Skip to content

README.zh.md

Latest commit

 

History

History
53 lines (42 loc) · 2.72 KB

README.zh.md

File metadata and controls

53 lines (42 loc) · 2.72 KB

DiffKeeper (diffk) — 基于 Git 的 AI 会话工作流

DiffKeeper 以 Git 为骨架，提供适合人类与自动化/代理的工作流：初始化会话、按步提交、可选压缩、合并回主线，CLI diffk 支持稳定的 JSON 输出。

命令

  • status、init、commit、stage、squash、merge、end、abort、help、version、doctor

特性

  • 会话：init 支持新分支/当前分支；--if-missing 幂等；脏工作区策略 commit|stash|block|keep；可选预推送钩子；默认不设 upstream。
  • 提交：自动 git add -A（或 --paths 限定），--message-file，--allow-empty。
  • Stage（仅改 index）：通过统一 diff 片段修改暂存区；内部预检；--check-only；3‑way/unidiff‑zero/recount；不改工作区。
  • 合并：squash|no-ff|ff-only；--dry-run 冲突检查；--message/--message-file 自定义信息。
  • 结束/中止：默认安全删除分支（-d），--force-delete 使用 -D。
  • 自动化：--output json、--debug、--timeout；稳定错误码；.git/diffkeeper/lock 进程锁。

90 秒上手

# 1) 确保会话（幂等）
diffk init --mode=new-branch --source main --if-missing --dirty commit --output json
# 切换源分支且工作区脏时
diffk init --mode=new-branch --source main --if-missing --dirty stash --output json

# 2) 提交
diffk commit --title "AI: update" --output json

# （可选）按补丁选择性暂存
diffk stage --stdin --check-only --output json < patch.diff
if [ $? -eq 0 ]; then diffk stage --stdin --output json < patch.diff; fi

diffk commit --title "AI: apply selected hunks" --output json

# 3) 合并与收尾
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

安装/构建

  • 构建：go build ./cmd/diffk（Go 1.22+，Git 2.30+）
  • 若缓存路径受限： mkdir -p .gocache .gopath/pkg/mod && GOCACHE=$(pwd)/.gocache GOPATH=$(pwd)/.gopath GOMODCACHE=$(pwd)/.gopath/pkg/mod go build ./cmd/diffk

文档

  • 用户/代理指南：usage.zh.md（中文），usage.md（English）
  • 使用详解：usage-detailed.zh.md（中文），usage-detailed.en.md（English）
  • 自动化指南：automation.zh.md（中文），automation.md（English）
  • 命令帮助：diffk help、diffk help <command>，或加 --output json 获取结构化帮助

说明

  • 建议在仓库根目录提供 .gitignore（自动快照与常规提交均遵循 .gitignore）。
  • 命令带进程锁避免并发；冲突返回 LOCKED。
  • 可选预推送钩子（init --install-hooks）阻止推送 diffkeeper/*（临时覆盖 DIFFKEEPER_ALLOW_PUSH=1）。