git-sync-all: Configuration

All git-sync-all configuration variables with defaults, validation, commit message placeholders and the actual precedence of CLI flags, environment and config file.

Deutsche Version

Back to overview

git-sync-all: Configuration

Config file

The path is ${XDG_CONFIG_HOME:-$HOME/.config}/git-sync-all/config.conf. Use --config FILE to load a different file. If the given file does not exist, the tool silently continues with the defaults.

git-sync-all --init-config

The command copies the example file config/config.conf.example to the XDG path. If the example file is missing (copy installation) it writes a short built-in configuration. The built-in variant does not set SYNC_CONFLICT_STRATEGY or SYNC_COMMIT_BODY. If the file already exists the command changes nothing.

The config file is a shell script and is loaded with source. Everything in it is executed. Keep it in a place where nobody but you has write access.

Variables

Variable	Default	Description
`SYNC_BASE_DIRS`	`$HOME/projekte`	Directories to scan, separated by colons. Every directory must exist.
`SYNC_SCAN_DEPTH`	`3`	Search depth below each base directory. `1` means direct subdirectories only. Integer, 1 or higher.
`SYNC_EXCLUDE`	empty	Directory names of repositories to skip. Colon-separated glob patterns.
`SYNC_INCLUDE`	empty	If set, only repositories whose directory name matches are synced.
`SYNC_COMMIT_MSG`	`chore: auto-sync from {hostname}`	Commit message template (placeholders below).
`SYNC_COMMIT_BODY`	`Automatic synchronization of uncommitted changes.`	Second paragraph of the commit message. Only an explicit empty assignment in the config file removes the body. An empty environment variable falls back to the default again.
`SYNC_AUTO_CONFIRM`	`false`	`true` answers all prompts automatically (same as `--yes`).
`SYNC_PULL_STRATEGY`	`rebase`	`rebase` (`git pull --rebase`) or `merge` (`git pull`). Other values are an error.
`SYNC_TAGS`	`true`	Fetch tags per repository with `git fetch --tags --prune-tags`.
`SYNC_REMOTE`	`origin`	Remote name. Repositories without this remote are skipped.
`SYNC_CONFLICT_STRATEGY`	`skip`	Behaviour in auto mode when changes overlap: `skip`, `stash` or `commit`.
`SYNC_INVENTORY_FILE`	empty	Path to `repos.yml`. Empty means the XDG path `${XDG_CONFIG_HOME:-$HOME/.config}/git-sync-all/repos.yml`.
`SYNC_VERIFY_GROUP`	`all`	Default group for `--verify` and `--issues`. Separate several groups with commas.
`SYNC_GITHUB_USER`	empty	GitHub user name used for the clone hints of `--verify`. If unset, the tool asks `gh api user`.
`SYNC_COLOR`	`auto`	`auto` (terminal only), `true`/`yes`/`on`/`always` or `false`/`no`/`off`/`never`.
`SYNC_VERBOSITY`	`1`	`0` quiet, `1` normal, `2` debug. Other values are an error.

SYNC_GITHUB_USER is not in the example file but is read from the config or the environment.

Validation

At startup the tool checks that every directory in SYNC_BASE_DIRS exists, SYNC_PULL_STRATEGY is rebase or merge, SYNC_VERBOSITY is 0, 1 or 2, SYNC_SCAN_DEPTH is a positive integer and SYNC_CONFLICT_STRATEGY is skip, stash or commit. On a violation the tool stops with Config error: ... and exit code 1.

Example

SYNC_BASE_DIRS="$HOME/projekte:$HOME/work"
SYNC_SCAN_DEPTH=3
SYNC_EXCLUDE="vendor:node_modules"
SYNC_COMMIT_MSG="chore: auto-sync from {hostname} on {date}"
SYNC_PULL_STRATEGY="rebase"
SYNC_AUTO_CONFIRM=false

Commit message placeholders

Placeholder	Replaced with
`{hostname}`	Output of `hostname`
`{date}`	Current date as `YYYY-MM-DD`
`{repo}`	Name of the current working directory you start the tool from

{repo} is not the name of the repository being synced but the directory you invoked git-sync-all from. In addition, the current code appends a stray } to every automatically generated commit message (for example chore: auto-sync from workstation}). This applies to the default template and to templates from the config file. If you set SYNC_COMMIT_MSG only as an environment variable and not in the config, there are even two (}}).

Precedence

The real order depends on which source sets the variable.

Setting	Who wins
Directory arguments, `--include`, `--exclude`, `-v`, `-q`	Always the command line
`--yes`, `--no-tags`, `--no-color`, `--conflict-strategy`	The command line, but only if the config file does not set the variable itself
Environment variables (`SYNC_...`)	The environment, but only if the config file does not set the variable itself
Config file	Overrides the built-in defaults

The file copied from config/config.conf.example explicitly sets SYNC_AUTO_CONFIRM, SYNC_TAGS, SYNC_COLOR and SYNC_CONFLICT_STRATEGY, among others. With that file, --yes, --no-tags, --no-color and --conflict-strategy have no effect and same-named environment variables are overridden. The built-in fallback configuration of a copy installation also sets SYNC_AUTO_CONFIRM, SYNC_TAGS and SYNC_COLOR, but not SYNC_CONFLICT_STRATEGY. Comment those lines out, or keep a separate file for cron runs and pass it with --config.

--no-pull, --no-push, --no-commit and --dry-run are command-line switches without a config variable and always take effect.

Multiple configurations

git-sync-all --config ~/.config/git-sync-all/work.conf ~/work
git-sync-all --config ~/.config/git-sync-all/cron.conf

See Usage for all options and Security for notes on how the config is loaded.