RTK Git Worktree 工作流:用 Claude Code 命令构建 Rust 项目的隔离开发环境【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtkRTK 仓库自带一套面向 Claude Code 的斜杠命令,其中 worktree.md 定义了/tech:worktree命令:它能在约 1 秒内创建隔离的 git worktree、自动触发后台cargo check,并给出立即可见的状态反馈,让切换分支继续开发这个高频操作脱离git checkout带来的工作区污染。读完本文,你能完整掌握该命令的用法、参数、命名规范,以及脚本中仓库定位、分支名校验、.gitignore 前置检查、后台检查与日志约定等实现细节,并可结合配套的状态查询、清理命令形成完整的 worktree 生命周期管理方案。命令定位与整体流程/tech:worktree是 RTK 项目内 Claude Code 自定义命令的一部分。与大多数自定义命令类似,它由一段 YAML frontmatter 和正文构成:--- model: haiku description: Git Worktree Setup for RTK argument-hint: branch-name ---model: haiku:指定该命令由轻量模型执行(脚本本身是确定性 bash,无需大模型参与);description/argument-hint:提供命令说明与参数提示,参数即目标分支名。整个命令的执行模型可以概括为秒级建环境 异步验证:通过git worktree add在主仓库下的.worktrees/目录创建独立工作目录并新建分支;除非显式跳过,否则在新 worktree 中后台运行cargo check --all-targets,输出写入/tmp下的日志文件;立即打印 worktree 路径与后续操作指引,不阻塞等待编译。官方文档标注的性能目标是~1s setup background cargo check,即环境准备与编译验证解耦:你先获得可编辑的代码目录,验证结果稍后通过状态命令查询。基本用法/tech:worktree feature/new-filter # 创建 worktree 后台 cargo check /tech:worktree fix/typo --fast # 跳过 cargo check(立即就绪) /tech:worktree feature/perf --no-check # 跳过 cargo check创建完成后命令会打印 worktree 路径,你需要手动进入:cd .worktrees/feature-new-filter与正在运行的 Claude Code 会话的关系文档特别强调:Claude Code 的上下文(工作目录、项目记忆)绑定在启动时的路径上,worktree 创建后不能指望当前会话自动感知新目录。正确做法是退出当前会话,在新 worktree 中重新启动:/exit # 退出当前 Claude 会话 cd .worktrees/fix-bug-name # 进入 worktree claude # 在 worktree 上下文中启动 Claude创建完成后的提示输出中也内置了这段指引(区分会话正在运行/未运行两种情况),可以直接照做。分支命名规范:斜杠是硬性要求文档强制要求分支名使用类别/描述的带斜杠形式:输入分支名worktree 目录结论feature/new-filterfeature/new-filter.worktrees/feature-new-filter✅ 合规fix/bug-namefix/bug-name.worktrees/fix-bug-name✅ 合规feature-new-filter——❌ 缺少类别前缀这里有一个关键的路径映射规则:git 分支名允许/,但作为目录名会造成嵌套。脚本会把分支名中的斜杠全部替换为连字符,保证 worktree 一律平铺在.worktrees/一级子目录下:WORKTREE_NAME${BRANCH_NAME//\//-} WORKTREE_DIR$REPO_ROOT/.worktrees/$WORKTREE_NAME LOG_FILE/tmp/worktree-cargo-check-${WORKTREE_NAME}.log这个同名约定贯穿全链路:创建命令、状态查询命令和日志文件都使用同一套${BRANCH_NAME//\//-}转换,因此查询状态时也必须传入精确的原始分支名(如feature/new-filter),由命令内部完成同样的斜杠替换来定位日志。脚本实现逐段解析命令的核心是一段完整的 bash 脚本(见 worktree.md 的 Implementation 一节),按阶段拆解如下。1. 定位主仓库根目录(而非 worktree 根目录)GIT_COMMON_DIR$(git rev-parse --git-common-dir 2/dev/null) if [ -z $GIT_COMMON_DIR ]; then echo ❌ Not in a git repository exit 1 fi REPO_ROOT$(cd $GIT_COMMON_DIR/.. pwd)这是一个容易被忽略的细节:worktree 自身没有独立的.git目录,.git是一个指向主仓库的指针文件。git rev-parse --git-common-dir返回的是所有 worktree 共享的 git 目录(.git),其上级即主仓库根。用git rev-parse --show-toplevel之类的替代方案在 worktree 内会得到 worktree 自己的路径,导致.worktrees/目录被错误地嵌套创建。脚本注释中always use main repo root (not worktree root)正是针对这一点。2. 参数解析:识别--fast/--no-checkRAW_ARGS$ARGUMENTS BRANCH_NAME$RAW_ARGS SKIP_CHECKfalse if [[ $RAW_ARGS *--fast* ]]; then SKIP_CHECKtrue BRANCH_NAME${BRANCH_NAME// --fast/} fi if [[ $RAW_ARGS *--no-check* ]]; then SKIP_CHECKtrue BRANCH_NAME${BRANCH_NAME// --no-check/} fi两个 flag 语义完全等价(跳过 cargo check),解析后从分支名中剥离,得到干净的BRANCH_NAME。3. 分支名双重校验if [[ $BRANCH_NAME ~ [[:space:]\$\] ]]; then echo ❌ Invalid branch name (spaces or special characters not allowed) exit 1 fi if [[ $BRANCH_NAME ~ [~^:?*\\\[\]] ]]; then echo ❌ Invalid branch name (git forbidden characters: ~ ^ : ? * [ ]) exit 1 fi第一层排除空格、$、反引号——防止分支名进入后续命令与路径时造成注入;第二层排除 git 自身禁止的保留字符。校验失败直接exit 1,不做任何副作用。4..gitignore前置检查(fail-fast)if ! grep -qE ^\.worktrees/?$ $REPO_ROOT/.gitignore 2/dev/null; then echo ❌ .worktrees/ not in .gitignore echo Run: echo .worktrees/ .gitignore git add .gitignore git commit -m chore: ignore worktrees exit 1 fiworktree 里会包含编译产物、未提交改动等,如果不忽略,git status会把.worktrees/整个目录显示为 untracked 噪音。脚本在创建目录之前就检查.gitignore是否含.worktrees/条目,缺失则直接失败并给出修复命令。该前提在 RTK 仓库中是满足的:.gitignore 第 50 行即包含.worktrees/。5. 创建 worktreeecho Creating worktree for $BRANCH_NAME... mkdir -p $REPO_ROOT/.worktrees if ! git worktree add $WORKTREE_DIR -b $BRANCH_NAME 2/tmp/worktree-error.log; then echo ❌ Failed to create worktree cat /tmp/worktree-error.log exit 1 figit worktree add path -b branch一步完成新建分支 检出到指定目录。失败时把 git 的原始 stderr 从/tmp/worktree-error.log回显出来,便于定位(常见报错见文末排障一节)。6. 后台 cargo check 与日志约定if [ $SKIP_CHECK false ] [ -f $WORKTREE_DIR/Cargo.toml ]; then ( cd $WORKTREE_DIR echo ⏳ Cargo check started at $(date %H:%M:%S) $LOG_FILE if cargo check --all-targets $LOG_FILE 21; then echo ✅ Cargo check passed at $(date %H:%M:%S) $LOG_FILE else echo ❌ Cargo check failed at $(date %H:%M:%S) $LOG_FILE fi ) CHECK_RUNNINGtrue else CHECK_RUNNINGfalse fi几个值得注意的设计:触发条件双保险:仅在未跳过检查且worktree 根目录存在Cargo.toml时才启动。RTK 是纯 Rust 项目(根目录有 Cargo.toml),条件必然满足;但这条判断让脚本对非 Rust 目录也安全。日志协议固定:日志首行必为⏳ Cargo check started at HH:MM:SS,结束时追加✅ … passed或❌ … failed行。这三个带时间戳的标记就是后续状态命令解析状态的契约——状态脚本只靠grep这三个字符串判定运行中 / 通过 / 失败。子 shell 后台化:( … ) 使整个检查在子 shell 中异步执行,创建命令本身立即返回;trap kill $(jobs -p) EXIT在脚本退出时清理遗留后台任务。检查用的是cargo check --all-targets(含测试与 bench 目标)而非cargo build,只做类型/借用检查,速度远快于完整编译,契合快速反馈的定位。7. 即时报告echo ✅ Worktree ready: $WORKTREE_DIR if [ $CHECK_RUNNING true ]; then echo ⏳ Cargo check running in background... echo Check status: /tech:worktree-status $BRANCH_NAME echo Or view log: cat $LOG_FILE elif [ $SKIP_CHECK true ]; then echo ⚡ Cargo check skipped (--fast / --no-check mode) fi无论哪种模式,命令都在创建完成瞬间给出确定性反馈:worktree 路径、状态查询入口、日志路径,以及如果 Claude 正在运行则/exit→cd→claude重开的下一步清单。状态查询:/tech:worktree-status创建命令把验证结果异步化,配套的状态命令 worktree-status.md 负责读取结果:/tech:worktree-status feature/new-filter其实现逻辑是:按同一套${BRANCH_NAME//\//-}规则拼出日志路径/tmp/worktree-cargo-check-name.log,然后按上文三个标记分类输出:日志含✅ Cargo check passed→ 输出✅ Cargo check passed 完成时间,提示 worktree 可放心开发;日志含❌ Cargo check failed→ 输出失败时间,并grep ^error提取最多 20 条 rustc 错误行(如error[E0308]: mismatched types),同时提示仍可继续开发,边做边修;日志只含⏳ Cargo check started→ 输出仍在运行及开始时间,并给出tail -f $LOG_FILE观察实时进度;日志不存在 → 明确列出三种可能原因(使用了--fast/--no-check、分支名不精确、检查尚未开始),并ls -1 /tmp/worktree-cargo-check-*.log列出当前所有可用日志,防止查不到变成黑盒。日志文件放在/tmp而非仓库内,既避免被 git 追踪,也不污染 worktree;代价是重启系统后日志丢失,此时状态命令会落入日志不存在分支,需要重新触发检查或依赖手动cargo check。清理:手动删除与自动清扫单个 worktree 删除/tech:remove-worktree feature/new-filter # 或手动: git worktree remove .worktrees/feature-new-filter git worktree pruneremove-worktree.md 的脚本在删除之上叠加了多层安全机制,值得对照理解:通过git worktree list定位路径,路径与当前目录相同(主仓库)或分支为master/main时拒绝执行;用git branch --merged master判断分支是否已合并:未合并分支会要求交互确认才允许删除,已合并分支直接清理;git worktree remove失败时回退到强制删除 git worktree prune;远程分支仅提示,需再次确认后才git push origin --delete。批量清理已合并 worktreeclean-worktrees.md 提供无人值守版本:先git worktree prune -v清理悬挂引用,再遍历git worktree list,只处理已合并进 master 的分支(跳过main/master与主仓库),支持--dry-run预演。适用时机:PR 合入后、周期性维护、创建新 worktree 前的整理。未合并分支不在此命令职责范围内,应走单个删除流程。RTK 对git worktree的 token 压缩代理从源码结构看,RTK 本体也代理了git worktree命令以压缩输出。src/cmds/git/git.rs 中的run_worktree分两种模式:参数含add/remove/prune/lock/unlock/move时透传给 git,成功只打印ok,失败打印FAILED: git worktree …与 stderr,并记录到tracking;无动作参数时执行git worktree list,经filter_worktree_list压缩每行路径 commit 分支的冗余输出,并用never_worse兜底保证过滤结果不会比原始输出更差。测试用例 test_filter_worktree_list 验证了列表压缩对多 worktree 输入的格式保持,功能说明见 FEATURES.md。也就是说,worktree 流程中产生的git worktree list、git worktree prune等命令本身也可以走rtk代理获得更省 token 的输出,与命令脚本中直接使用原生 git 并不冲突——脚本追求的是确定性,RTK 代理追求的是输出压缩,二者分工不同。排障手册文档内置了两类高频故障的处理方式:worktree already exists——目标目录已被占用:git worktree remove .worktrees/$BRANCH_NAME # Then retrybranch already exists——-b不能新建已存在的分支:git branch -D $BRANCH_NAME # Then retry结合脚本的 fail-fast 设计,排障思路是:每个阶段(仓库定位、参数校验、.gitignore 检查、git worktree add)失败都会打印明确错误并立即退出,/tmp/worktree-error.log保存 git 原始报错,/tmp/worktree-cargo-check-*.log保存完整cargo check输出,三者配合即可定位问题落在哪一层。小结/tech:worktree用约百行的 bash 脚本把 git worktree 的创建—验证—查询—清理闭环做成了可重复的 Claude Code 命令,关键设计可以归纳为四点:用--git-common-dir锚定主仓库根避免 worktree 嵌套;斜杠转连字符的统一路径映射贯穿创建与状态查询;.gitignore前置检查与分支名双重校验把失败挡在副作用之前;后台cargo check 固定日志协议让秒级建环境与异步验证并行。这套模式(隔离目录 异步验证 日志契约 安全清理)同样适用于其他语言的项目,只需把检查阶段替换为对应的编译/类型检查命令。【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考