Skip to content

usage.md

Latest commit

 

History

History
67 lines (55 loc) · 3.71 KB

usage.md

File metadata and controls

67 lines (55 loc) · 3.71 KB

DiffKeeper User & Agent Guide (English)

Task‑oriented usage for humans and automation. For full options, use diffk help <command> (add --output json for structured help).

Tip: In automation, default to --output json; add --debug for diagnostics.

Detailed guide: see usage-detailed.en.md for per-command usage, examples, and exit codes.

90‑Second Quickstart

  • Ensure session (idempotent)

    • On current work (auto snapshot):
      • diffk init --mode=new-branch --source main --if-missing --dirty commit --snapshot-message "Warmup snapshot" --output json
    • Switching source with dirty worktree:
      • diffk init --mode=new-branch --source main --if-missing --dirty stash --snapshot-message-file .snapshot-msg.txt --output json

  • Commit all or selected files

    • diffk commit --title "AI: update" --output json
    • diffk commit --title "AI: update" --paths "a,b" --output json

  • Selective (staged‑hunks via patch)

    • Pre‑check: diffk stage --stdin --check-only --output json < patch.diff
    • Apply: diffk stage --stdin --output json < patch.diff
    • Commit: diffk commit --title "AI: apply selected hunks" --output json

  • Merge & finish

    • Dry‑run: diffk merge --to main --strategy=squash --dry-run --output json
    • Merge: diffk merge --to main --strategy=squash --message "Squash: session" --output json
    • End: diffk end --output json

Quick Reference (core flags)

  • init --mode new-branch|current --source <branch> [--dirty commit|stash|block|keep] [--if-missing] [--snapshot-message "<msg>"|--snapshot-message-file <path>]
  • commit --title "<msg>" [--paths <p1,p2,...>] [--message-file <path>] [--allow-empty]
  • stage (--stdin | --patch-file <path>) [--check-only] [--three-way] [--unidiff-zero] [--recount] [--whitespace nowarn|warn|error] [--reverse]
  • merge --to <branch> --strategy squash|no-ff|ff-only [--dry-run] [--message "<m>"|--message-file <path>]
  • end [--keep-branch] [--force-delete]
  • abort [--hard]
  • status
  • doctor (repo health)

Stage Essentials

  • Index‑only: applies hunks to the index; working tree is untouched.
  • Input: choose exactly one of --stdin or --patch-file.
  • Pre‑check: internal --check; --check-only validates without changes; failure returns 41.
  • TTY behavior: with --stdin on an interactive TTY, it waits for input/EOF (Ctrl‑D). Prefer pipe/redirect or --patch-file in automation.
  • Produce patches: git diff -U0 -- <paths> > patch.diff (U0 works well with defaults).

Errors → Actions

  • NOT_GIT/20: run in repo root or pass --repo.
  • NO_SESSION/12: run diffk init first.
  • DIRTY_WORKTREE/13: retry init with --dirty=stash (or clean first).
  • LOCKED/14: serialize; short back‑off retry; if crash left a stale lock, remove .git/diffkeeper/lock after ensuring no active process.
  • NOTHING_TO_COMMIT/15: modify files or limit with --paths.
  • PATCH_APPLY_FAILED/41: patch mismatches current state; recompute/align or sync working tree.
  • CONFLICT/10: resolve conflicts, commit, then retry merge.
  • INVALID_ARGS/2: check signature; diffk help <command>.
  • INTERNAL/100 or 50: add --debug and inspect stderr.

Safety & Hygiene

  • .gitignore: recommended; auto snapshot (init --dirty commit) and normal commit both respect it.
  • Process lock: .git/diffkeeper/lock; concurrent attempts return LOCKED (14).
  • Push protection: init --install-hooks blocks pushing diffkeeper/*; override with DIFFKEEPER_ALLOW_PUSH=1.

Troubleshooting

  • NOT_GIT/20: set --repo or run from the repo root.
  • NO_SESSION/12: ensure session with diffk init.
  • PATCH_APPLY_FAILED/41: confirm how patches are produced; try --check-only first.
  • Interactive block: stage --stdin waits on TTY; use < patch.diff or --patch-file.