Deutsche Version

Back to overview

git-sync-all: Technical details

File layout

git-sync-all/
├── bin/git-sync-all           Entry point
├── lib/
│   ├── core.sh                Strict mode, logging, colors, lock, cleanup
│   ├── config.sh              Defaults, config loading, validation, --init-config
│   ├── cli.sh                 Arguments, help, version, alias
│   ├── repo-discovery.sh      Repository search, filters, remote check
│   ├── git-ops.sh             Git operations, dry-run wrapper
│   ├── sync.sh                Sync flow, prompts, status, summary
│   ├── inventory.sh           repos.yml, --verify, cleanup, --init-inventory
│   └── issues.sh              GitHub issues via gh
├── config/
│   ├── config.conf.example
│   └── repos.yml.example
├── tests/                     Test scripts
├── Makefile                   install, uninstall, link, test, lint, format
└── install.ps1                Windows installer

Execution order

graph TD
    A[parse_args] --> B[load_config]
    B --> C[apply_cli_overrides]
    C --> D[setup_environment: colors, git check, lock]
    D --> E{Mode}
    E -->|--verify| F[parse_inventory and verify_inventory]
    E -->|--issues| G[parse_inventory and show_issues]
    E -->|default| H[discover_repos]
    H --> I{--status?}
    I -->|yes| J[show_status]
    I -->|no| K[sync_all]
    J --> L[print_summary]
    K --> L
    L --> M{Failed greater than 0?}
    M -->|yes| N[Exit 1]
    M -->|no| O[Exit 0]

--help, --version, --init-config, --setup-alias and --init-inventory already end the tool inside parse_args. The lock is acquired before every mode, so also for --status, --verify and --issues.

Modules

Design decisions

• Subshells: Every function in git-ops.sh does its cd into the repository in a subshell. The working directory of the main process is never changed.
• Dry-run wrapper: Write commands go through git_cmd, which only prints [DRY-RUN] Would: git ... in a dry run. Read commands always run. Because sync_repository runs inside a command substitution per repository and some calls discard stderr, the lines are only visible for git add and git commit.
• Conflict detection: The tool compares git status --porcelain with git diff --name-only HEAD..<upstream> and reports files that appear in both lists.
• Lock file: Contains the PID. At startup kill -0 checks whether the process is alive. A cleanup trap on EXIT, INT and TERM removes it again. flock is not used. The path is fixed before the check, so a second instance that exits because of the first one also deletes the first instance's lock file.
• Config via source: There is no parser of its own. Shell variables work in the config, but the file is executed.
• Output: --help and --version write to stdout, all other user output goes to stderr. Only internal intermediate values (per-repository result, statistics strings) travel via stdout.
• q in prompts: exit 0 runs inside the command substitution of sync_all and only ends that subshell. The repository counts as Failed.

Tests and CI

make test starts tests/run-tests.sh, which runs all tests/test-*.sh files. The tests cover CLI parsing, config, repository discovery, Git operations, conflict handling, the inventory and the Windows installer. make lint runs ShellCheck, make format checks with shfmt -i 4 -ci -bn, and make check runs everything together. The GitHub Actions pipeline runs ShellCheck, shfmt, PSScriptAnalyzer for install.ps1 and the tests on Ubuntu and Windows.