Branch Rename Skill

Overview

This skill intelligently analyzes the differences between the current branch and the base branch (typically origin/main), then generates and applies a descriptive branch name following conventional commit conventions. The generated name uses kebab-case and accurately reflects the nature of the changes.

Naming Convention

Format

<type>/<description>

Branch Type Prefixes

Prefix	Purpose	Examples
`feat/`	New features	`feat/user-auth`, `feat/dark-mode`
`fix/`	Bug fixes	`fix/null-pointer`, `fix/memory-leak`
`docs/`	Documentation	`docs/api-guide`, `docs/setup`
`style/`	Formatting	`style/prettier`, `style/lint-rules`
`refactor/`	Code restructuring	`refactor/extract-utils`, `refactor/simplify-logic`
`perf/`	Performance	`perf/cache-queries`, `perf/lazy-load`
`test/`	Testing	`test/unit-coverage`, `test/e2e-auth`
`build/`	Build system	`build/webpack-config`, `build/deps`
`ci/`	CI/CD	`ci/github-actions`, `ci/deploy`
`chore/`	Maintenance	`chore/cleanup`, `chore/update-deps`

Description Guidelines

Kebab-case: lowercase words separated by hyphens
Length: 20 characters or less (excluding prefix)
Imperative mood: "add" not "added", "fix" not "fixed"
Specific: Clearly describes the primary change
Concise: No unnecessary words

Good examples:

feat/oauth-login ✓
fix/race-condition ✓
docs/quick-start ✓

Bad examples:

feat/AddOAuthLogin ✗ (not kebab-case)
fix/fixed-the-race-condition-in-auth ✗ (too long, past tense)
docs/documentation-updates ✗ (redundant)

Workflow

1. Verify Git Repository Status

Check if we're in a valid git repository:

git rev-parse --git-dir 2>&1

Expected output:

Success: .git or path to git directory
Failure: "not a git repository" error

Check current branch:

git branch --show-current

If detached HEAD state:

Error: Cannot rename branch - currently in detached HEAD state

You are not on any branch. To create a new branch from current state:
  git checkout -b <branch-name>

If on protected branch (main/master/develop):

Warning: You are on the protected branch '[branch-name]'

Creating new branches from protected branches is recommended:
  git checkout -b <new-branch-name>

Proceed with rename anyway? [y/n]

2. Identify Base Branch

Attempt to find the base branch in order of preference:

# Try origin/main
git rev-parse --verify origin/main 2>/dev/null

# If not found, try origin/master
git rev-parse --verify origin/master 2>/dev/null

# If not found, try local main
git rev-parse --verify main 2>/dev/null

# If not found, try local master
git rev-parse --verify master 2>/dev/null

Store the first successful result as BASE_BRANCH

If no base branch found:

Error: Cannot determine base branch

None of the following branches exist:
  - origin/main
  - origin/master
  - main
  - master

Please specify the base branch manually or create one.

3. Analyze Changes

Fetch comprehensive change information:

# Summary of changed files
git diff $BASE_BRANCH...HEAD --stat

# Detailed line-by-line changes
git diff $BASE_BRANCH...HEAD

# Commit messages on this branch
git log $BASE_BRANCH..HEAD --oneline

# Number of commits
git rev-list --count $BASE_BRANCH..HEAD

If no changes detected:

No changes detected between current branch and $BASE_BRANCH

This branch is either:
  - Fully merged into $BASE_BRANCH
  - Has no commits
  - Is synchronized with $BASE_BRANCH

No rename needed.

Parse the data to extract:

List of modified files with paths
Number of insertions and deletions
Commit messages for context
File patterns (identify directories/modules)

4. Determine Branch Type

Apply pattern matching logic:

File-based Detection

