git-sync-all: Usage
Invocation, all options, status table, dry run, cron operation, exit codes and output format of git-sync-all with verified examples.
git-sync-all: Usage
Invocation
git-sync-all [OPTIONS] [DIRECTORY...]
Without arguments the tool scans the directories in SYNC_BASE_DIRS (default ~/projekte). Directories passed as arguments replace SYNC_BASE_DIRS for that run. Short options cannot be combined: -vv is rejected as an unknown option.
Options
| Option | Short | Effect |
|---|---|---|
--help |
-h |
Show help and exit |
--version |
-V |
Show version and exit |
--dry-run |
-n |
Do not run write operations (see the Dry run section) |
--verbose |
-v |
Debug output (SYNC_VERBOSITY=2) |
--quiet |
-q |
No info, warning and OK messages (SYNC_VERBOSITY=0) |
--yes |
-y |
Confirm all prompts automatically |
--config FILE |
-c |
Load a different config file |
--init-config |
Create the config file at the XDG path | |
--setup-alias |
Create the git alias check |
|
--no-pull |
No fetch and no pull | |
--no-push |
No push | |
--no-tags |
Skip tag synchronization | |
--no-commit |
Do not commit | |
--no-color |
No colors | |
--conflict-strategy VALUE |
skip, stash or commit |
|
--status |
Status table only, no sync actions | |
--verify |
Verify the inventory (see Inventory) | |
--issues |
Show open GitHub issues for inventory repositories | |
--inventory FILE |
Use a different inventory file | |
--group NAME |
Filter inventory group, repeatable | |
--init-inventory |
Create the inventory file at the XDG path | |
--exclude PATTERN |
Exclude repositories by directory name, repeatable | |
--include PATTERN |
Only sync matching repositories, repeatable |
--exclude and --include replace the values of SYNC_EXCLUDE and SYNC_INCLUDE from the config. See the notes on precedence for --yes, --no-tags, --no-color and --conflict-strategy.
Examples
git-sync-all
git-sync-all ~/work ~/personal
git-sync-all --dry-run
git-sync-all --status
git-sync-all --exclude vendor --exclude "test-*"
git-sync-all --include "api-*"
git-sync-all --no-commit --no-push
git-sync-all --no-pull
git-sync-all --config ~/.config/git-sync-all/cron.conf
--include and --exclude compare the repository directory name (not the path) with Bash glob patterns. The include filter applies first, then the exclude filter.
Dry run
In a dry run the tool does not execute git add, commit, pull, push, stash or the tag fetch. Only git add and git commit are visible as [DRY-RUN] Would: git ...; the output for tag fetch, stash, pull and push is suppressed. Read-only commands really run, including git status and a git fetch <remote> <branch> that updates the remote-tracking references.
In a dry run, repositories with changes are still reported as
Synced, and the prompts are still asked. Only the writes are skipped.
Status table
REPOSITORY BRANCH DIRTY UNPUSHED UNPULLED
--------------------------------------------------------------------------------
invoice-management main 3 2 --
DIRTY counts the lines of git status --porcelain, UNPUSHED the commits ahead of the upstream. UNPULLED always shows -- because status mode does not fetch. The tool then also prints the summary. Its Clean counter equals the number of repositories without changes.
Output
--help and --version write to stdout. All other output goes to stderr and stdout stays empty. Messages carry the prefixes [INFO], [WARN], [OK], [ERROR], [DEBUG] and [DRY-RUN]. The run ends with a summary of the counters Total, Clean, Synced, Skipped and Failed. -q suppresses info, warning and OK messages. Errors, prompts and the summary are still shown.
Aborting with q
If you answer a prompt with q, the tool prints Aborted by user but ends only the handling of that one repository. It counts as Failed, the remaining repositories are still prompted and processed, and the final exit code is 1. To really stop a run, interrupt it with Ctrl+C.
Exit codes
| Code | Meaning |
|---|---|
0 |
Run without failed repositories, even if some were skipped or none were found. |
1 |
At least one repository failed (commit, pull, stash or push, including an abort with q). Also: config error, unknown option, second instance running, missing git, missing repositories with --verify, and repositories with open issues with --issues. |
Unattended operation (cron)
Without --yes and without a terminal the tool skips every repository with changes and reports it as Skipped. For cron you therefore need a config with SYNC_AUTO_CONFIRM=true that you pass with --config.
# ~/.config/git-sync-all/cron.conf contains SYNC_AUTO_CONFIRM=true
0 18 * * 1-5 /usr/local/bin/git-sync-all --config $HOME/.config/git-sync-all/cron.conf --quiet 2>> $HOME/.local/log/git-sync.log
Output goes to stderr, so redirect with 2>> into the log file. Cron needs access to your credentials (SSH agent, credential helper), otherwise pull and push fail. Read the security notes first: in auto mode changes are committed and pushed without asking.
Multi-machine routine
git-sync-all # end of day: commit and push
git-sync-all --verify # new machine: find missing repositories
git-sync-all # start of day: fetch changes
What happens per repository is described under Sync workflow.