Skip to content

usage-detailed.zh.md

Latest commit

 

History

History
176 lines (159 loc) · 8.21 KB

usage-detailed.zh.md

File metadata and controls

176 lines (159 loc) · 8.21 KB

DiffKeeper 使用详解（diffk）

本文面向终端用户与 AI/Agent，覆盖当前已实现的全部命令、用法与示例。建议自动化默认携带 --output json，排障加 --debug。

全局选项（适用于所有命令）

  • --repo <path>：显式指定 Git 仓库根（默认从当前目录自动探测）
  • --output json|text：输出格式（默认 text；自动化推荐 json）
  • --debug：打印底层 git 调用（stderr），便于定位问题
  • --timeout <ms>：命令超时时间（毫秒，默认 30000）

通用约定

  • 并发锁：命令执行期间会获取 .git/diffkeeper/lock，并发时返回 LOCKED（14）。
  • .gitignore：init --dirty commit 的自动快照与常规 commit 均遵循 .gitignore。
  • 错误码与 JSON：错误时 JSON 中包含 error.errorCode（如 NOT_GIT、NO_SESSION、DIRTY_WORKTREE、LOCKED、PATCH_APPLY_FAILED 等）。

1) status — 查看状态

用法

  • diffk status [--repo <path>] [--output json|text] 说明
  • 显示仓库信息与会话状态（当前分支、是否脏、是否处于会话）。
  • 若仓库根缺少 .gitignore，可能在 data.warnings 中给出 NO_GITIGNORE 提示。 示例
  • diffk status
  • diffk status --output json 相关退出码
  • 20/NOT_GIT：不在 Git 仓库内

2) init — 初始化会话

