NeuroAgent

How to Rename Local Git Branch: Complete Guide

Learn how to rename local Git branches that haven't been pushed to remote. Complete guide with commands, verification steps, and best practices for branch management.

#git-branch-management#git-local-commands#git-rename-branch#git-tutorial#git-workflow#version-control-tips
Question

How can I rename a local Git branch that has not been pushed to a remote repository?

NeuroAgent

To rename a local Git branch that hasn’t been pushed to a remote repository, you can use the git branch -m command. For branches that exist only locally and have never been pushed upstream, the process is straightforward - simply rename the branch using git branch -m <old_name> <new_name> or git branch -m <new_name> if you’re currently on the branch you want to rename.

Contents

Basic Local Branch Rename Commands

When working with a local Git branch that has never been pushed to a remote repository, you have several command options available:

Renaming the Current Branch

If you’re currently checked out to the branch you want to rename, use this simple command:

bash
git branch -m <new_branch_name>

This command renames the current branch to the new specified name. The -m flag stands for “move” and is shorthand for --move.

Renaming a Different Local Branch

If you want to rename a branch that you’re not currently on, specify both the old and new names:

bash
git branch -m <old_branch_name> <new_branch_name>

Alternative Syntax

You can also use the full command syntax without the -m flag:

bash
git branch --move <old_branch_name> <new_branch_name>

Both commands achieve the same result - moving the branch pointer from one name to another.

Step-by-Step Process for Unpushed Branches

Step 1: Check Current Branch Status

Before renaming, verify which branch you’re currently on and list all local branches:

bash
git branch -v

This will show you all local branches with their latest commit information.

Step 2: Rename the Local Branch

Use the appropriate command based on your current context:

Option A: When you’re on the branch to rename:

bash
git checkout <old_branch_name>
git branch -m <new_branch_name>

Option B: When renaming a different branch:

bash
git branch -m <old_branch_name> <new_branch_name>

Step 3: Verify the Rename

Confirm the branch has been successfully renamed:

bash
git branch -v

You should see the new branch name with the same commit history as before.

Step 4: Check for Upstream Tracking

Since this branch hasn’t been pushed to remote, there should be no upstream tracking set. Verify this with:

bash
git branch -vv

If you see any upstream references, you can remove them with:

bash
git branch --unset-upstream

Common Scenarios and Solutions

Scenario 1: Renaming the Currently Checked-Out Branch

This is the most common scenario where you want to rename your active branch:

bash
# You're currently on 'bugfix-feature'
git checkout -b bugfix-feature
git branch -m feature-bugfix-2024

Scenario 2: Renaming Multiple Local Branches

If you have several local branches to rename (none pushed to remote):

bash
git branch -m old-name new-name
git branch -m legacy-branch updated-legacy-branch
git branch -m experiment experimental-feature

Scenario 3: Undoing a Branch Rename

If you accidentally rename a branch, you can easily revert it:

bash
git branch -m <incorrect_name> <correct_name>

Scenario 4: Force Renaming (Advanced)

In rare cases where Git might prevent the rename due to conflicts, you can use the force option:

bash
git branch -M <new_name>  # Capital M for force move

Use this with caution as it can potentially cause issues in complex scenarios.

Verification and Troubleshooting

Verifying the Rename Operation

After renaming, always verify the operation was successful:

bash
# List all branches
git branch

# Show detailed branch information with commits
git branch -v

# Show tracking information
git branch -vv

Common Issues and Solutions

Issue: “fatal: ‘branch-name’ is not a branch”
This error occurs if you try to rename a non-existent branch. Double-check the branch name spelling.

Issue: “fatal: A branch named ‘new-name’ already exists”
This happens when there’s already a branch with the desired new name. Either:

  • Delete the existing branch first: git branch -D existing-branch
  • Choose a different name for your renamed branch

Issue: Permission denied when trying to rename
Ensure you have write permissions in the repository directory and the Git repository isn’t locked by another process.

Best Practices for Branch Management

Before Renaming

  1. Check for uncommitted changes: Ensure your working directory is clean with git status
  2. Communicate with your team: If others might be using the branch, coordinate the rename
  3. Consider the impact: Branch names should be descriptive and follow team conventions

After Renaming

  1. Update documentation: Any scripts or documentation referencing the old branch name
  2. Update IDE configurations: If your IDE has branch-specific settings
  3. Inform team members: Especially if this is a shared development branch

Branch Naming Conventions

  • Use descriptive, meaningful names
  • Follow consistent patterns (e.g., feature/description, bugfix/issue-number)
  • Include relevant dates or version numbers when appropriate
  • Avoid special characters and spaces

When to Rename Branches

  • When the original name no longer reflects the branch’s purpose
  • When following new team naming conventions
  • When fixing typos in branch names (early in the branch lifecycle)
  • When consolidating similar functionality

Conclusion

Renaming a local Git branch that hasn’t been pushed to a remote repository is a straightforward process using the git branch -m command. The key advantages of renaming local-only branches are that there’s no need to coordinate with remote repositories or team members, and the operation can be undone easily if needed. Always verify the rename operation and follow best practices for branch naming to maintain clarity in your version control workflow. For branches that have been pushed to remote repositories, additional steps are required to update both local and remote branches, but for purely local branches, the simple rename command is all you need.

Sources

  1. Stack Overflow - How can I rename a local Git branch?
  2. Linuxize - How To Rename a Local and Remote Git Branch
  3. IONOS Digital Guide - How to rename a local and remote Git branch
  4. DataCamp - Git Rename Branch: How to Rename Local or Remote Branch
  5. Better Stack Community - git: how to rename a branch (both local and remote)?
  6. Ultahost Knowledge Base - How to Rename a Local and Remote Git Branch
  7. W3Docs - How to Rename Git Local and Remote Branches
How do I rename a Git branch that has already been pushed to a remote repository?What's the difference between git branch -m and git branch -M commands?How can I rename multiple Git branches at once?What are the best practices for naming Git branches in a team environment?How do I undo a Git branch rename if I made a mistake?Can I rename a Git branch while it has uncommitted changes?
Ask NeuroAgent