Look, we've all been there. You start a feature, name the branch fix-bug, and three hours later you realize you’re actually rewriting the entire authentication module. Using a generic name is a recipe for chaos when you finally open that Pull Request. You need to fix it. Honestly, knowing how to git rename a local branch is one of those "quality of life" skills that separates the juniors from the seniors who actually have a clean workflow.
It’s easy. Mostly. But there are a few edge cases—like when you’re currently on the branch versus when you’re looking at it from afar—that trip people up.
The Quick Command Everyone Forgets
If you are already sitting on the branch you want to rename, the command is dead simple. You just use the -m flag. Think of it as "move." In the world of Unix and Git, moving and renaming are basically the same operation.
git branch -m new-branch-name
That’s it. You’re done. But what if you’re currently on main and you realize your local branch feature-123 should actually be login-logic-refactor? You don't actually have to switch branches just to rename it. That’s a common misconception that wastes time. You can pass both the old and new names directly:
git branch -m old-branch-name new-branch-name
Why Renaming Locally Isn't Enough
Here is where it gets kinda annoying. Git is a distributed version control system. When you git rename a local branch, Git doesn't automatically go and tell your remote (like GitHub or GitLab) that you changed your mind. Your local machine knows about login-logic-refactor, but the cloud still thinks it’s feature-123.
If you've already pushed the old branch name to the server, you have a bit of cleanup to do. You can’t just "rename" a remote branch in one click. You basically have to delete the old one and push the new one.
- Push the new name:
git push origin -u new-branch-name - Delete the old name from the remote:
git push origin --delete old-branch-name
The -u flag is important here. It sets the upstream tracking. Without it, your local branch won't know which remote branch to pull from next time you type git pull. It’s like moving into a new house but forgetting to tell the post office where you went.
The Case Sensitivity Trap
Windows and Mac users, listen up. This is a weird one. If you are trying to change a branch name from Feature-Branch to feature-branch (just changing the casing), Git might get confused depending on your file system.
Since some systems are case-insensitive, Git might think the name is already the same. If git branch -m feature-branch doesn't work because Git says the branch already exists, you have to do a two-step dance. Rename it to something completely different first, like feature-branch-tmp, and then rename it to your desired lowercase version. It’s clunky, but it works every time.
Advanced Scenarios: Re-pointing Your Upstream
Sometimes you rename a branch and forget the -u flag. Now you're in a state where your local branch is called cool-new-thing but it’s still trying to track old-boring-thing on the remote.
You'll see a message like "Your branch is up to date with 'origin/old-boring-thing'." That’s not what you want.
To fix this without deleting everything, use this:git branch --set-upstream-to=origin/new-branch-name new-branch-name
This re-links the logic. It’s basically surgery for your .git/config file without having to actually open that terrifying file in Vim.
Dealing with Other People's Confusion
If you are working on a team, renaming a branch that has already been shared is... risky. Sorta.
If your teammate has already checked out old-branch-name, and you delete it from the remote to rename it, their local environment is going to get grumpy. They will see errors about a "non-existent ref."
If you must rename a shared branch, communicate it clearly. Tell them to run git fetch --prune. This cleans up their local references to deleted remote branches. Then they can just check out the new one.
Practical Checklist for a Clean Rename
Don't just run commands blindly. Follow this flow to ensure you don't lose work or break the CI/CD pipeline:
- Check your status. Make sure you don't have uncommitted changes that might get lost if something goes sideways (though renaming is usually safe).
- Run
git branch -ato see all your branches and make sure the "new" name isn't already taken by some forgotten experiment from six months ago. - Execute the local rename with
git branch -m. - If pushed previously, handle the remote delete-and-push sequence.
- Update your Pull Request. Most platforms like GitHub will realize the branch is gone and might close your PR. You'll need to open a new one or update the head ref.
The technical debt of a bad branch name is real. It makes your git log look like a junk drawer. Taking ten seconds to git rename a local branch keeps the history legible for the person who has to read your code a year from now. Usually, that person is you.
Moving Forward With a Better Workflow
Instead of constantly renaming, try to adopt a naming convention that works. Many teams use type/description or issue-number/description. For example: feat/oauth-fix or bug/122-header-overflow.
If you find yourself renaming branches every single day, your task definitions might be too vague. Narrow the scope of your work before you even run git checkout -b.
The next step is to audit your current local branches. Run git branch right now. If you see ten branches named test, temp, or fix1, go through and rename the ones worth keeping and delete the rest. Your future self will thank you for the clarity.
🔗 Read more: How to Edit a Podcast Without Losing Your Mind or Your Audience
Once you've mastered the local rename, look into git remote prune origin. It’s the best way to keep your local list of "remote branches" from becoming a graveyard of deleted ideas.