Why Rename Branches?¶

When using Git for version control, branch names may need modification due to early unclean naming, team collaboration requirements, or branch logic adjustments. For example, an old branch named dev_old might need to be changed to a more concise dev, or the team may need to standardize branch naming rules. Renaming branches improves code structure clarity and avoids confusion.

Preparation Before Renaming¶

Ensure the following before starting the renaming process:
1. No Uncommitted Changes in Local Branch: Commit or stash all local branch modifications first (check with git status to avoid losing uncommitted content after renaming).
2. Confirm Branch Ownership: If the branch involves multiple collaborators, notify team members in advance to prevent conflicts from others working on the old branch.

I. Renaming a Local Branch (Safe First Step)¶

Git supports direct renaming of local branches, which is simple and risk-free.

Step 1: Execute the Rename Command¶

Open the terminal, navigate to the project directory, and run:

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

• Example: To rename the local branch dev_old to dev:

  git branch -m dev_old dev

Step 2: Verify Local Branch Renaming Success¶

Run git branch to check the local branch list. Confirm the new branch name appears and the old one is removed:

git branch

Example Output (new branch dev exists, old branch dev_old does not):

* dev
  main

II. Renaming a Remote Branch (Caution Required)¶

Git does not directly support renaming remote branches. The safe approach is: delete the old remote branch, push the local new branch to the remote, and then link the local and remote branches.

Step 1: Delete the Old Remote Branch¶

Execute the command to remove the old branch from the remote repository (origin is the default remote name; replace with the actual repo name if needed):

git push origin --delete old-branch-name

• Example: Delete the remote branch dev_old:

  git push origin --delete dev_old

⚠️ Warning: This operation is irreversible! Before deletion, confirm the branch has no important unmerged content (check commit history with git log).

Step 2: Push the Local New Branch to the Remote¶

Push the locally renamed new branch to the remote repository (remote has no new branch yet, so manual linking is required):

git push origin new-branch-name

• Example: Push the local branch dev to the remote:

  git push origin dev

Step 3: (Optional) Link Local and Remote Branches¶

To directly sync with the remote branch via git pull/git push, set the tracking relationship:

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

• Example: Link local dev to remote dev:

  git branch --set-upstream-to origin/dev

III. Verification After Renaming¶

1. Check Remote Branches: Run git branch -r ( -r for remote branches) to confirm the old branch is removed and the new one exists:

   git branch -r

Example Output:

   origin/main
   origin/dev

2. Test Branch Switching: Switch to the new branch to confirm functionality:

   git checkout new-branch-name

Notes¶

1. Avoid Conflicts in Multi-Person Collaboration: After renaming the remote branch, team members should run git fetch --prune (clean up invalid remote branch references) and update local branch names.
2. Merge Before Renaming: If merging the branch into the main branch, merge first before renaming to avoid merge conflicts.
3. Risk of Remote Branch Deletion: If the remote branch contains important unmerged content, create a backup branch first or contact the administrator for confirmation before deletion.

By following these steps, you can safely rename local and remote branches, preventing data loss while ensuring smooth team collaboration. If issues arise, use git --help or consult the official Git documentation for assistance.