# Documentation changes
if files match: *.md, docs/*, README*
  → type: docs

# Test files
if files match: *test.*, *spec.*, __tests__/*, tests/*
  → type: test

# CI/CD configurations
if files match: .github/workflows/*, .gitlab-ci.yml, Jenkinsfile
  → type: ci

# Build configurations
if files match: package.json, Gemfile, requirements.txt, *.config.js
  → type: build

# Style/formatting
if files match: .prettierrc, .eslintrc, .editorconfig
  → type: style

Content-based Detection

# Analyze diff and commit messages for keywords

# New features (keyword presence in diffs/commits)
if contains: "add", "implement", "create", "new"
  → type: feat

# Bug fixes
if contains: "fix", "bug", "issue", "resolve", "correct"
  → type: fix

# Refactoring
if contains: "refactor", "restructure", "extract", "move", "rename"
  → type: refactor

# Performance
if contains: "optimize", "performance", "faster", "cache", "speed"
  → type: perf

# Default fallback
if no clear pattern:
  → type: chore

Multiple Types

If changes span multiple types:

Count file changes per type
Select the type with most changes
If tie, prioritize: feat > fix > refactor > others

5. Generate Description

Extract meaningful description from changes:

Identify primary module/component:

# From file paths: src/auth/login.ts → "auth"
# From multiple files in same dir → use directory name

Extract action from commits:

# From commit messages like "Add OAuth support"
# Extract: "oauth-support"

Combine module + action:

# If module: "auth", action: "oauth"
# Result: "auth-oauth"

# If action already includes module context
# Result: just use action

Sanitize description:

# Convert to lowercase
description=$(echo "$description" | tr '[:upper:]' '[:lower:]')

# Replace spaces/underscores with hyphens
description=$(echo "$description" | tr ' _' '-')

# Remove special characters
description=$(echo "$description" | sed 's/[^a-z0-9-]//g')

# Remove consecutive hyphens
description=$(echo "$description" | sed 's/--*/-/g')

# Trim to 20 characters
description=${description:0:20}

# Remove trailing hyphen if present
description=${description%-}

Examples of description generation:

Commits	Files	Generated Description
"Add OAuth login"	`src/auth/oauth.ts`	`oauth-login`
"Fix null pointer in payment"	`src/payment/process.ts`	`payment-null-ptr`
"Update API docs"	`docs/api.md`	`api-docs`
"Refactor validation utils"	`src/utils/validation.ts`	`validation-utils`
"Optimize database queries"	`src/db/query.ts`	`db-queries`

6. Construct New Branch Name

Combine type and description:

new_branch="${type}/${description}"

Validate the name:

