Skip to content

usage-detailed.en.md

Latest commit

 

History

History
171 lines (154 loc) · 7.92 KB

usage-detailed.en.md

File metadata and controls

171 lines (154 loc) · 7.92 KB
Raw

DiffKeeper Detailed Usage (diffk)

This document targets both humans and AI/agents. It covers every implemented command with usage, descriptions, examples, and exit codes. For automation, prefer --output json; add --debug when diagnosing issues.

Global Options (apply to all commands)

  • --repo <path>: explicit Git repo root (default: auto-detect from CWD)
  • --output json|text: output format (default text; automation should use json)
  • --debug: print underlying git commands to stderr
  • --timeout <ms>: per-command timeout in milliseconds (default 30000)

Conventions

  • Concurrency lock: commands acquire .git/diffkeeper/lock; on contention, exit code is LOCKED (14).
  • .gitignore: both auto-snapshot (init --dirty commit) and regular commit honor .gitignore.
  • Errors & JSON: when failing, JSON includes error.errorCode (e.g., NOT_GIT, NO_SESSION, DIRTY_WORKTREE, LOCKED, PATCH_APPLY_FAILED, etc.).

1) status — show repo/session status

Usage

  • diffk status [--repo <path>] [--output json|text] Description
  • Prints repo info and session state (current branch, dirty/untracked, in-session).
  • If .gitignore is missing, a NO_GITIGNORE warning may appear in data.warnings. Examples
  • diffk status
  • diffk status --output json Exit codes
  • 20/NOT_GIT: not a git repo

2) init — initialize a session

Usage

  • diffk init --mode new-branch|current [--source <branch>] [--branch <name>] [--install-hooks] [--no-upstream] [--dirty commit|stash|block|keep] [--if-missing] [--snapshot-message "<msg>"|--snapshot-message-file <path>] [--output json] Description
  • Initialize a session on a new or the current branch; records base commit.
  • Idempotent: --if-missing returns existing session if present.
  • Dirty policy --dirty:
    • commit (default, only when not switching source): auto git add -A and commit a snapshot;
    • stash: stash push before switching, stash pop after; if changes remain, commit a snapshot;
    • block: block and suggest cleaning;
    • keep: attempt to keep and switch (may fail; not recommended).
  • Auto snapshot commit message can be customized:
    • --snapshot-message, --snapshot-message-file (file takes priority); applied only if a snapshot commit actually occurs; no prefix added automatically;
    • Environment overrides for defaults: DIFFK_SNAPSHOT_MESSAGE, DIFFK_SNAPSHOT_MESSAGE_STASH.
  • Others: --install-hooks installs a pre-push hook blocking diffkeeper/*; --no-upstream skips setting an upstream. Examples
  • Current branch auto snapshot:
    • diffk init --mode=new-branch --source main --if-missing --dirty commit --snapshot-message "Warmup snapshot" --output json
  • Switching source with a dirty worktree (stash policy):
    • diffk init --mode=new-branch --source main --if-missing --dirty stash --snapshot-message-file .snapshot-msg.txt --output json Exit codes
  • 11/SESSION_EXISTS: session exists (without --if-missing)
  • 13/DIRTY_WORKTREE: switching source blocked due to a dirty worktree
  • 14/LOCKED: concurrent operation
  • 20/NOT_GIT: not a git repo

3) commit — commit changes

Usage

  • diffk commit --title "<msg>" [--paths <p1,p2,...>] [--signoff] [--no-verify] [--gpg-sign] [--co-author "Name <email>,..."] [--message-file <path>] [--allow-empty] [--output json] Description
  • On the session branch:
    • Without --paths: performs git add -A (honors .gitignore) then commits.
    • With --paths: commit only listed files.
    • --message-file: read full commit message from file; --allow-empty: allow empty commit. Examples
  • All changes: diffk commit --title "AI: update" --output json
  • Selected files: diffk commit --title "AI: partial" --paths "a,b" --output json
  • Long message: diffk commit --message-file COMMIT_MSG.txt --output json Exit codes
  • 12/NO_SESSION, 14/LOCKED, 15/NOTHING_TO_COMMIT, 20/NOT_GIT

4) stage — apply unified diff to index only

Usage

  • diffk stage --stdin | --patch-file <path> [--three-way] [--unidiff-zero] [--recount] [--whitespace nowarn|warn|error] [--reverse] [--check-only] [--output json] Description
  • Applies unified diff hunks to the staging area (index) only; working tree remains unchanged.
  • Performs a pre-check (git apply --cached --check); --check-only validates without writing.
  • Defaults enable --three-way, --unidiff-zero, --recount for better tolerance; --reverse if your patch direction is inverted.
  • TTY: --stdin on an interactive terminal waits for input or EOF (Ctrl-D); use pipe/redirect or --patch-file in automation. Examples
  • Pre-check: diffk stage --stdin --check-only --output json < patch.diff
  • Apply: diffk stage --stdin --output json < patch.diff
  • From file: diffk stage --patch-file patch.diff --output json Exit codes
  • 12/NO_SESSION, 20/NOT_GIT, 41/PATCH_APPLY_FAILED, 50/INTERNAL (read failure)

5) squash — squash commits

Usage

  • diffk squash --strategy reset-soft|merge-squash [--message "<msg>"] [--output json] Description
  • Squash all commits since the session base.
  • merge-squash currently behaves like reset-soft (simplified). Examples
  • diffk squash --message "Squash: AI session summary" --output json Exit codes
  • 12/NO_SESSION, 20/NOT_GIT

6) merge — merge back to target

Usage

  • diffk merge --to <branch> --strategy squash|no-ff|ff-only [--dry-run] [--message "<msg>"|--message-file <path>] [--output json] Description
  • Merge the session branch back (default to source).
  • --dry-run: use merge-tree to detect conflicts without modifying working tree.
  • Messages:
    • squash: if no message provided, default is Squash merge from <session-branch>;
    • no-ff: with message uses -m; without message uses --no-edit to accept Git default;
    • ff-only: fast-forward; no merge commit. Examples
  • Dry-run: diffk merge --to main --strategy=squash --dry-run --output json
  • Merge: diffk merge --to main --strategy=squash --message "Squash: session" --output json Exit codes
  • 10/CONFLICT, 12/NO_SESSION, 14/LOCKED, 20/NOT_GIT, 2/INVALID_ARGS

7) end — end session

Usage

  • diffk end [--keep-branch] [--force-delete] [--output json] Description
  • Cleanup metadata; default safe branch delete (-d); --force-delete uses -D. Examples
  • diffk end --output json Exit codes
  • 12/NO_SESSION, 20/NOT_GIT

8) abort — abort session

Usage

  • diffk abort [--hard] [--output json] Description
  • new-branch: switch back to source and delete session branch (--hard to force).
  • current-branch: reset to base commit (--hard discards working tree changes). Examples
  • diffk abort --hard --output json Exit codes
  • 12/NO_SESSION, 20/NOT_GIT

9) help — command help

Usage

  • diffk help / diffk help <command> / diffk help codes [optionally --output json] Description
  • Top-level / per-command help / exit codes overview.
  • --output json returns structured help (name, usage, options, examples, exitCodes, seeAlso). Examples
  • diffk help
  • diffk help merge --output json

10) version — print version

Usage

  • diffk version [--output json] Description
  • Show CLI version; supports JSON output. Examples
  • diffk version --output json

11) doctor — repo health check

Usage

  • diffk doctor [--output json] Description
  • Scan for common issues and suggestions (e.g., .gitignore presence). Examples
  • diffk doctor --output json

Appendix: Error Codes → Actions (quick list)

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