# Rename Branch

> Rename a git branch. Analyzes changes against the main branch, decides on a conventional name, and executes the rename.

- Skill: `jimmypaolini/rename-branch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jimmypaolini/rename-branch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jimmypaolini/rename-branch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jimmypaolini (https://skillmd.com/u/jimmypaolini)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/jimmypaolini/rename-branch

---


# Rename Branch

This skill provides a standardized workflow for renaming a Git branch to comply with the repository's Conventional Commits naming conventions (`<type>/<scope>-<description>`).

## When to Use This Skill

- When the user asks to "rename this branch" or "give this branch a better name".
- When a branch name is rejected by a pre-push hook or CI validation and needs to be fixed.
- When the user wants the agent to automatically deduce a conventional branch name based on the current local changes.

## Workflow

When invoked, perform the following steps sequentially:

### 1. Analyze Changes

Use the terminal to understand what the branch is doing:

- Check the current branch: `git branch --show-current`
- Compare with the default branch to see what changed: `git diff --name-status main...HEAD`
- If there are uncommitted changes, check them too: `git status -s`

### 2. Determine the Conventional Name

Using the repository's naming convention (`<type>/<scope>-<description>`):

**Type**: Choose the appropriate type based on the nature of the changes.
<!-- types-start -->

| Type | Description |
| ---- | ----------- |
| `feat` | A new feature or capability that adds value for users |
| `fix` | A bug fix that addresses a specific issue or problem |
| `docs` | Documentation, AGENTS.md, SKILL.md, README, and planning files |
| `test` | Adding or correcting unit, integration, or end-to-end tests |
| `refactor` | Code restructuring that neither fixes a bug nor adds a feature |
| `style` | Formatting, whitespace, or code structure changes with no semantic effect |
| `perf` | A code change that improves performance (caching, query optimization, etc.) |
| `chore` | Housekeeping that doesn't modify src or test files (gitignore, editor config, etc.) |
| `ci` | GitHub Actions workflows, composite actions, and CI/CD scripts |
| `build` | Build system, Vite/Docker/Helm config, or external dependency integration |
| `revert` | Reverts a previous commit |

<!-- types-end -->

**Scope**: Identify the scope based on the directory of the modified files.
<!-- scopes-start -->

| Scope | Description |
| ----- | ----------- |
| `affirmations` | Python Jupyter notebook application for LangGraph affirmation generation |
| `caelundas` | Node.js CLI for astronomical calendar generation (NASA JPL ephemeris) |
| `configuration` | Workspace root config files (tsconfig, eslint, vitest, nx.json, etc.) |
| `conformetry` | Code generator templates and validation tests for generated instances |
| `dependencies` | Dependency version changes (upgrades, additions, removals via pnpm) |
| `deps` | Dependency version changes (upgrades, additions, removals via pnpm) |
| `deployments` | GitHub Actions workflows and CI/CD pipeline configuration |
| `documentation` | Markdown docs, skills, planning files, and AGENTS.md files |
| `infrastructure` | Helm charts, Terraform configs, and Kubernetes resources |
| `JimmyPaolini` | Static GitHub profile README project (markdown and assets) |
| `lexico` | TanStack Start SSR Latin dictionary web app with Supabase backend |
| `lexico-components` | Shared React/shadcn component library |
| `lexico-entities` | Shared TypeORM entities and GraphQL types |
| `lexico-ingestion` | Data ingestion scripts for Lexico |
| `meanderaw` | Greek meander (key/fret) SVG generator CLI and the composable motif/modifier library it reads |
| `sempientor` | Lexical gap discovery CLI that surveys English for morphological, phonotactic, and semantic gaps and coins words to fill them |
| `callidescope` | Call stack tracing and linting CLI, the configuration package it reads, and the packages that build and render its call graph |
| `codependix` | Dependency graph export CLI, the configuration package it reads, and the package that judges the graphs against declared rules |
| `codometer` | Code statistics measurement CLI, the configuration package it reads, and the packages that diff and render its pull request change report |
| `no-release` | Escape hatch: suppress semantic-release for any commit type |
| `release` | Version bumps and release commits generated by semantic-release |
| `reporting` | Pull request change report generation and the packages that diff and render it |
| `scripts` | Shell and TypeScript scripts in scripts/ (sync, setup, utilities) |
| `testing` | Vitest configuration, shared test utilities, and coverage setup |
| `synchronization` | Synchronization application and commands for automating workflows |
| `validation` | Validation CLI and the checks it runs, such as pull request metadata |

<!-- scopes-end -->

**Description**: Formulate a concise, lowercase, kebab-case description (e.g., `add-user-auth`).

_Note: If multiple scopes are touched, list them comma-separated in the title (e.g., `feat(lexico,logger): ...`) rather than reaching for a single umbrella scope._

### 3. Create a Backup (Safety First)

Be very cautious before taking any destructive actions (renaming or deleting remote branches). Always create a temporary backup branch to ensure no work is lost:

Preferred approach: invoke [backup-code](../backup-code/SKILL.md) before renaming so backup creation and recovery commands are documented.

```bash
branch_name="$(git branch --show-current)"
iso_timestamp="$(date -u +%Y-%m-%dT%H-%M-%SZ)"
git branch "backup/${branch_name}/${iso_timestamp}"
```

### 4. Execute the Rename

Proceed automatically with the best determined name without asking the user for permission. Run the appropriate Git commands to rename the branch.

```bash
git branch -m <type>/<scope>-<description>
```

### 5. Update Remote (If Applicable)

If the old branch was already pushed to the remote (`git status` shows it tracking an origin branch), you must push the new branch and delete the old one:

```bash
git push origin -u <new-branch-name>
git push origin --delete <old-branch-name>
```

If remote cleanup or rename operations are incorrect, use [restore-code](../restore-code/SKILL.md) with the backup branch to recover safely.

## Example Scenarios

### Scenario 1: Uncommitted feature in lexico

- _Changes_: Modified `applications/lexico/src/components/Button.tsx`
- _Derived Name_: `feat/lexico-button-component`
- _Action_: `git branch backup/old-name/2026-06-22T12-00-00Z`, then `git branch -m feat/lexico-button-component`

### Scenario 2: Pushed bugfix in caelundas

- _Changes_: Modified `applications/caelundas/src/utils/time.ts` (already pushed as `fix-time`)
- _Derived Name_: `fix/caelundas-time-calculation`
- _Action_: `git branch backup/fix-time/2026-06-22T12-00-00Z`, then `git branch -m fix/caelundas-time-calculation`, push new, and delete old remote.