gitman

name	gitman
description	Route ALL version control through gitman (jj + colocated git). Never run raw jj/git.

Gitman — version control for this repo

Run every version-control action through gitman (inside the devenv shell). Raw jj/git edits break canonicity and force a gitman reconcile.

Scope & coordination

gitman owns version control only. For cross-phase, cross-manager ordering across the repo's whole lifecycle (spec → scaffold → change → verify → save → docs), defer to the repoman skill — the repoman entrypoint sequences the managers and routes the VC steps here. Within version control, gitman is authoritative.

Bootstrapping a repo

gitman init --colocate is the one-command front door: it colocates jj onto this directory's git — adopting an existing .git (importing its history, keeping uncommitted work on @) or creating a fresh one — and then freezes trunk. Pick the path by repo state:

• Existing git repo with history (e.g. an "Initial commit" + uncommitted edits):

  gitman init --colocate --trunk main     # adopts the .git; trunk reuses the existing branch
  gitman start <name>                      # adopts the uncommitted work into a lane
  gitman save -m "<message>"
  

  No seed needed — trunk already has a commit.

• Fresh / empty repo (no commits yet):

  gitman init --colocate --trunk main      # creates the colocated git + trunk bookmark at @
  gitman seed -m "Initial commit"          # describes the working copy as trunk's first commit
  

  seed is one-shot and refuses once trunk has any history.

(Without --colocate, gitman init assumes the workspace is already colocated; if it isn't, it tells you to colocate first.)

The lane loop

A lane is one unit of work: a named bookmark (= git branch) on trunk, kept linear.

gitman start <name>         # begin a lane (add --workspace to isolate it in its own dir)
# ...edit files...
gitman save -m "<message>"  # describe the current change
gitman status               # see trunk + all lanes (canonical or off-canonical)
gitman sync                 # fetch trunk + rebase this lane onto it
gitman publish              # push the lane (branch = lane name); verify hook runs first
gitman land [<lane>...]     # fold lane(s) into trunk, advance trunk, retire the lane(s)
gitman abandon [<lane>]     # discard a lane

Safety net

• gitman undo reverts the last intent (whole-intent, via jj's op-log). gitman undo --list shows recent ops; gitman undo --op <id> restores any of them.
• gitman resolve [--list] surfaces conflicts. Conflicts are not blocking — keep working and resolve later (jj records conflicts in commits).
• gitman reconcile is the one recovery path when status says OFF-CANONICAL: it adopts stray changes into lanes (or --abandon discards them).

Versioning

gitman version                       # show current version
gitman version bump <major|minor|patch>
gitman release [<level>|--version X.Y.Z]   # (bump →) tag vX.Y.Z → push tag

This repo's version lives at: not configured — add a [version] section to gitman.toml to enable version/release

Exit codes

0 ok · 1 a VC decision is needed (conflict / push rejected / verify blocked / off-canonical) · 2 infra/config · 3 invalid usage. Pass --json for structured output.