Git-Mastery: Lessons

T6L4. Renaming Branches


Branches can be renamed, for example, to fix a mistake in the branch name.

This lesson covers that part.

Local branches can be renamed easily. Renaming a branch changes the branch reference (i.e., the name used to identify the branch). This is a cosmetic change: the commits, file contents, and merge relationships stay the same; only the name pointing to the branch tip changes.

HANDS-ON: Rename local branches

Target You want to rename fantasy (not yet merged) and textbooks (merged), as shown below:

gitGraph BT:
    %%{init: { 'theme': 'default', 'gitGraph': {'mainBranchName': 'main'}} }%%
    commit id: "m1"
    branch textbooks
    checkout textbooks
    commit id: "[textbooks] t1"
    checkout main
    branch fantasy
    checkout fantasy
    commit id: "[fantasy] f1"
    checkout main
    merge textbooks id: "[HEAD → main] mc1"

→
[rename branches]

gitGraph BT:
    %%{init: { 'theme': 'default', 'gitGraph': {'mainBranchName': 'main'}} }%%
    commit id: "m1"
    branch study-books
    checkout study-books
    commit id: "[study-books] t1"
    checkout main
    branch fantasy-books
    checkout fantasy-books
    commit id: "[fantasy-books] f1"
    checkout main
    merge study-books id: "[HEAD → main] mc1"

Preparation

Option 1: Create a fresh sandbox using the Git-Mastery app

  • Navigate inside the gitmastery-exercises folder.
  • Run the gitmastery download hp-branch-rename command.

The sandbox will be set up inside the gitmastery-exercises/hp-branch-rename folder.

Git-Mastery commands list | Report Git-Mastery bugs | How to update Git-Mastery

Option 2: Manually set up a sandbox

To create the repo samplerepo-books used in this hands-on practical, run the following commands in your terminal.

mkdir samplerepo-books
cd samplerepo-books
git init -b main
echo "Horror Stories" >> horror.txt
git add .
git commit -m "Add horror.txt"
git switch -c textbooks
echo "Textbooks" >> textbooks.txt
git add .
git commit -m "Add textbooks.txt"
git switch main
git switch -c fantasy
echo "Fantasy Books" >> fantasy.txt
git add .
git commit -m "Add fantasy.txt"
git switch main
sleep 1
git merge --no-ff -m "Merge branch textbooks" textbooks

The sleep 1 in line 17 adds a delay so the next commit has a different timestamp from the previous one.
Reason: Commit timestamps are rounded to the nearest second. If multiple commits have the same timestamp, git log output can look slightly different from what we expect because git log orders commits by commit timestamp.

steps:

 CLI

To rename a branch, use the git branch -m <current-name> <new-name> command (-m stands for 'move'):

git branch -m fantasy fantasy-books
git branch -m textbooks study-books
git log --oneline --decorate --graph --all  # verify the changes
⤷
*   443132a (HEAD -> main) Merge branch textbooks
|\
| * 4969163 (study-books) Add textbooks.txt
|/
| * 0586ee1 (fantasy-books) Add fantasy.txt
|/
* 7f28f0e Add horror.txt

Note these additional switches to the git log command:

  • --all: Shows all branches, not just the current branch.
  • --graph: Shows a graph-like visualization. * indicates a commit, and vertical lines indicate branches.
 Sourcetree

Right-click the branch name and choose Rename.... Provide the new branch name in the next dialog.

done!

SIDEBAR: Branch naming conventions

Branch names can contain lowercase letters, numbers, /, dashes (-), underscores (_), and dots (.). You can also use uppercase letters, but many teams avoid them for consistency.

A common branch naming convention is to prefix branch names with <category>/. Some examples:

  • feature/login-form — for new features (origin/feature/login-form could be the matching remote-tracking branch)
  • bugfix/profile-photo — for fixing bugs
  • hotfix/payment-crash — for urgent production fixes
  • release/2.0 — for preparing a release
  • experiment/ai-chatbot — for “just trying stuff”

Although a forward slash (/) in the prefix doesn't create folders in Git, some tools treat it like a path, which lets you group related branches when you run git branch. The example below shows how Sourcetree groups branches with the same prefix.

EXERCISE: branch-rename