gitw

Stateless "where am I" for git. One read that answers, in a single call, the orientation questions an agent otherwise discovers with a status+branch+rev-parse+fetch+log dance: which repo/worktree/branch, detached or not, ahead/behind upstream, and how dirty. Read-only — never mutates.

Companion to gitx: gitx is the stateless write lane (commit to a branch with no checkout); gitw is the stateless read of local git state.

Install

ln -sf ~/src/gitw/gitw ~/bin/gitw   # needs `git` + python3 on PATH

Usage

gitw                 # one-line human summary of the current repo
gitw --json          # bare JSON object (pipe to jq)
gitw -C <dir>        # report on <dir> instead of cwd
gitw --fetch         # git fetch first so ahead/behind reflect the remote
gitw --usage         # {calls, ok, fail} from ~/.gitw/usage.jsonl

JSON fields

{ repo, root, is_worktree, branch, detached, head, upstream,
  ahead, behind, dirty, staged, unstaged, untracked, default_branch }

ahead/behind are relative to the branch's own upstream (@{u}), not the default branch — and only as fresh as the last fetch; pass --fetch to refresh from the remote first (fail-soft: a failed fetch warns on stderr and reports local state). Exit 3 (stderr) when not inside a git repo.

Test

python3 -m pytest test_gitw.py -q