How can I rename a local Git branch?

How to Rename a Local Git Branch

Learn the essential Git commands to safely and effectively rename a local branch, ensuring your repository stays organized and your workflow smooth.

Renaming a local Git branch is a common task in version control, often done to improve clarity, fix typos, or align with new naming conventions. While seemingly simple, it's important to understand the correct commands to avoid disrupting your workflow or repository history. This article will guide you through the process of renaming a local branch, covering both active and inactive branches, and provide best practices for a seamless experience.

Understanding Git Branch Renaming

Git provides a straightforward command for renaming branches. The primary command, git branch -m, allows you to change the name of a branch. The behavior of this command slightly differs depending on whether the branch you want to rename is your currently checked-out branch or another branch in your local repository.

flowchart TD
    A[Start: Decide to Rename Branch]
    A --> B{Is the branch you want to rename currently checked out?}
    B -- Yes --> C[Rename Current Branch]
    C --> D["git branch -m <new-branch-name>"]
    B -- No --> E[Rename Another Branch]
    E --> F["git branch -m <old-branch-name> <new-branch-name>"]
    D --> G[End: Branch Renamed Locally]
    F --> G

Decision flow for renaming a local Git branch

Renaming the Currently Checked-Out Branch

This is the most common scenario. If you are currently on the branch you wish to rename, Git makes it very simple. You only need to provide the new name for the branch. Git will automatically update your HEAD reference to point to the new branch name.

git branch -m <new-branch-name>

Renaming the current branch

Renaming Another Local Branch (Not Checked Out)

If the branch you want to rename is not your currently active branch, you need to specify both the old name and the new name. This tells Git exactly which branch to modify. Make sure you are on a different branch (e.g., main or develop) before attempting this.

git branch -m <old-branch-name> <new-branch-name>

Renaming a local branch that is not currently checked out

Verifying the Rename

After executing the rename command, you can verify that the branch has been successfully renamed by listing all your local branches. The old name should no longer appear, and the new name should be present.

git branch

Listing all local branches to verify the rename

1. Step 1: Check Current Branch

First, identify the branch you are currently on using git branch --show-current or git status. If it's the branch you want to rename, proceed to Step 2a. If not, proceed to Step 2b.

2. Step 2a: Rename Current Branch

If you are on the branch you wish to rename (e.g., feature/old-name), execute: git branch -m feature/new-name.

3. Step 2b: Rename Another Branch

If you are on a different branch (e.g., main) and want to rename feature/old-name, execute: git branch -m feature/old-name feature/new-name.

4. Step 3: Verify Rename

Confirm the rename by listing all local branches: git branch. The old name should be gone, and the new name should appear.