Skip to content

usage.zh.md

Latest commit

 

History

History
69 lines (56 loc) · 3.91 KB

usage.zh.md

File metadata and controls

69 lines (56 loc) · 3.91 KB
Raw

DiffKeeper 使用指南（面向用户与 AI/Agent）

本指南聚焦可直接复制的命令与自动化要点；更多参数可用 diffk help <command> 或加 --output json 查看。

建议：自动化/代理调用默认使用 --output json，排障时加 --debug。

使用详解：参见 usage-detailed.zh.md（逐命令用法、示例与退出码）。

90 秒上手

  • 确保会话（幂等）

    • 当前分支直接自动快照：
      • diffk init --mode=new-branch --source main --if-missing --dirty commit --snapshot-message "Warmup snapshot" --output json
    • 切换源分支且工作区脏时改用：
      • diffk init --mode=new-branch --source main --if-missing --dirty stash --snapshot-message-file .snapshot-msg.txt --output json

  • 整体提交（按需限制文件）

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

  • 选择性提交（stage 路径）

    • 预检：diffk stage --stdin --check-only --output json < patch.diff
    • 应用：diffk stage --stdin --output json < patch.diff
    • 提交：diffk commit --title "AI: apply selected hunks" --output json

  • 合并与收尾

    • 预检：diffk merge --to main --strategy=squash --dry-run --output json
    • 合并：diffk merge --to main --strategy=squash --message "Squash: session" --output json
    • 结束：diffk end --output json

常用命令速查（核心选项）

  • 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（健康检查）

Stage 使用要点（重要）

  • 作用：只修改暂存区（index），不改工作区文件。
  • 输入：--stdin 或 --patch-file（必须二选一）。
  • 预检：内部先做 --check；--check-only 仅检查不修改 index；失败返回 41。
  • TTY 行为：--stdin 在交互式终端会等待输入或 EOF（Ctrl‑D）；自动化请用管道/重定向或 --patch-file。
  • 生成补丁建议：git diff -U0 -- <paths> > patch.diff（U0 与默认容错更友好）。

错误码 → 动作

  • NOT_GIT/20：切到仓库根或传 --repo。
  • NO_SESSION/12：先执行 diffk init。
  • DIRTY_WORKTREE/13：init 改用 --dirty=stash 或清理后重试。
  • LOCKED/14：避免并发，短延时重试；崩溃残留锁需确认无活动进程后删除 .git/diffkeeper/lock。
  • NOTHING_TO_COMMIT/15：修改文件或传 --paths 指定文件。
  • PATCH_APPLY_FAILED/41：补丁与当前状态不匹配；重算/对齐补丁或同步工作区。
  • CONFLICT/10：手动解决冲突并提交，再重试 merge。
  • INVALID_ARGS/2：核对命令签名；用 diffk help <command> 查看。
  • INTERNAL/100 或 50：加 --debug 查看底层 git 输出定位问题。

安全与卫生

  • .gitignore：建议提供；init --dirty commit 的自动快照与常规 commit 均遵循 .gitignore。
  • 进程锁：命令获取 .git/diffkeeper/lock，并发时返回 LOCKED（14）。
  • 预推送钩子：init --install-hooks 可阻止推送 diffkeeper/*；临时覆盖 DIFFKEEPER_ALLOW_PUSH=1。

故障排除

  • 提示 NOT_GIT/20：在仓库目录内执行，或加 --repo。
  • 提示 NO_SESSION/12：先 diffk init。
  • 提示 PATCH_APPLY_FAILED/41：验证补丁生成方式与基线；可先 --check-only。
  • 交互阻塞：stage --stdin 在 TTY 下等待输入；使用 < patch.diff 或 --patch-file。

更多参数与示例：diffk help <command>（或加 --output json）。