---
title: Private Git Config
description: The dot-git.yml schema for repository shortcuts, updates, activity, and notifications.
sidebar:
  order: 3
---

The git and GitHub tooling reads a private YAML config that lists the repositories to track and how. It lives in the private overlay at `$DOTFILES_PRIVATE_DIR/dot-git.yml` by default (override with `DOT_GIT_CONFIG_FILE`).

It is consumed by `dot git-diff`, `dot git-notifications --bar-json`, `dot notes-capture-sync`, `dot stow`, `dot update`, and `dot doctor`.

## Per-repo keys

Each repo entry has two required sections, each with an explicit `enabled` flag and a 5-field cron `schedule`:

The optional `aliases` list generates Zsh repository shortcuts during `dot stow` and `dot update`. The same entries feed Herdr's repository picker alongside `~/` and `~/repos`. Inside Herdr, a shortcut changes directory in the current tab when it already belongs to the repository workspace; otherwise it creates or focuses that workspace using the repository's `name`. Outside Herdr, it changes directory normally:

```yaml
- name: "[HA] Frontend"
  path: ~/repos/home-assistant/frontend
  aliases: [haf]
```

Top-level `shortcuts` use the same `name`, `path`, and `aliases` keys for directories that are not managed repositories, such as the private dotfiles checkout or a repository group directory.

Open the Herdr picker with `prefix+s`. Its cache is regenerated from validated `dot-git.yml` data by `dot stow` and `dot update`. The Home and Repos entries leave the workspace title unset.

An optional `post_update` command runs from the repository root when `dot update` successfully pulls that repo to a new HEAD. Use it for local generated artefacts that must match the checkout, such as rebuilding an unpacked browser extension:

```yaml
post_update: mise run build
```

The command does not run when the repo is already current or its pull is skipped. A failure or five-minute timeout stops the update so stale build output is not silently retained.

- `activity` — include the repo in `dot git-diff` and pull it during `dot update`.
- `notifications` — include the repo in GitHub notification checks and in the notes capture repository picker generated by `dot notes-capture-sync`.

`dot notes-capture-sync` finds the managed `timmo001/notes` checkout, mirrors the active Worker's non-secret variables and KV bindings into its ignored `capture/wrangler.local.jsonc`, and updates `vars.CAPTURE_REPOSITORIES`. Secret values are never written locally. When the live picker differs, the command deploys the capture Worker; `keep_vars` preserves dashboard-managed runtime variables and secrets on later Git-connected builds. Run it explicitly or from the Dot TUI when watched repositories change.

- `notifications` — include the repo in the notification inbox surfaces.

The `notifications.bar.ignore_bot_activity` key controls status-bar bot noise. A repo's `remote.upstream.url` lets upstream notifications match a managed fork.

:::note[Private by default]
`dot-git.yml` lives in the private dotfiles overlay because it contains a machine- and user-specific repository list. The public dotfiles only contain the logic that reads it.
:::

## Requirements

- `dot git-notifications` requires `gh` authenticated with a classic token carrying the `notifications` or `repo` scope.
- `dot doctor` verifies `dot-git.yml` and GitHub notification access.