手动创建分支工作流

如果未提供 Issue 编号，请遵循此工作流：

1. 检查仓库状态

git status

验证：

• 工作目录是否干净，或者是否有可接受的未提交更改
• 当前分支信息
• 是否在 git 仓库中

2. 获取分支名称输入

向用户询问所需的分支名称。接受任何格式的输入——命令将处理格式化和验证。

3. 自动检测并应用前缀

分析分支名称输入中的关键词，并自动添加适当的前缀：

• feature/ - 关键词：“add”、“implement”、“create”、“new”、“feature”
• bugfix/ - 关键词：“fix”、“bug”、“resolve”、“patch”、“repair”
• hotfix/ - 关键词：“hotfix”、“urgent”、“critical”、“emergency”
• chore/ - 关键词：“chore”、“refactor”、“update”、“upgrade”、“maintain”
• docs/ - 关键词：“docs”、“documentation”、“readme”、“guide”

如果用户的输入已经以可识别的前缀（feature/、bugfix/ 等）开头，则保持原样。

4. 验证分支名称

应用全面的验证：

短横线命名法强制

• 转换为小写
• 将空格和下划线替换为连字符
• 确保格式为：prefix/kebab-case-name

字符验证

拒绝包含以下内容的分支名称：

• 空格（转换为连字符）
• 特殊字符：~、^、:、?、*、[、]、\、@{、..
• 控制字符或非 ASCII 字符（连字符和斜杠除外）
• 开头或结尾的斜杠或连字符

长度验证

• 最小长度：3 个字符（前缀除外）
• 最大长度：100 个字符（总计）

5. 检查重复项

检查本地和远程分支：

# 检查本地分支
git branch --list "<branch-name>"

# 检查远程分支
git ls-remote --heads origin "<branch-name>"

如果分支已存在：

• 本地存在：提供检出现有分支的选项
• 远程存在：警告用户并建议替代名称
• 两者都存在：通知用户并询问是否要检出或选择其他名称

6. 确定基础分支

使用智能默认值：

1. 检查 main 是否存在：

   git rev-parse --verify main
   

2. 如果不存在，检查 master 是否存在：

   git rev-parse --verify master
   

3. 如果两者都不存在，则使用当前 HEAD

4. 允许用户在需要时指定不同的基础分支（在创建前询问）

7. 创建并检出分支

git checkout -b <validated-branch-name> <base-branch>

通过显示以下信息的消息确认创建成功：

• 分支名称
• 使用的基础分支
• 当前状态

8. 远程推送建议

询问用户：“您是否希望将此分支推送到远程并设置跟踪？”

如果是：

git push -u origin <branch-name>

这可以实现：

• 分支的远程备份
• 与团队成员协作
• GitHub PR 创建工作流
• 在 GitHub UI 中显示分支

错误处理

提供清晰、可操作的错误消息：

• 不是 git 仓库：“此目录不是 git 仓库。请使用 git init 初始化一个仓库，或导航到一个仓库目录。”
• GitHub CLI 不可用：“GitHub CLI (gh) 未安装。请从 https://cli.github.com 安装，或使用手动创建分支。”
• 未找到 Issue：“未找到 Issue #123。请检查 Issue 编号或手动创建分支。”
• 无效的分支名称：“分支名称包含无效字符。建议：feature/valid-branch-name”
• 分支已存在：“分支 feature/existing 已存在。请使用 git checkout feature/existing 切换到该分支，或选择其他名称。”
• 网络问题：“无法检查远程分支。仅继续本地创建。”

示例

示例 1：GitHub Issue 集成

User: "Create a branch for issue #456"
Command: gh issue view 456
Output: #456 - Add user authentication (open)
Command: gh issue develop 456 -c
Output: Created and checked out branch: feature/456-add-user-authentication

示例 2：手动创建并自动添加前缀

User: "Create branch: fix login bug"
Analysis: Contains "fix" → apply "bugfix/" prefix
Validated: "bugfix/login-bug"
Command: git checkout -b bugfix/login-bug main

示例 3：自定义前缀

User: "Create branch: docs/update readme"
Analysis: Already has "docs/" prefix → keep as-is
Validated: "docs/update-readme"
Command: git checkout -b docs/update-readme main

最佳实践

1. 当提及 Issue 编号时，始终优先使用 GitHub Issue 工作流
2. 在创建分支之前进行彻底验证，以避免 git 错误
3. 使用描述性名称，清楚地表明其目的
4. 遵循团队惯例——检查现有分支名称的模式
5. 尽早推送到远程，以便备份和协作
6. 尽可能将分支与 Issue 关联，以便更好地进行项目跟踪

每周安装量

1.2K

仓库

ruchernchong/claude-kit

首次出现

2026年2月13日

安全审计

Gen Agent Trust HubFailSocketPassSnykWarn

安装于

github-copilot988

opencode988

codex987

gemini-cli986

amp985

kimi-cli985

gh issue develop <issue-number> -c

• The -c flag automatically checks out the newly created branch
• GitHub automatically generates an appropriate branch name from the issue title
• The branch is linked to the issue for better project tracking

Manual Branch Creation Workflow

If no issue number is provided, follow this workflow:

1. Check Repository Status

git status

Verify:

• Clean working directory or acceptable uncommitted changes
• Current branch information
• Whether we're in a git repository

2. Get Branch Name Input

Ask the user for the desired branch name. Accept input in any format - the command will handle formatting and validation.

3. Auto-Detect and Apply Prefix

Analyse the branch name input for keywords and automatically add appropriate prefixes:

• feature/ - Keywords: "add", "implement", "create", "new", "feature"
• bugfix/ - Keywords: "fix", "bug", "resolve", "patch", "repair"
• hotfix/ - Keywords: "hotfix", "urgent", "critical", "emergency"
• chore/ - Keywords: "chore", "refactor", "update", "upgrade", "maintain"
• docs/ - Keywords: "docs", "documentation", "readme", "guide"

If the user's input already starts with a recognised prefix (feature/, bugfix/, etc.), keep it as-is.

4. Validate Branch Name

Apply comprehensive validation:

Kebab-Case Enforcement

• Convert to lowercase
• Replace spaces and underscores with hyphens
• Ensure format is: prefix/kebab-case-name

Character Validation

Reject branch names containing:

• Spaces (convert to hyphens)
• Special characters: ~, ^, :, ?, *, [, ], \, @{, ..
• Control characters or non-ASCII (except hyphens and slashes)
• Leading or trailing slashes or hyphens

Length Validation

• Minimum: 3 characters (excluding prefix)
• Maximum: 100 characters (total)

5. Check for Duplicates

Check both local and remote branches:

# Check local branches
git branch --list "<branch-name>"

# Check remote branches
git ls-remote --heads origin "<branch-name>"

If branch exists:

• Locally : Offer to checkout existing branch instead
• Remotely : Warn user and suggest alternative name
• Both : Inform user and ask if they want to checkout or choose different name

6. Determine Base Branch

Use smart defaulting:

1. Check if main exists:

   git rev-parse --verify main
   

2. If not, check if master exists:

   git rev-parse --verify master
   

3. If neither exists, use current HEAD

4. Allow user to specify different base branch if needed (ask before creating)

7. Create and Checkout Branch

git checkout -b <validated-branch-name> <base-branch>

Confirm successful creation with a message showing:

• Branch name
• Base branch used
• Current status

8. Remote Push Recommendation

Ask the user: "Would you like to push this branch to remote and set up tracking?"

If yes:

git push -u origin <branch-name>

This enables:

• Remote backup of the branch
• Collaboration with team members
• GitHub PR creation workflow
• Branch visibility in GitHub UI

Error Handling

Provide clear, actionable error messages:

• Not a git repository : "This directory is not a git repository. Initialise one with git init or navigate to a repository."
• GitHub CLI not available : "GitHub CLI (gh) is not installed. Install it from https://cli.github.com or use manual branch creation."
• Issue not found : "Issue #123 not found. Check the issue number or create a branch manually."
• Invalid branch name : "Branch name contains invalid characters. Suggested: feature/valid-branch-name"
• Branch exists : "Branch feature/existing already exists. Switch to it with git checkout feature/existing or choose a different name."
• Network issues : "Unable to check remote branches. Proceeding with local creation only."

Examples

Example 1: GitHub Issue Integration

User: "Create a branch for issue #456"
Command: gh issue view 456
Output: #456 - Add user authentication (open)
Command: gh issue develop 456 -c
Output: Created and checked out branch: feature/456-add-user-authentication

Example 2: Manual with Auto-Prefix

User: "Create branch: fix login bug"
Analysis: Contains "fix" → apply "bugfix/" prefix
Validated: "bugfix/login-bug"
Command: git checkout -b bugfix/login-bug main

Example 3: Custom Prefix

User: "Create branch: docs/update readme"
Analysis: Already has "docs/" prefix → keep as-is
Validated: "docs/update-readme"
Command: git checkout -b docs/update-readme main

Best Practises

1. Always prioritise GitHub issue workflow when issue numbers are mentioned
2. Validate thoroughly before creating branches to avoid git errors
3. Use descriptive names that clearly indicate the purpose
4. Follow team conventions - check existing branch names for patterns
5. Push to remote early for backup and collaboration
6. Link branches to issues whenever possible for better project tracking

Weekly Installs

1.2K

Repository

ruchernchong/claude-kit

First Seen

Feb 13, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykWarn

Installed on

github-copilot988

opencode988

codex987

gemini-cli986

amp985

kimi-cli985