Configuration

The configuration file is stored at $XDG_CONFIG_HOME/autogitter/config.yaml (typically ~/.config/autogitter/config.yaml).

Modular Configuration with sources.d

For better organization, you can split your sources across multiple files in the sources.d directory:

~/.config/autogitter/
├── config.yaml          # Main config (required)
└── sources.d/           # Additional source files (optional)
    ├── github.yaml
    ├── work.yaml
    └── personal.yaml

Each file in sources.d/ uses the same format as the main config:

# ~/.config/autogitter/sources.d/work.yaml
sources:
  - name: "Work Bitbucket"
    source: bitbucket.company.com/~username
    strategy: all
    type: bitbucket
    local_path: "~/Git/work"

Rules: - Main config.yaml must exist - Files are loaded in alphabetical order - Only .yaml and .yml files are processed - Sources from all files are merged together - Not supported for remote configs (HTTP/SSH)

Config Format

sources:
  # Manual strategy - explicitly list repos
  - name: "GitHub (Personal)"
    source: github.com/username
    strategy: manual
    local_path: "~/Git/github"
    repos:
      - username/repo1
      - username/repo2

  # All strategy - sync all repos from user/org
  - name: "GitHub (All)"
    source: github.com/username
    strategy: all
    local_path: "~/Git/github-all"

  # Regex strategy - filter repos by pattern
  - name: "APIs Only"
    source: github.com/myorg
    strategy: regex
    local_path: "~/Git/apis"
    regex_strategy:
      pattern: "^myorg/api-.*"

  # Gitea with explicit type
  - name: "Work Gitea"
    source: gitea.company.com/myuser
    strategy: all
    type: gitea
    local_path: "/work/git"

  # Bitbucket Server with SSH options
  - name: "Bitbucket"
    source: bitbucket.company.com/~username
    strategy: all
    type: bitbucket
    local_path: "~/Git/bitbucket"
    ssh_options:
      port: 7999
      private_key: "~/.ssh/work_ed25519"

Fields

Field	Required	Description
`name`	Yes	Display name for the source
`source`	Yes	Git host and user/org (e.g., `github.com/username`)
`strategy`	Yes	Sync strategy: `manual`, `all`, `regex`, or `file`
`type`	No	Provider type: `github`, `gitea`, `bitbucket` (auto-detected from host if omitted)
`local_path`	Yes	Where to clone repos (supports `$HOME`, `~`)
`repos`	For manual	List of repos to sync (strings or objects with `name` and optional `local_path`)
`regex_strategy`	For regex	Regex pattern configuration
`branch`	No	Branch to clone (uses remote default if not set)
`private_key`	No	Path to SSH key for this source (legacy, prefer `ssh_options`)
`ssh_options`	No	SSH configuration (port, private key)

SSH Options

Configure SSH behavior per source using the ssh_options block:

ssh_options:
  port: 7999                          # Custom SSH port
  private_key: "~/.ssh/work_ed25519"  # Path to SSH private key
  submodules: true                    # Recurse submodules on clone & pull

Fields

Field	Type	Description
`port`	int	Custom SSH port. When set, autogitter uses `ssh://git@host:port/repo.git` URL format instead of `git@host:repo.git`
`private_key`	string	Path to SSH private key for this source. Supports `~` and environment variables. Used for clone, pull, and submodule operations
`submodules`	bool	When `true`, clones with `--recurse-submodules` and runs `git submodule update --init --recursive` after each pull

Custom Port

For self-hosted instances with non-standard SSH ports (common with Bitbucket Server):

- name: "Bitbucket Server"
  source: bitbucket.company.com/~username
  type: bitbucket
  strategy: all
  local_path: "~/Git/work"
  ssh_options:
    port: 7999

Private Key

Specify a per-source SSH key for private repositories:

- name: "Work"
  source: github.com/myorg
  strategy: all
  local_path: "~/Git/work"
  ssh_options:
    private_key: "~/.ssh/work_ed25519"

The key is passed via GIT_SSH_COMMAND with -o IdentitiesOnly=yes so only the specified key is used.

