create-branch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Language Conventions

语言规范

Infer language style from the project:

Analyze existing branches, commit messages, and documentation to detect the project's language variant (US English, UK English, etc.)
Match the spelling conventions found in the project (e.g., "synchronize" vs "synchronise", "center" vs "centre")
Maintain consistency with the project's established language style throughout branch names and command outputs

从项目中推断语言风格：

分析现有分支、提交消息和文档，检测项目使用的语言变体（美式英语、英式英语等）
匹配项目中已有的拼写规范（例如："synchronize" 对应 "synchronise"，"center" 对应 "centre"）
在分支名称和命令输出中始终保持与项目既定语言风格的一致性

Create Branch Command

创建分支命令

This command creates and checks out a new git branch with intelligent validation and GitHub issue integration.

此命令可创建并检出带有智能验证和GitHub Issue集成功能的Git分支。

Priority: GitHub Issue Integration

优先级：GitHub Issue集成

IMPORTANT: If the user provides an issue number (e.g., "#123", "123", or "issue 123"), ALWAYS prioritise using GitHub CLI's issue development workflow:

Check for GitHub CLI availability:
bash
```
gh --version
```
If not available, inform the user and fall back to manual branch creation.
Verify the issue exists:
bash
```
gh issue view <issue-number>
```
Display issue title and status to confirm.
Create branch linked to issue:
bash
```
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
Skip to remote push step (step 8 below)

重要提示：如果用户提供了Issue编号（例如："#123"、"123" 或 "issue 123"），请始终优先使用GitHub CLI的Issue开发工作流：

检查GitHub CLI是否可用：
bash
```
gh --version
```
如果不可用，请告知用户并回退到手动创建分支的方式。
验证Issue是否存在：
bash
```
gh issue view <issue-number>
```
显示Issue标题和状态以确认。
创建关联到Issue的分支：
bash
```
gh issue develop <issue-number> -c
```
- ```
-c
```
  参数会自动检出新创建的分支
- GitHub会根据Issue标题自动生成合适的分支名称
- 该分支会与Issue关联，以便更好地跟踪项目
跳转到远程推送步骤（下方的步骤8）

Manual Branch Creation Workflow

手动创建分支工作流

If no issue number is provided, follow this workflow:

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

1. Check Repository Status

1. 检查仓库状态

bash

git status

Verify:

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

bash

git status

验证：

工作目录是否干净，或是否存在可接受的未提交更改
当前分支信息
当前目录是否为Git仓库

2. Get Branch Name Input

2. 获取分支名称输入

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

3. 自动检测并添加前缀

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.

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

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. Validate Branch Name

4. 验证分支名称

Apply comprehensive validation:

执行全面的验证：

Kebab-Case Enforcement

强制使用短横线命名法（Kebab-Case）

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

转换为小写
将空格和下划线替换为短横线
确保格式为：
```
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

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

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

Length Validation

长度验证

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

最小长度：3个字符（不含前缀）
最大长度：100个字符（总计）

5. Check for Duplicates

5. 检查分支是否重复

Check both local and remote branches:

bash

undefined

检查本地和远程分支：

bash

undefined

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

git ls-remote --heads origin "<branch-name>"


如果分支已存在：
- **本地存在**：提供检出现有分支的选项
- **远程存在**：向用户发出警告并建议使用其他名称
- **两者都存在**：告知用户并询问是否要检出现有分支或选择其他名称

6. Determine Base Branch

6. 确定基准分支

Use smart defaulting:

Check if
```
main
```
exists:
bash
```
git rev-parse --verify main
```
If not, check if
```
master
```
exists:
bash
```
git rev-parse --verify master
```
If neither exists, use current HEAD
Allow user to specify different base branch if needed (ask before creating)

使用智能默认规则：

检查是否存在
```
main
```
分支：
bash
```
git rev-parse --verify main
```
如果不存在，检查是否存在
```
master
```
分支：
bash
```
git rev-parse --verify master
```
如果两者都不存在，则使用当前HEAD
允许用户指定其他基准分支（创建前询问用户）

7. Create and Checkout Branch

7. 创建并检出分支

bash

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

Confirm successful creation with a message showing:

Branch name
Base branch used
Current status

bash

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

显示包含以下信息的成功创建消息：

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

8. Remote Push Recommendation

8. 远程推送建议

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

If yes:

bash

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

询问用户："是否要将此分支推送到远程并设置跟踪？"

如果用户同意：

bash

git push -u origin <branch-name>

这将实现：

分支的远程备份
与团队成员协作
GitHub PR创建工作流
在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."

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

非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
```
切换到该分支，或选择其他名称。"
网络问题："无法检查远程分支。仅进行本地创建。"

Examples

示例

Example 1: GitHub Issue Integration

示例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

用户："为Issue #456创建分支"
命令：gh issue view 456
输出：#456 - 添加用户认证（开放状态）
命令：gh issue develop 456 -c
输出：已创建并检出分支：feature/456-add-user-authentication

Example 2: Manual with Auto-Prefix

示例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

用户："创建分支：修复登录bug"
分析：包含关键词"fix" → 应用"bugfix/"前缀
验证后名称："bugfix/login-bug"
命令：git checkout -b bugfix/login-bug main

Example 3: Custom Prefix

示例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

用户："创建分支：docs/更新README"
分析：已包含"docs/"前缀 → 保持原样
验证后名称："docs/update-readme"
命令：git checkout -b docs/update-readme main

Best Practises

最佳实践

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

当提及Issue编号时，始终优先使用GitHub Issue工作流
在创建分支前进行全面验证，避免Git错误
使用描述性名称，清晰表明分支用途
遵循团队规范 - 检查现有分支名称的模式
尽早推送到远程，以便备份和协作
尽可能将分支与Issue关联，以便更好地跟踪项目