4.6 KiB
name, description
| name | description |
|---|---|
| branch | 根据当前仓库约定，在用户确认后于当前工作区或独立 worktree 创建本地 Git 分支，并在分支任务结束后安全关闭额外 worktree。适用于新增需求、缺陷、维护分支及解除 worktree 分支占用；仅查看、重命名、删除、合并、推送或发布分支不应触发本 Skill。 |
创建 Git 分支
安全地创建本地分支并管理其独立 worktree 生命周期。所有检查默认只读；fetch、分支创建和 worktree 移除分别需要明确授权，不得把它们合并为一次隐含操作。
选择模式
create：规划名称，并在当前工作区或独立 worktree 创建分支。close：分支任务结束后安全移除额外 worktree，释放分支占用。
涉及独立 worktree 时读取 Worktree 分支规则。用户只说“创建分支”时进入 create；用户要求结束、关闭、清理额外 worktree，或出现分支已被 worktree 占用错误时进入 close。
创建前检查
- 运行
git status --short --branch、git branch --show-current、git branch --list、git branch --remotes和git worktree list --porcelain。 - 读取当前仓库适用的
AGENTS.md、贡献指南或其他明确的分支约定；没有约定时再参考现有分支命名。 - 收集分支用途、简短描述和基准引用。不要默认
main、master、远程名称、版本分支或合并目标。 - 若工作区不干净，列出现有修改并说明直接切换会携带这些修改；不得自动暂存、提交、还原或清理，优先建议使用独立 worktree。
.craftkit/local/**和.craftkit/cache/**不视为业务改动；若它们出现在普通状态中，提示检查.craftkit/.gitignore。.craftkit/agents/**、standards/**、knowledge/**、handoff/**和project.json属于普通项目改动，应与其他未提交内容一起展示。
生成和验证名称
- 优先遵循仓库已有规则。没有规则时，可建议
feature/<short-name>、fix/<short-name>、hotfix/<short-name>或chore/<short-name>。 - 描述部分使用简短的小写连字符形式；保留用户提供且确有需要的任务编号，不自行编造编号。
- 使用
git check-ref-format --branch "<branch>"验证名称。 - 使用
git show-ref --verify --quiet "refs/heads/<branch>"检查本地分支，并检查同名远程引用；已存在时停止，不覆盖、不重置。 - 使用
git rev-parse --verify "<base>^{commit}"验证基准能够解析为提交。
远程引用边界
只读检查不得自动执行 git fetch。如果用户要求基于远程最新状态，先展示远程名称和将要执行的 fetch 命令，取得单独确认后再执行。fetch 完成后重新验证基准，不把 fetch 授权视为创建分支授权。
创建确认
执行前展示：
- 当前分支和工作区状态；
- 目标分支名称；
- 基准引用及其提交短哈希；
- 在当前工作区还是独立 worktree 创建，以及是否影响未提交修改；
- 将执行的唯一创建命令。
工作区干净、当前 checkout 可以切换且用户没有隔离要求时，可以在当前工作区创建。工作区不干净、当前分支被 IDE/服务/测试占用，或用户要求不影响当前 checkout 时，使用独立 worktree；创建前确认目标绝对路径不存在、分支不存在且基准哈希已锁定。
本地基准使用：
git switch -c "<branch>" "<base>"
远程跟踪引用使用：
git switch --no-track -c "<branch>" "<remote>/<base>"
独立 worktree 使用：
git worktree add -b "<branch>" "<absolute-worktree-path>" "<base>"
只有用户在看到上述最终信息后明确确认，才执行该命令。用户调整名称或基准后必须重新展示并确认。
创建后验证
在实际创建位置运行 git branch --show-current、git rev-parse --short HEAD 和 git status --short --branch，确认当前分支、起点和工作区状态。独立 worktree 创建后还要复核主工作区分支、HEAD 和未提交内容未变化，并明确报告分支占用路径、后续操作目录以及生命周期结束后的清理义务。远程基准创建时再用 git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 检查没有错误 upstream；命令返回“无 upstream”属于预期结果。
create 到此不执行 push、不设置远程 upstream，也不创建合并请求。独立 worktree 在分支任务完成前保持 active，完成后必须调用 close 进入清理门禁。失败时报告原始错误和当前仓库状态，不自动重试破坏性替代命令。