用法

  • 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] 说明
  • 在新分支或当前分支初始化会话，并记录基线 commit。
  • 幂等：--if-missing 已存在会话时直接返回现有会话。
  • 脏工作区策略 --dirty：
    • commit（默认，仅在不切换 source 时生效）：自动 git add -A 并提交一次“快照”；
    • stash：切换前 stash push，切换后 stash pop，若仍有变动则自动提交一次快照；
    • block：阻止初始化并提示清理；
    • keep：尝试保留并切换，可能失败（不推荐）。
  • 自动快照的提交消息可定制：
    • --snapshot-message、--snapshot-message-file（文件优先级更高）；仅在“实际发生自动快照”时生效；不会自动添加前缀；
    • 也可通过环境变量覆盖默认值：DIFFK_SNAPSHOT_MESSAGE、DIFFK_SNAPSHOT_MESSAGE_STASH。
  • 其它：--install-hooks 安装预推送钩子阻止推送 diffkeeper/*；--no-upstream 默认不设置 upstream。 示例
  • 当前分支自动快照：
    • diffk init --mode=new-branch --source main --if-missing --dirty commit --snapshot-message "Warmup snapshot" --output json
  • 切换 source 且工作区脏（stash 策略）：
    • diffk init --mode=new-branch --source main --if-missing --dirty stash --snapshot-message-file .snapshot-msg.txt --output json 相关退出码
  • 11/SESSION_EXISTS：会话已存在（未加 --if-missing）
  • 13/DIRTY_WORKTREE：切换 source 且工作区脏被阻止
  • 14/LOCKED：并发锁冲突
  • 20/NOT_GIT：不在 Git 仓库内

3) commit — 提交改动

用法

  • diffk commit --title "<msg>" [--paths <p1,p2,...>] [--signoff] [--no-verify] [--gpg-sign] [--co-author "Name <email>,..."] [--message-file <path>] [--allow-empty] [--output json] 说明
  • 在会话分支上提交：
    • 未指定 --paths 时，默认 git add -A 后提交（遵循 .gitignore）。
    • 指定 --paths 时，仅提交这些文件。
    • --message-file 从文件读取完整提交消息；--allow-empty 允许空提交（流水线兜底）。 示例
  • 全量提交：diffk commit --title "AI: update" --output json
  • 限定文件：diffk commit --title "AI: partial" --paths "a,b" --output json
  • 长消息：diffk commit --message-file COMMIT_MSG.txt --output json 相关退出码
  • 12/NO_SESSION：无活动会话
  • 14/LOCKED：并发锁冲突
  • 15/NOTHING_TO_COMMIT：没有需要提交的改动
  • 20/NOT_GIT：不在 Git 仓库内

4) stage — 以补丁方式暂存（仅改 index）

用法

  • diffk stage --stdin | --patch-file <path> [--three-way] [--unidiff-zero] [--recount] [--whitespace nowarn|warn|error] [--reverse] [--check-only] [--output json] 说明
  • 将统一 diff 补丁的变更应用到“暂存区（index）”，不修改工作区文件。
  • 先执行预检（相当于 git apply --cached --check），失败立即返回；--check-only 仅检查可应用性，不写入 index。
  • 默认开启 --three-way、--unidiff-zero、--recount，容错更强；必要时可配合 --reverse。
  • TTY 行为：--stdin 在交互式终端会等待输入或 EOF（Ctrl‑D）；自动化推荐管道/重定向或 --patch-file。 示例
  • 预检：diffk stage --stdin --check-only --output json < patch.diff
  • 应用：diffk stage --stdin --output json < patch.diff
  • 从文件：diffk stage --patch-file patch.diff --output json 相关退出码
  • 12/NO_SESSION、20/NOT_GIT、41/PATCH_APPLY_FAILED、50/INTERNAL(读取失败)

5) squash — 压缩提交

用法

  • diffk squash --strategy reset-soft|merge-squash [--message "<msg>"] [--output json] 说明
  • 将会话起点以来的提交压缩为一次提交。
  • 当前 merge-squash 与 reset-soft 行为等价（简化实现）。 示例
  • diffk squash --message "Squash: AI session summary" --output json 相关退出码
  • 12/NO_SESSION、20/NOT_GIT

6) merge — 合并回目标分支

用法

  • diffk merge --to <branch> --strategy squash|no-ff|ff-only [--dry-run] [--message "<msg>"|--message-file <path>] [--output json] 说明
  • 将会话分支合并回目标分支（默认回到源分支）。
  • --dry-run：使用 merge-tree 检查是否会发生冲突，不修改工作区。
  • 合并消息：
    • squash：若未提供消息，默认 Squash merge from <session-branch>；
    • no-ff：未提供消息时使用 --no-edit 接受 Git 默认信息；提供消息时使用 -m；
    • ff-only：仅快进，不产生合并提交。 示例
  • 干跑检查：diffk merge --to main --strategy=squash --dry-run --output json
  • 真正合并：diffk merge --to main --strategy=squash --message "Squash: session" --output json 相关退出码
  • 10/CONFLICT：发生冲突
  • 12/NO_SESSION、14/LOCKED、20/NOT_GIT、2/INVALID_ARGS

7) end — 结束会话

用法

  • diffk end [--keep-branch] [--force-delete] [--output json] 说明
  • 清理会话元数据；默认安全删除会话分支（-d）。
  • --force-delete：使用 -D 强制删除。 示例
  • diffk end --output json 相关退出码
  • 12/NO_SESSION、20/NOT_GIT

8) abort — 中止会话

用法

  • diffk abort [--hard] [--output json] 说明
  • new-branch：切回源分支并删除会话分支（--hard 强制）。
  • current-branch：重置到会话基线（--hard 丢弃工作区更改）。 示例
  • diffk abort --hard --output json 相关退出码
  • 12/NO_SESSION、20/NOT_GIT

9) help — 查看帮助

用法

  • diffk help / diffk help <command> / diffk help codes [可加 --output json] 说明
  • 顶层帮助 / 子命令帮助 / 退出码总览。
  • --output json 返回结构化帮助（命令名、用法、选项、示例、退出码、See also）。 示例
  • diffk help
  • diffk help merge --output json

10) version — 版本

用法

  • diffk version [--output json] 说明
  • 打印版本号；支持 JSON 输出。 示例
  • diffk version --output json

11) doctor — 健康检查

用法

  • diffk doctor [--output json] 说明
  • 扫描常见问题并给出建议（当前主要检查 .gitignore 是否存在）。 示例
  • diffk doctor --output json

附：错误码与常见动作（简表）

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