Skip to content

automation.md

Latest commit

 

History

History
65 lines (57 loc) · 3.14 KB

automation.md

File metadata and controls

65 lines (57 loc) · 3.14 KB
Raw

Automation & Agent Integration Guide (English)

Designed for Codex/Claude Code and scripts to use diffk reliably and predictably.

Recommended Flow (new-branch mode)

  • Ensure session (idempotent):
diffk init --mode=new-branch --source <branch> --install-hooks --no-upstream --if-missing --dirty commit --snapshot-message "Warmup snapshot" --output json
  • If switching --source and the worktree is dirty, you may get DIRTY_WORKTREE (13). Retry with --dirty=stash (you can still set --snapshot-message/--snapshot-message-file; it applies only if a snapshot commit actually happens):
diffk init --mode=new-branch --source <branch> --if-missing --dirty stash --snapshot-message-file .snapshot-msg.txt --output json
  • For each change:
    • Optional pre-check then apply patch to index:
diffk stage --stdin --check-only --output json   < patch.diff
if ok then: diffk stage --stdin --output json     < patch.diff
  • Commit:
diffk commit --title "AI: update" --output json
  • Finish:
diffk squash --message "Squash: AI session summary" --output json
# Dry-run merge to detect conflicts
m=$(diffk merge --to <branch> --strategy=squash --dry-run --output json)
# If ok, perform the merge (custom message optional)
diffk merge --to <branch> --strategy=squash --message "Squash: session" --output json
diffk end --output json

JSON Contract & Error Handling

  • Top-level: version|command|code|status|data|error
  • Errors include: error.message, error.hint, error.errorCode
  • Common errorCode values and meanings:
    • NO_SESSION (12), SESSION_EXISTS (11), DIRTY_WORKTREE (13), LOCKED (14), NOTHING_TO_COMMIT (15), CONFLICT (10), PATCH_APPLY_FAILED (41), NOT_GIT (20), INVALID_ARGS (2), INTERNAL (100/50)

Suggested State Machine

  1. Ensure session (init --if-missing → handle DIRTY_WORKTREE)
  2. Stage/commit loop (stage --check-only → stage → commit; handle PATCH_APPLY_FAILED and NOTHING_TO_COMMIT)
  3. squash
  4. merge --dry-run (handle CONFLICT) → merge
  5. end

Stability Switches

  • --debug: print underlying git commands (to stderr)
  • --timeout <ms>: per-command timeout (default 30000)
  • Process lock: commands acquire .git/diffkeeper/lock; on contention you get LOCKED (14). Serialize or retry. If a crash leaves a stale lock, manually delete it after ensuring no active diffk process.

gitignore Recommendation

  • Provide a .gitignore at repo root. Auto-snapshot on init --dirty commit and normal commit both respect .gitignore. Without it, build/cache files may be committed accidentally.

Patch Tips

  • Generate minimal tolerant patches: git diff -U0 -- <paths> > patch.diff (U0 pairs well with --unidiff-zero)
  • --stdin reads from pipe/redirect; when run interactively with no input it waits for EOF (Ctrl-D)
  • Use --reverse if your patch direction is inverted

Notes

  • No interactive hunk picker; use prepared unified diffs with stage
  • merge --strategy=no-ff without --message uses --no-edit to avoid interactive editor
  • ff-only fast-forwards; no merge commit
  • Prefer --message-file for multi-line commit/merge messages (shell-safe)