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 simply changes the branch reference (i.e., the name used to identify the branch) — it is just a cosmetic change.

HANDS-ON: Rename local branches

Target You wish 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 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 for 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 delay to ensure the next commit has a different timestamp the one before.
Reason: Commit timestamps are rounded to the nearest second. If multiple commits have the same timestamp, the shape of git log output (which orders commits based on commit timestamp) can be slightly different from what we expect, which can be confusing.

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 log command:

  • --all: Shows all branches, not just the current branch.
  • --graph: Shows a graph-like visualisation (notice how * is used to indicate a commit, and branches are indicated using vertical lines).
 Sourcetree

Right-click on 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 use uppercase letters too, but many teams avoid them for consistency.

A common branch naming convention is to prefix it 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 prepping a release
  • experiment/ai-chatbot — for “just trying stuff”

Although forward-slash (/) in the prefix doesn't mean folders, some tools treat it kind of like a path so you can group related branches when you run git branch. Shown below is an example of how Sourcetree groups branches with the same prefix.

EXERCISE: branch-rename