cli git wraps common local git workflows. Commit message defaults to ..

Core commands:

Pattern:

1. Read (src/internal/read/) — worktree snapshot, no prompts
2. Write gate (src/internal/write/gate.py) — prints --- cli write gate --- with repo context, then asks to proceed
3. Write — mutation runs only after --yes or interactive confirmation

Read-only commands (review, docs, branch list, stash list) skip the gate.

Operations that mutate remote state or discard local work require confirmation:

No confirmation needed:

• git commit
• git start --no-prep (creates branch from current state)
• git pull
• git stash push/list/apply/pop

Default (issue workflow — align main + branch):

cli git start issue-9-docker --yes

Branch from the current working tree without reset/clean:

cli git start my-feature --no-prep

cli git reset --yes              # checkout main, fetch, pull, clean
cli git reset --yes --delete-merged  # sync main + delete merged branches
cli git reset --yes --main-only  # sync main only (skip branch prompt)
cli git reset --yes --discard    # drop uncommitted work on current branch

On a feature branch with uncommitted edits, reset commits with . (or -m) before checking out main. Then it fetches upstream / fork / origin, hard-resets main to the newest tip among those refs, and cleans the worktree.

git pull on main does the same sync. On a feature branch it merges tracking upstream (when set) and the newest main tip.

cli git push              # interactive: branch summary → add + commit + push
cli git push --yes        # non-interactive
cli git commit -m "wip"   # commit only (no push)

push shows a write gate with branch, dirty state, commit message, and intent before running:

On main with origin, an interactive cli git push asks whether to push directly to main before starting a generated wip-* branch. Non-interactive runs keep the wip-branch default unless you pass --allow-main.

Before the write gate, push may surface warnings (informational; they do not block unless you decline the gate):

cli git push --yes --format json   # structured result: branch, pushed, remote, warnings, …

The no-remote case avoids failing late after staging/committing. Add a remote and rerun cli git push --yes when you are ready to publish.

branch delete --merged removes branches merged into main (lists local + remote in the prompt):

cli git branch delete --merged
cli git branch delete --merged --yes

branch delete --all deletes every branch except main, including unmerged work (local + remote):

cli git branch delete --all
cli git branch delete --all --yes

branch clear resets the working tree, then deletes all local branches except main:

cli git branch clear

1. Write gate — confirms hard reset + clean, checkout main, delete every local branch except main (lists branches in the prompt).
2. Second prompt — optionally delete all remote branches on origin except main (default: keep remotes).

Non-interactive full wipe:

cli git branch clear --yes --delete-remote

Single-repository only (run from the repo you want to tag).

Put config/tag.yaml in the target repo, or let the CLI detect the pattern from existing tags:

Optional keys: bump (patch | minor | major), require_increase: true (reject tags ≤ latest).

This repo (config/tag.yaml): semver-v, patch bump, require_increase: true.
cli git tag with no name auto-suggests the next tag (e.g. v0.1.0 → v0.1.1).

PR CI runs cli pypi version check — pyproject.toml version must be greater than main.

cli pypi version suggest      # next package version (patch)
cli pypi version tag-suggest  # next git tag for current repo
cli pypi version check        # compare HEAD vs origin/main

cli git tag                    # sync main, suggest next vX.Y.Z, push to origin
cli git tag v0.1.1             # explicit release tag
cli git tag list               # local + remote tags (sorted)
cli git tag push               # push latest local tag to origin
cli git tag push v0.1.1 --yes --force   # force-push when remote differs
cli git zip                    # zip latest local tag → git-tags/REPO/
cli git zip v0.1.1 -o out.zip

tag syncs main first, creates the next tag greater than the latest (per config/tag.yaml), then pushes to origin when configured. zip always archives the latest local tag unless you pass a name. Subcommands: list, push (--force), and explicit tag names still work.

See ci-workflows.md for the standard trio: test.yml (PR build/test) → deploy.yml (main → tag) → release.yml (tag → GitHub Release artifacts).

When main has commits not covered by the latest policy tag and there are no open PRs, create and push the next tag:

cli git deploy --status     # read-only: main vs tag + open PR count
cli git deploy --dry-run    # same as --status
cli git deploy              # interactive write gate
cli git deploy --yes        # CI / automation

Push to main can trigger deploy via external CI, which calls cli git deploy --yes. Open PRs block deploy unless you pass --skip-pr-check.

For multi-repo zip inventory and bulk ingest, use cli drive ingest.

Debug tests: cli test python unit . (fast host pytest) · cli test python integration . (tags + Docker unit + integration).

cli git review

Runs command-surface checks; without --quick, also cli test python unit .. No commit or push. Use cli git review --quick when full unit checks are unavailable.

No write gate:

cli git branch current
cli git diff stat --base upstream/main
cli git diff names --base "$BASE_GIT"
cli git log oneline --base "$BASE_GIT"
cli git log messages --base "$BASE_GIT" --max-count 30
cli git rev-list count --base "$BASE_GIT"
cli git remote url upstream
cli git rev parse HEAD
cli git merge-base check --base "$BASE_GIT"
cli git publish check --remote origin --branch feature-x

cli git docs

Lists markdown paths for sync. In-place edits use cli git docs.