git-sync

Context and purpose

git-sync grew from the need to keep many GitHub repositories orderly inside one local directory. It combines finding missing repositories, safely advancing outdated branches, and gathering shared Git configuration into one workflow.

The tool does not try to force every repository to the same state. Local work, diverged history, and broken repositories are made visible; decisions that risk data loss or automatic merging are not made without user confirmation.

How it works

The workflow has four stages. It first audits repositories in the target directory and reports broken ones. It then clones repositories available through GitHub CLI but missing locally. The update stage advances eligible branches with fast-forward operations, and the final stage aggregates gitignore and gitattributes rules into shared output files.

Before work begins, the tool validates Git, GitHub CLI, authentication, and the target directory. A dry-run can show planned cleanup, cloning, updating, and merging without changing files. Results are summarised in the terminal and can be exported as JSON.

System design

The application is split into Core, Application, and Infrastructure layers. Core holds options, result models, and service contracts. Application contains the orchestrator, validators, and workflow steps. Infrastructure implements Git, GitHub CLI, the filesystem, process execution, and Spectre.Console interaction.

That separation avoids binding Git commands and file access directly to workflow rules. Tests mock processes, filesystem access, and user interaction, allowing decisions to be tested without a live GitHub account or working directory.

Key technical decisions

The active tracking branch is updated only when fast-forward is possible. Other branches are checked for ancestry before their references advance, and diverged histories are never merged automatically. The tool refuses to trade convenience for losing local work.

Cloning and updates can run concurrently, but bounded parallelism keeps network and disk use under control for large repository sets. Submodules are handled when their parent repository changes.

Broken-repository cleanup and output-producing merge steps are visible through dry-run. Preview mode is therefore a safety boundary for a workflow that can otherwise be destructive, not merely a reporting option.

Validation and limits

Unit tests cover validation, broken-repository detection, cloning, updating, dry-run behaviour, and configuration merging. Process results and timeout handling can also be controlled through the abstraction layer.

The tool is not a general merge-conflict resolver. Local changes, detached HEAD, permission issues, and diverged branches are not resolved automatically. It requires Git, GitHub CLI, and an authenticated GitHub session, and should not be run with elevated privileges.