How to Rename a Local Git Branch: A Step-by-Step Guide

Quick Answers: Renaming a Local Git Branch

1. Rename the Current Branch:

   git branch -m new-branch-name

2. Rename a Specific Branch (Not Currently Checked Out):

   git branch -m old-branch-name new-branch-name

3. Verify the Rename:

   git branch

Introduction

Renaming a Git branch is a common task when you realize a branch name is unclear, outdated, or doesn’t follow your team’s naming conventions. Whether you’re refining a feature branch or correcting a typo, Git makes renaming local branches simple. In this guide, we’ll walk you through how to rename a local Git branch using straightforward commands, explain what to do if the branch is already pushed to a remote repository, and share best practices to keep your Git workflow smooth. Let’s get started and give your branches better names!

Why Rename a Local Git Branch?

You might want to rename a branch for several reasons:

• Clarity: A vague name like test could be improved to feature/login-page.
• Consistency: Align with team naming conventions, e.g., bugfix/issue-123.
• Mistakes: Fix typos or incorrect names.
• Project evolution: Update branch names to reflect new project goals.

Renaming a local branch is quick and safe as long as you follow the correct steps, especially if the branch hasn’t been shared with others yet.

Detailed Explanation: Renaming a Local Git Branch

Step 1: Rename the Current Branch

If you’re already on the branch you want to rename, use the git branch -m command with the new name.

• Command:

  git branch -m new-branch-name

• Example:

  git branch -m feature-old feature-login-page

• What it does: Renames the current branch to new-branch-name.
• Note: The -m flag stands for “move” or “rename.”

Step 2: Rename a Different Branch

If you’re not on the branch you want to rename, specify both the old and new names.

• Command:

  git branch -m old-branch-name new-branch-name

• Example:

  git branch -m bug-fix bugfix/issue-123

• What it does: Renames the specified branch without needing to check it out first.

Step 3: Verify the Rename

After renaming, check your branch list to confirm the change.

• Command:

  git branch

• Example Output:

  * feature-login-page
    main

• Tip: The asterisk (*) indicates the current branch.

Step 4: Handling a Pushed Branch

If the branch was already pushed to a remote repository (e.g., GitHub, GitLab), you’ll need to update the remote after renaming locally.

1. Push the renamed branch:

   git push origin new-branch-name

2. Delete the old branch from the remote:

   git push origin --delete old-branch-name

3. Update local tracking (if needed):
   If your local branch was tracking the old remote branch, reset the upstream:

   git branch --set-upstream-to=origin/new-branch-name

• Example:

  git branch -m feature-old feature-login-page
  git push origin feature-login-page
  git push origin --delete feature-old
  git branch --set-upstream-to=origin/feature-login-page

Using a Git GUI to Rename a Branch

Prefer a visual interface? Tools like SourceTree, GitKraken, or Visual Studio Code make renaming branches easy:

1. Open your Git client and navigate to the repository.
2. View the branch list or commit history.
3. Right-click the branch you want to rename and select “Rename.”
4. Enter the new name and confirm.
5. If the branch was pushed, use the GUI to push the new branch and delete the old one from the remote.

Common Pitfalls and How to Avoid Them

• Renaming the wrong branch: Double-check your current branch with git branch before renaming.
• Remote conflicts: If teammates are using the old branch, communicate the rename to avoid confusion.
• Tracking issues: After renaming a pushed branch, update the upstream to keep local and remote branches in sync.
• Invalid names: Use clear, descriptive names and avoid special characters that Git might reject.

Best Practices for Branch Naming

• Be descriptive: Use names like feature/add-cart or bugfix/login-error to reflect the branch’s purpose.
• Follow conventions: Stick to your team’s naming rules, e.g., issue-123/fix or hotfix/v1.2.
• Keep it short: Avoid overly long names, but ensure they’re meaningful.
• Rename early: Change branch names before sharing with others to minimize disruption.
• Document changes: Note branch renames in your project’s changelog or team chat.

Conclusion

Renaming a local Git branch is a simple process with the git branch -m command, whether you’re on the branch or renaming another. If the branch was pushed, a few extra steps ensure the remote repository stays in sync. By following the steps in this guide and adopting best practices, you’ll keep your Git repository organized and your branch names clear and professional.

Got a Git question or a naming tip? Share it in the comments or explore our Git tutorials for more version control insights!

Loved this guide? Subscribe to our newsletter for more Git tips and tricks, or check out our version control resources to level up your skills. Let’s keep your Git workflow clean and efficient!