gh-setouchi-h-cc-marketplace-packages-git/commands/create-branch.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Create a new git-flow style branch (feature/bugfix/hotfix/release) based on the task description.	<task-description> [--base <branch>] [--no-push] [--type <type>]	Bash(git status:*) Bash(git branch:*) Bash(git checkout:*) Bash(git switch:*) Bash(git rev-parse:*) Bash(git push:*) Bash(git fetch:*) Bash(git ls-remote:*) Bash(git pull:*)

Git-Flow Branch Creation

You are a Claude Code slash command that creates git-flow style branches based on task descriptions. Follow the protocol below exactly, using only the allowed tools.

Git-Flow Branch Types

• feature/: New features or enhancements (e.g., feature/user-authentication)
• bugfix/: Bug fixes for the next release (e.g., bugfix/login-error)
• hotfix/: Critical fixes for production (e.g., hotfix/security-patch)
• release/: Release preparation (e.g., release/v1.2.0)

Inputs

Parse the arguments provided to this command ($ARGUMENTS):

• First argument (required): Task description text that will be used to generate the branch name
• --base <branch>: Base branch to branch from (default: detect from main, master, or develop)
• --no-push: Do not push the new branch to remote after creation
• --type <type>: Force a specific branch type (feature, bugfix, hotfix, release) instead of auto-detecting

Example usage:

/git:create-branch "add user authentication with OAuth2" --base develop
/git:create-branch "fix login page crash" --type bugfix
/git:create-branch "prepare v1.2.0 release" --no-push

Protocol

1. Validate Repository State

Check the current repository state:

git status
git branch --show-current

• Ensure we are in a git repository
• Check for uncommitted changes (warn if present but don't block)
• Note the current branch

2. Detect Base Branch

If --base is not specified, detect the appropriate base branch:

git rev-parse --verify main 2>/dev/null || echo "not found"
git rev-parse --verify master 2>/dev/null || echo "not found"
git rev-parse --verify develop 2>/dev/null || echo "not found"

Priority order:

1. develop (if exists) - standard git-flow development branch
2. main (if exists)
3. master (if exists)
4. Current branch (as fallback)

3. Analyze Task Description

Analyze the task description to determine the branch type (if not forced with --type):

Feature detection (use feature/):

• Keywords: "add", "implement", "create", "new", "enhancement", "feature"
• Examples: "add user auth", "implement payment flow", "new dashboard"

Bugfix detection (use bugfix/):

• Keywords: "fix", "bug", "issue", "error", "problem", "crash", "broken"
• Examples: "fix login error", "resolve crash on startup"

Hotfix detection (use hotfix/):

• Keywords: "hotfix", "urgent", "critical", "security", "production", "emergency"
• Examples: "hotfix security vulnerability", "urgent fix for production crash"

Release detection (use release/):

• Keywords: "release", "version", "v\d+.\d+", "prepare for release"
• Examples: "release v1.2.0", "prepare for v2.0 release"

Default: If unclear, use feature/

4. Generate Branch Name

Convert the task description into a valid, consistent branch name. Use the following deterministic sanitization rules so different implementations produce the same result:

1. Remove stopwords (English, minimal set): the, a, an, and, or, but, for, to, with, in, on, at.
2. Convert to lowercase.
3. Replace any character not [a-z0-9-] with a hyphen.
   • Regex: /[^a-z0-9-]+/g → -
4. Collapse multiple hyphens into one.
   • Regex: /-+/g → -
5. Trim leading/trailing hyphens.
   • Regex: /^-+|-+$/g → ``
6. Limit to a reasonable length (e.g., 50 chars max) after the above steps.

Notes:

• This list of stopwords is intentionally small and stable to avoid unexpected removals. Teams may extend it, but should document additions to keep behavior predictable.
• Version-like strings (e.g., v1.2.0) will naturally become v1-2-0 via step 3.

Format: <type>/<descriptive-name>

Examples:

• "Add user authentication with OAuth2" → feature/add-user-authentication-oauth2
• "Fix login page crash on mobile" → bugfix/fix-login-page-crash-mobile
• "Hotfix security vulnerability in API" → hotfix/security-vulnerability-api
• "Prepare v1.2.0 release" → release/v1-2-0
• "Implement the new UI in the app" → feature/implement-new-ui-app ("the", "in" removed; punctuation normalized)

5. Check Branch Existence

Check if the branch already exists locally or remotely:

git rev-parse --verify <branch-name> 2>/dev/null
git ls-remote --heads origin <branch-name> 2>/dev/null

If the branch exists:

• Show a warning
• Suggest an alternative name (append -2, -v2, or date suffix)
• Ask user for confirmation to use alternative or cancel

6. Create Branch

Present the plan to the user:

Branch creation plan:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Type:        feature
Base:        develop
Branch name: feature/add-user-authentication-oauth2
Description: Add user authentication with OAuth2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This will:
1. Switch to base branch 'develop'
2. Pull latest changes from remote (if available)
3. Create and checkout new branch 'feature/add-user-authentication-oauth2'
4. Push to remote 'origin' (unless --no-push is specified)

Proceed? (yes/no)

Once confirmed:

1. Switch to base branch: git checkout <base-branch>
2. Pull latest changes: git pull origin <base-branch> (handle gracefully if remote doesn't exist)
3. Create and checkout new branch: git checkout -b <branch-name>
4. Verify creation: git branch --show-current

7. Push to Remote

If --no-push is NOT set:

1. Push with upstream tracking: git push -u origin <branch-name>
2. Verify push success
3. Report the result

If --no-push is set:

• Skip push
• Note that the branch is local only

Output

Print a summary:

✓ Branch created successfully

Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Branch:      feature/add-user-authentication-oauth2
Type:        feature
Base:        develop
Status:      pushed to origin
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

You are now on the new branch. Start working on:
"Add user authentication with OAuth2"

Next steps:
1. Make your changes
2. Commit with: /git:commit
3. Create PR when ready

Error Handling

• No task description provided: Show usage and examples
• Invalid base branch: List available branches and ask user to specify
• Branch already exists: Suggest alternative name or offer to switch to existing
• Uncommitted changes: Warn but allow proceeding (git will handle conflicts)
• Push failed: Report error and suggest manual push command
• Not a git repository: Show clear error message
• Network issues during pull/push: Report and suggest manual retry

Examples

Example 1: Feature branch with auto-detection

Command: /git:create-branch "add user authentication"
Result: feature/add-user-authentication

Example 2: Bugfix with explicit base

Command: /git:create-branch "fix login error" --base main
Result: bugfix/fix-login-error (from main)

Example 3: Hotfix without push

Command: /git:create-branch "critical security patch" --type hotfix --no-push
Result: hotfix/critical-security-patch (local only)

Example 4: Release branch

Command: /git:create-branch "prepare v1.2.0 release"
Result: release/v1-2-0

Notes

• Branch names follow kebab-case convention
• Special characters are converted to hyphens
• Version numbers (v1.2.0) are converted to v1-2-0
• Long descriptions are truncated to keep branch names manageable
• The command is idempotent: if something fails, it's safe to retry