---
title: Private Git Config
description: The dot-git.yml schema for repository shortcuts, updates, activity, notifications, and agent lint opt-ins.
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.

Set `agent_oxlint: true` only for an external TypeScript or JavaScript repository that should receive the personal generic Oxlint pass without owning its configuration:

```yaml
- name: "[HA] Frontend"
  path: ~/repos/home-assistant/frontend
  github: home-assistant/frontend
  agent_oxlint: true
```

`dot agent-oxlint` checks this opt-in before preparing its cache. It also skips a repository that already has an Oxlint config, dependency, script, or local binary, so repository-owned linting always takes precedence. The personal pass extends the published generic config and can lower selected rules to advisory warnings without changing the shared package. Only diagnostics on added or modified diff lines are candidates for fixes. Personal repositories should install [`@timmo001/oxlint-rules`](https://github.com/timmo001/oxlint-rules) directly instead of using this opt-in.

- `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 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.