DiffKeeper (diffk) — Git‑powered AI Session Workflow

DiffKeeper wraps Git into a safe, automatable workflow for AI‑assisted changes: initialize a session, commit in small steps, optionally squash, and merge back cleanly. A single CLI binary diffk exposes JSON‑first commands designed for agents.

Commands

• status, init, commit, stage, squash, merge, end, abort, help, version, doctor

Highlights

• Session: init on a new/current branch; idempotent --if-missing; dirty policy commit|stash|block|keep; optional pre‑push hook; no upstream by default.
• Commit: auto git add -A (or --paths), --message-file, --allow-empty.
• Stage (index‑only): apply unified diff hunks to the index; internal pre‑check; --check-only; 3‑way/unidiff‑zero/recount; no working‑tree edits.
• Merge back: squash|no-ff|ff-only; --dry-run conflict check; custom message via --message/--message-file.
• End/Abort: safe branch deletion (-d by default); --force-delete for -D.
• Automation ready: --output json, --debug, --timeout; stable error codes; process lock at .git/diffkeeper/lock.

90‑Second Quickstart

# 1) Ensure a session (idempotent)
diffk init --mode=new-branch --source main --if-missing --dirty commit --output json
# If switching source with a dirty worktree
diffk init --mode=new-branch --source main --if-missing --dirty stash --output json

# 2) Commit changes
diffk commit --title "AI: update" --output json

# (Optional) Stage selected hunks via patch
diffk stage --stdin --check-only --output json < patch.diff
if [ $? -eq 0 ]; then diffk stage --stdin --output json < patch.diff; fi

diffk commit --title "AI: apply selected hunks" --output json

# 3) Merge & finish
diffk merge --to main --strategy=squash --dry-run --output json
# if ok
diffk merge --to main --strategy=squash --message "Squash: session" --output json
diffk end --output json

Install / Build

• Build: go build ./cmd/diffk (Go 1.22+, Git 2.30+)
• If cache paths are restricted: mkdir -p .gocache .gopath/pkg/mod && GOCACHE=$(pwd)/.gocache GOPATH=$(pwd)/.gopath GOMODCACHE=$(pwd)/.gopath/pkg/mod go build ./cmd/diffk

Documentation

• User/Agent Guide: usage.md (English), usage.zh.md (中文)
• Detailed Usage: usage-detailed.en.md (English), usage-detailed.zh.md (中文)
• Automation Guide: automation.md (English), automation.zh.md (中文)
• In‑CLI help: diffk help, diffk help <command>, or add --output json for structured help

Notes

• Provide a .gitignore at repo root (auto snapshot and commit follow .gitignore).
• Commands are serialized with a process lock; concurrent runs return LOCKED.
• Optional pre‑push hook (init --install-hooks) blocks pushing diffkeeper/* (override with DIFFKEEPER_ALLOW_PUSH=1).