Git is a powerful version control system used by millions of developers worldwide. Whether you’re working solo or collaborating in a team, naming your branches clearly and consistently is crucial for readability and project organization. But what if you’ve already created a branch with a less-than-ideal name?
In this blog, we’ll walk you through how to rename a branch in Git—both locally and remotely—while preserving history and avoiding disruptions.
🧠 Why Rename a Branch?
There are several reasons why you might want to rename a Git branch:
- The name is unclear or misleading.
- You’ve adopted a new branch naming convention.
- You want to remove non-inclusive or outdated terminology (e.g., changing
mastertomain). - You’ve made a typo or want to correct formatting.
Regardless of the reason, renaming a branch is simple and safe if done correctly.
🧱 Prerequisites
- You should have Git installed on your system.
- You should be on the branch you want to rename or know its current name.
- Ensure no other team members are working on the branch during the renaming process (especially for remote branches).
🔄 How to Rename a Local Git Branch
✅ Option 1: Rename the current branch
If you’re already on the branch you want to rename, use:
git branch -m new-branch-name
✅ Option 2: Rename a different branch
If you’re not on the branch you want to rename:
git branch -m old-branch-name new-branch-name
-mstands for “move,” which Git uses to rename branches internally.
☁️ How to Rename a Remote Git Branch
Renaming a remote branch requires a few more steps:
Step 1: Rename it locally (as shown above)
git branch -m old-name new-name
Step 2: Delete the old branch name from the remote
git push origin --delete old-name
Step 3: Push the new branch name to remote
git push origin new-name
Step 4: Reset the upstream tracking
If you plan to continue working with the renamed branch:
git push --set-upstream origin new-name
This sets the new branch to track the remote version.
🧼 Clean Up: Inform Your Team
If you’re working in a team, communicate the change. Anyone using the old branch will need to:
git fetch origin
git checkout new-name
And optionally delete their old local branch:
git branch -d old-name
🛡 Best Practices When Renaming Branches
- Avoid unnecessary renames on shared branches.
- Coordinate with your team before renaming remote branches.
- Use meaningful names (e.g.,
feature/login-uiorbugfix/payment-error). - Avoid using spaces—stick to dashes or slashes.
🧭 Conclusion
Renaming a branch in Git is straightforward but requires careful steps, especially when working with remote repositories. With the steps above, you can ensure a clean and professional update to your project’s structure without disrupting your workflow.
Want more Git best practices or need help organizing your branching strategy? Stay tuned for upcoming posts or drop your questions in the comments!
Further Reading:
