Update Branch Fast

Automatically rename the current Git branch based on the actual work reflected in its diff.

When to Use This Command

Run this command when you need to:

• Rename a generic branch like dev-work or fix-stuff to something descriptive before opening a PR
• Align branch naming with your team conventions after the scope of work has shifted
• Clean up branch names that were created hastily during rapid prototyping

Consider alternatives when:

• Your branch has already been pushed and others are tracking it since renaming would break their references
• Your team uses auto-generated branch names from a project management tool

Quick Start

Configuration

Copy
name: update-branch-fast
type: command
category: git-workflow

Example Invocation

Copy
claude command:run update-branch-fast

Example Output

Analyzing diff between current branch and main...
Files changed: 6
  src/components/UserProfile.tsx (modified)
  src/hooks/useAvatar.ts (new)
  src/api/upload.ts (modified)
  tests/useAvatar.test.ts (new)

Detected work: Adding user avatar upload functionality
Suggested branch name: feature/add-user-avatar-upload

Rename branch from 'dev-work' to 'feature/add-user-avatar-upload'? [Y/n]
Branch renamed successfully.

Core Concepts

Branch Analysis Overview

Aspect	Details
Diff Source	Compares current branch against main using git diff main...HEAD
Name Format	Follows conventional prefix/description pattern (feature/, fix/, chore/)
Detection	Analyzes file paths, commit messages, and diff content for intent
Safety	Never renames if the branch is already pushed with upstream tracking
Undo	Provides the reverse rename command in output for easy rollback

Renaming Workflow

Current Branch
      |
      v
git diff main...HEAD
      |
      v
Analyze changed files
  + commit messages
  + diff content
      |
      v
Infer work category
  (feature/fix/chore/refactor)
      |
      v
Generate descriptive slug
      |
      v
Confirm and rename

Configuration

Parameter	Type	Default	Description
prefix	string	auto	Force a branch prefix: feature, fix, chore, refactor
separator	string	/	Character between prefix and description
max-length	integer	60	Maximum branch name length
dry-run	boolean	false	Show proposed name without renaming
base	string	main	Base branch to diff against

Best Practices

1. Run before your first push - Renaming a local-only branch is free; renaming a pushed branch requires coordinating with everyone who has checked it out.

2. Review the suggested name - The auto-detection is good but not perfect. A branch touching both auth and profile files might get named for the wrong feature so always confirm the suggestion.

3. Adopt a consistent naming convention - Whether you use feature/, feat/, or ft-, pick one and configure the prefix parameter in your project settings so all generated names match.

4. Include ticket numbers when applicable - If your workflow ties branches to issue trackers, append the ticket ID manually or configure a pattern like feature/PROJ-123-description.

Common Issues

1. Branch already has an upstream - The command refuses to rename pushed branches by default. Use --force only after confirming no one else is tracking it, then update the remote with git push origin --delete old-name && git push -u origin new-name.

2. Suggested name is too generic - When the diff spans many unrelated files, the analyzer may produce a vague name. Narrow the scope by providing a hint via --prefix fix or splitting the branch into focused pieces.

3. Name conflicts with existing branch - If the suggested name already exists locally, the command appends a numeric suffix. Delete the stale branch first if it is no longer needed and you want a clean name without the suffix.

4. Diff contains only configuration changes - When the diff is primarily config file changes like .env or package.json, the analyzer may not infer a meaningful feature name. Provide a manual prefix hint to guide the naming logic toward a relevant result.