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

---
description: Create a new git-flow style branch (feature/bugfix/hotfix/release) based on the task description.
argument-hint: "<task-description> [--base <branch>] [--no-push] [--type <type>]"
allowed-tools: [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:
```bash
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:
```bash
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:
```bash
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