# Check length (should be reasonable, typically < 50 chars total)
if [ ${#new_branch} -gt 50 ]; then
  # Truncate description further
fi

# Check for existing branch with same name
if git show-ref --verify --quiet "refs/heads/$new_branch"; then
  # Append number: feat/user-auth-2
  suffix=2
  while git show-ref --verify --quiet "refs/heads/${new_branch}-${suffix}"; do
    ((suffix++))
  done
  new_branch="${new_branch}-${suffix}"
fi

7. Check Current Branch Name

Compare with existing name:

current_branch=$(git branch --show-current)

# If already follows convention and is accurate
if [[ "$current_branch" =~ ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)/ ]]; then
  # Extract current description
  current_desc=${current_branch#*/}

  # Check similarity with generated description
  if [ "$current_desc" == "$description" ]; then
    echo "Current branch name is already appropriate: $current_branch"
    echo "No rename needed."
    exit 0
  fi
fi

8. Rename Branch

Perform the rename operation:

old_branch=$(git branch --show-current)

# Rename the branch
git branch -m "$old_branch" "$new_branch"

Verify the rename:

# Check new branch name
if [ "$(git branch --show-current)" == "$new_branch" ]; then
  echo "✓ Branch renamed successfully"
else
  echo "✗ Branch rename failed"
  exit 1
fi

9. Display Results and Instructions

Show summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Branch Renamed Successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Old name: [old_branch]
New name: [new_branch]

Reason: [Brief explanation of type and description choice]

Changes analyzed:
  - [X] files modified
  - [Y] insertions, [Z] deletions
  - [N] commits

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If branch was previously pushed to remote:

⚠ Remote Branch Update Required

This branch was previously pushed to remote as '[old_branch]'.
To update the remote:

1. Push the new branch:
   git push -u origin [new_branch]

2. Delete the old remote branch:
   git push origin --delete [old_branch]

3. (Optional) Update any open pull requests to point to new branch

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Check if branch has remote tracking:

# Check for remote tracking branch
if git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null; then
  # Remote tracking exists, show update instructions
fi

Examples

Example 1: Feature Addition

Scenario:

Current branch: feature-branch
Changes: Added user authentication with OAuth

Commands executed:

git diff origin/main...HEAD --stat
# Output: src/auth/oauth.ts | 120 +++++++
#         src/auth/login.ts  |  45 +++

git log origin/main..HEAD --oneline
# Output: a1b2c3d Add OAuth authentication
#         b2c3d4e Implement login flow

Analysis:

Type: feat (new functionality)
Primary module: auth
Action: oauth-login
Description: oauth-login (16 chars)

Result:

Old: feature-branch
New: feat/oauth-login

Reason: Detected new authentication feature in auth module

Example 2: Bug Fix

Scenario:

Current branch: bugfix
Changes: Fixed null pointer exception in payment processing

Commands executed:

git diff origin/main...HEAD --stat
# Output: src/payment/process.ts | 8 ++--

git log origin/main..HEAD --oneline
# Output: c3d4e5f Fix null pointer in payment processor

Analysis:

Type: fix (bug fix keywords)
Primary module: payment
Issue: null-pointer
Description: payment-null-ptr (17 chars)

Result:

Old: bugfix
New: fix/payment-null-ptr

Reason: Detected bug fix in payment processing module

Example 3: Documentation

Scenario:

Current branch: update-docs
Changes: Updated API documentation

Commands executed:

git diff origin/main...HEAD --stat
# Output: docs/api/v2.md      | 200 +++++++++++++
#         docs/guides/auth.md |  50 ++++

git log origin/main..HEAD --oneline
# Output: d4e5f6a Update API v2 documentation
#         e5f6g7h Add authentication guide

Analysis:

Type: docs (documentation files)
Focus: api-v2
Description: api-v2-guide (12 chars)

Result:

Old: update-docs
New: docs/api-v2-guide

Reason: Detected documentation updates for API v2

Example 4: Refactoring

Scenario:

Current branch: cleanup
Changes: Extracted validation logic into utilities

Commands executed:

git diff origin/main...HEAD --stat
# Output: src/utils/validation.ts | 150 ++++++++++++++
#         src/components/Form.tsx  |  80 ++------

git log origin/main..HEAD --oneline
# Output: f6g7h8i Extract validation to utility module
#         g7h8i9j Simplify form component

Analysis:

Type: refactor (code restructuring)
Module: validation
Action: extract-validation
Description: validation-utils (16 chars)

Result:

Old: cleanup
New: refactor/validation-utils

Reason: Detected refactoring of validation logic into utils

Example 5: Multiple Change Types

Scenario:

Current branch: various-updates
Changes: Added feature, fixed bugs, updated docs

Commands executed:

git diff origin/main...HEAD --stat
# Output: src/auth/oauth.ts   | 120 +++++++  (new file)
#         src/payment/fix.ts  |   8 +-    (bug fix)
#         docs/readme.md      |  10 +      (docs)

git log origin/main..HEAD --oneline
# Output: h8i9j0k Add OAuth authentication (major)
#         i9j0k1l Fix payment bug         (minor)
#         j0k1l2m Update readme            (minor)

Analysis:

Mixed types: feat (120 lines), fix (8 lines), docs (10 lines)
Primary type: feat (most significant change)
Focus: oauth from largest change
Description: oauth-auth (10 chars)

Result:

Old: various-updates
New: feat/oauth-auth

Reason: Primary change is new OAuth authentication feature
        (Also includes minor bug fix and doc update)

Technical Requirements

Required Tools

Tool	Purpose	Check Command
Git	Version control	`git --version`
Bash	Shell scripting	`bash --version`

Minimum Versions

Git: 2.0 or higher (for git diff ... syntax)
Bash: 4.0 or higher

Git Configuration

No special configuration required, but recommended:

# Set default branch name (optional)
git config --global init.defaultBranch main

Best Practices

Run before pushing: Rename branches early before pushing to remote
One focus per branch: Branches with mixed purposes are harder to name
Keep descriptions clear: Prioritize clarity over brevity
Follow team conventions: Adjust type prefixes if team uses different standards
Update PR titles: If PR exists, update title to match new branch name
Communicate changes: Inform team members if renaming shared branches

Limitations

Single branch focus: Best results when branch has one primary purpose
20-character limit: Very long descriptions get truncated
English descriptions: Generated names are in English
No semantic analysis: Cannot understand complex business logic
Pattern-based: Relies on file patterns and keywords
Local operation: Does not automatically update remote branches

Error Handling

Common Errors and Solutions

Error: Not a git repository

Cause: Current directory is not a git repository
Solution: Navigate to git repository or run git init

Error: Detached HEAD state

Cause: Not on any branch (e.g., checked out specific commit)
Solution: Create new branch with git checkout -b <name>

Error: Cannot determine base branch

Cause: No main/master branch exists
Solution: Create base branch or specify manually

Error: No changes detected

Cause: Branch is synchronized with base or has no commits
Solution: No action needed, branch is up to date

Error: Branch name already exists

Cause: Generated name conflicts with existing branch
Solution: Tool automatically appends number (e.g., feat/auth-2)

Error: Invalid ref format

Cause: Generated name contains invalid characters
Solution: Tool sanitizes automatically, but check for edge cases

Advanced Features

Custom Base Branch

Allow user to specify different base branch:

# Compare against different branch
git diff custom-base...HEAD --stat

Interactive Mode

Confirm before renaming:

Generated branch name: feat/oauth-login

Current: feature-branch
New:     feat/oauth-login

Proceed with rename? [y/n]

Dry Run Mode

Show what would happen without actually renaming:

# Simulate rename
echo "Would rename: $old_branch → $new_branch"
# Skip actual git branch -m command

Preserve Remote Connection

Automatically update remote tracking after rename:

git branch -m "$old_branch" "$new_branch"
git push origin -u "$new_branch"
git push origin --delete "$old_branch"

References

Git Branch Documentation: https://git-scm.com/docs/git-branch
Conventional Commits: https://www.conventionalcommits.org/
Git Best Practices: https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project

Notes

Branch renaming is a local operation by default
Remote branches must be updated separately if already pushed
Pull requests may need manual update after branch rename
Team members should be notified of branch name changes
Consider branch protection rules when renaming
Some CI/CD systems may be configured for specific branch names

rename-branch

Branch Rename Skill

Overview

Naming Convention

Format

Branch Type Prefixes

Description Guidelines

Workflow

1. Verify Git Repository Status

2. Identify Base Branch

3. Analyze Changes

4. Determine Branch Type

File-based Detection

Content-based Detection

Multiple Types

5. Generate Description

6. Construct New Branch Name

7. Check Current Branch Name

8. Rename Branch

9. Display Results and Instructions

Examples

Example 1: Feature Addition

Example 2: Bug Fix

Example 3: Documentation

Example 4: Refactoring

Example 5: Multiple Change Types

Technical Requirements

Required Tools

Minimum Versions

Git Configuration

Best Practices

Limitations

Error Handling

Common Errors and Solutions

Advanced Features

Custom Base Branch

Interactive Mode

Dry Run Mode

Preserve Remote Connection

References

Notes