How to Rename Git Branches Locally and Remotely

To rename a Git branch both locally and remotely, you need to first rename the local branch using git branch -m, then delete the old remote branch with git push origin --delete old-name, and finally push the new branch with git push origin -u new-name. The git remote rename command is for renaming remote repository aliases, not branches within a repository, which is why you received the error about config sections.

Contents

• Understanding the Problem
• Correct Procedure for Renaming Branches
• Step-by-Step Guide
• Handling Special Cases
• Common Pitfalls and Solutions
• Best Practices

Understanding the Problem

The error you encountered with git remote rename regacy legacy occurs because this command is designed for renaming remote repository aliases (like changing “origin” to “upstream”), not for renaming branches within a remote repository.

As GitHub Docs explains, “This error means that the remote you tried to change doesn’t exist” - but in your case, it’s more about using the wrong command for the intended purpose.

The git remote rename command modifies your local Git configuration, changing how you refer to a remote repository as a whole. It cannot rename individual branches within that repository. Renaming a remote branch requires a different approach that involves deleting the old branch and creating a new one.

Correct Procedure for Renaming Branches

To rename a branch both locally and remotely, you need to follow a specific sequence of commands:

1. Rename the local branch
2. Delete the old remote branch
3. Push the new branch to the remote
4. Set the upstream tracking

As Linuxize states, “Renaming a local Git Branch is a matter of running a single command. However, you can’t directly rename a remote branch; you need to push the renamed local branch and delete the branch with the old name.”

Step-by-Step Guide

Renaming to origin/legacy (fixing the typo)

Here’s the complete procedure:

Step 1: Switch to the branch you want to rename

git checkout regacy

Step 2: Rename the local branch

git branch -m legacy

Step 3: Delete the old remote branch

git push origin --delete regacy

Step 4: Push the new branch to the remote

git push origin -u legacy

Step 5: Update your local tracking branch

git fetch origin
git branch -u origin/legacy legacy

Alternative approach (combining steps)

You can also combine steps 3 and 4 into a single command:

git push origin -u legacy :regacy

This command simultaneously pushes the new branch (legacy) and deletes the old one (regacy) in one operation.

Renaming to origin/master (different scenario)

If you want to rename regacy to master instead:

Step 1: Switch to the branch you want to rename

git checkout regacy

Step 2: Rename the local branch

git branch -m master

Step 3: Delete the old remote branch

git push origin --delete regacy

Step 4: Push the new branch to the remote

git push origin -u master

Note: If master is the default branch, you may need to update the repository settings on GitHub/GitLab to make master the new default branch.

Handling Special Cases

When the branch is the default branch

If you’re renaming the default branch (like master to main), you’ll need to update the repository settings:

1. GitHub: Go to Repository Settings → Branches → Change Default/Main Branch
2. GitLab: Go to Settings → Repository → Default branch
3. Bitbucket: Go to Repository Settings → General → Default branch

As mentioned in Stack Overflow, “For Github and Bitbucket users, when you run Step 2, it will create the new remote branch, but you will see an error from the remote about ‘refusing to delete the current branch’. So just go to Repository Settings → Branches → Change Default/Main Branch → new_branch_name → Save. Then run Step 2 again, so that it deletes the old remote branch name.”

When other collaborators are using the branch

If other team members are working on the branch, they’ll need to update their local copies:

# Collaborators should run:
git fetch origin
git checkout old-name
git branch -m new-name
git branch -u origin/new-name

Common Pitfalls and Solutions

Error: “refusing to delete the current branch”

This occurs when trying to delete a branch that is set as the default branch. Solution: Update the repository settings first, then delete the branch.

Error: “No such remote”

If you get “fatal: No such remote ‘regacy’”, check your remote names:

git remote -v

Make sure you’re using the correct remote name (usually origin).

Config file permission errors

As shown in your error message “Could not rename config section ‘remote.regacy’ to ‘remote.legacy’”, this can happen due to:

• File permission issues
• Another process using the Git config file

Solution: Check file permissions or close any other applications that might be accessing the config file.

Upstream tracking issues

After renaming, you might need to reset the upstream tracking:

git branch -u origin/new-branch-name

Best Practices

1. Communicate with your team: Before renaming a branch that others are using, notify them about the change.

2. Use descriptive branch names: Avoid typos and use clear, consistent naming conventions from the start.

3. Test the rename process: Consider doing a test rename on a throwaway branch first to understand the process.

4. Update CI/CD configurations: If your branch names are referenced in CI/CD pipelines, update those configurations accordingly.

5. Consider repository hygiene: Regularly clean up old branch names to keep your repository organized.

Remember that renaming a remote branch is not a direct operation - as FreeCodeCamp explains, “To be precise, renaming a remote branch is not direct – you have to delete the old remote branch name and then push a new branch name to the repo.”

Conclusion

Renaming a Git branch both locally and remotely requires following a specific sequence of commands since you cannot directly rename a remote branch. The key steps are: rename the local branch, delete the old remote branch, push the new branch, and update the upstream tracking. Remember that git remote rename is not the correct command for this purpose - it’s designed for renaming remote repository aliases, not individual branches. Always communicate with your team before renaming branches that others are using, and be prepared to update repository settings if you’re renaming the default branch.

Sources

1. Stack Overflow - Git: how to rename a branch (both local and remote)?
2. IONOS - How to rename a local and remote Git branch
3. FreeCodeCamp - How to Rename a Local or Remote Branch in Git
4. GitHub Docs - Renaming a branch
5. DataCamp - Git Rename Branch: How to Rename Local or Remote Branch
6. Linuxize - How To Rename a Local and Remote Git Branch
7. Git Tower - How to rename local and remote branches in Git
8. Better Stack Community - Git: how to rename a branch (both local and remote)?