gites 0.5.2

Deterministic local multi-repo checkpointing for repo families.

Gites

Gites is a local-first command line tool for deterministic multi-repo checkpointing.

It is designed for a root directory that contains many Git repositories. Gites previews repo state, refuses unsafe repositories, commits with an explicit deterministic message, pushes safely, and records each run in a local ignored ledger.

Install

pip install gites

For local development:

pip install -e .

Simple Workflow

Register the current directory as a repo root:

cd ~/All_github_repo
gites init

Or register a Windows-mounted repo root from WSL:

gites init /mnt/c/Documents/All_github_repo --name win --branch main

List saved roots:

gites dirs

Switch active root:

gites use win

Show the current repo-state table for a saved root:

gites view
gites view win

Preview what would be pushed:

gites push

Apply with a deterministic commit message:

gites push -m "chore: checkpoint repo family 2026-05-11"

The saved directory config lives outside the repo at ~/.config/gites/config.json.

Explicit Workflow

Preview repositories under a root directory:

gites plan --root ~/All_github_repo --branch main

Dry-run a checkpoint:

gites sync --root ~/All_github_repo --branch main --dry-run

Apply a checkpoint with an explicit commit message:

gites sync --root ~/All_github_repo \
  --branch main \
  --apply \
  --message "chore: checkpoint repo family 2026-05-10"

Read local run ledgers:

gites ledger list --root ~/All_github_repo
gites ledger show RUN_ID --root ~/All_github_repo

Ledgers are written under .gites/ledgers/ inside the selected root. That directory is intentionally ignored by Git.

Safety Rules

gites sync --apply refuses a repository when it detects:

• detached HEAD
• merge, rebase, cherry-pick, or revert in progress
• unresolved conflicts
• wrong branch
• missing origin
• missing upstream branch
• branch behind upstream
• branch diverged from upstream
• protected path changes such as .env, secrets/, private/, or internal/
• changed files larger than the configured size limit
• missing commit message in apply mode

Gites never force-pushes by default.

Manifest Files

Real manifests should stay local and ignored, for example my_gites.json or gites.local.json.

Create a local template:

gites config init my_gites.json

Validate a manifest:

gites config validate my_gites.json

Use a family from a manifest:

gites sync --manifest my_gites.json \
  --family default \
  --dry-run

A sanitized public example is available at examples/example.gites.json.

Development

Run tests:

python -m unittest discover -v

Privacy

Do not commit real manifests, ledgers, credentials, ChatGPT exports, private notes, or local editor state. The repository .gitignore blocks the intended local-only paths.