Submodules

Enable recursive submodule support for sources with repos that use git submodules:

- name: "Projects"
  source: github.com/myorg
  strategy: manual
  local_path: "~/Git/projects"
  ssh_options:
    private_key: "~/.ssh/id_ed25519"  # also used for submodule fetches
    submodules: true
  repos:
    - myorg/project-with-submodules

When submodules: true:

Clone: runs git clone --recurse-submodules, initializing all submodules during clone
Pull: after git pull, runs git submodule update --init --recursive to sync submodule state

The same SSH key (if configured) is used for submodule operations, so private submodule URLs work correctly.

Strategies

Manual

Explicitly list repositories to sync:

strategy: manual
repos:
  - user/repo1
  - user/repo2
  - org/project

Per-Repo Local Path

Individual repos can override the source's local_path to clone to a custom location. This is useful for dotfiles or config repos that belong in a specific directory:

strategy: manual
local_path: "~/Git/github"
repos:
  - user/repo1                        # cloned to ~/Git/github/repo1
  - name: user/tmux-conf              # cloned to ~/.config/tmux
    local_path: "~/.config/tmux"
  - name: user/nvim-config            # cloned to ~/.config/nvim
    local_path: "~/.config/nvim"

Both plain strings and objects are supported in the repos list. Repos with a custom local_path are excluded from orphan detection in the source directory. If the target path already exists but is not a git repo, autogitter will warn and skip it.

Best for: Curated lists of specific repos you want to track.

All

Sync all repositories from a user/organization. Requires API authentication.

strategy: all

This fetches all non-archived repositories from the specified user or organization.

Best for: Backing up all your repos or keeping a local mirror.

Regex

Sync repositories matching a regex pattern. Requires API authentication.

strategy: regex
regex_strategy:
  pattern: "^myorg/api-.*"  # matches repos starting with "api-"

The pattern is matched against the full repository name (e.g., username/repo-name).

Examples: - ^user/.* - All repos from user - .*-service$ - Repos ending with "-service" - ^org/(api|web)-.* - Repos starting with "api-" or "web-"

Best for: Syncing a subset of repos based on naming conventions.

File (Coming Soon)

Sync repositories containing a specific file:

strategy: file
file_strategy:
  filename: ".autogitter"

Provider Types

Autogitter auto-detects the provider from the host:

Host	Detected Type
`github.com`	`github`
`bitbucket.org`	`bitbucket`
Other	`gitea` (default)

For self-hosted instances, specify type explicitly:

- name: "Self-hosted Bitbucket"
  source: scm.company.com/~username
  type: bitbucket  # Required for self-hosted
  strategy: all
  local_path: "~/Git/work"

Authentication

The all and regex strategies require API tokens. Set up authentication with:

ag connect

Tokens are stored in $XDG_DATA_HOME/autogitter/credentials.env.

Environment Variables

Provider	Environment Variable
GitHub	`GITHUB_TOKEN`
Gitea	`GITEA_TOKEN`
Bitbucket	`BITBUCKET_TOKEN`

You can also export these directly:

export GITHUB_TOKEN=ghp_xxxx
ag sync

Remote Configs

Load configuration from remote sources using the -c flag:

HTTP/HTTPS

ag sync -c https://example.com/config.yaml
ag config -v -c https://raw.githubusercontent.com/user/repo/main/config.yaml

SSH

ag sync -c user@host:/path/to/config.yaml
ag sync -c ssh://user@host/path/to/config.yaml

Remote configs can be used with sync and config --validate, but cannot be edited.

Environment Variable Expansion

Paths support environment variable expansion:

$HOME or ~ - User's home directory
$XDG_CONFIG_HOME - XDG config directory
Any other environment variable

local_path: "$HOME/Git/repos"
local_path: "~/Git/repos"
local_path: "/data/$USER/repos"

Custom Config Path

Use a custom config file:

ag sync -c /path/to/config.yaml
ag sync -c ~/dotfiles/autogitter.yaml