git branch: listing, creating and deleting branches

git branch lists the branches in a repository, creates a new one, and deletes one you no longer need.

A branch is a pointer to a single commit, not a copy of the project. That explains the set of operations: see where the names point, put a new name on the current commit, remove a name that has done its job.

With no arguments the command prints the list, and the star marks the branch you are standing on:

$ git branch
  feature-x
* main

$ git branch -v            # the same plus the last commit of each branch
  feature-x 1ef2a5c first draft of the report
* main      1ef2a5c first draft of the report

Given a name, the command creates a branch at the current commit and leaves you exactly where you were. Moving is a separate command, git switch:

$ git branch feature-x     # create it, stay on main
$ git switch feature-x     # move there
Switched to branch 'feature-x'

Creating a branch takes no time even in a huge repository, because there is nothing to copy. The branch lives in the file .git/refs/heads/<name>, and inside it there is one line: a commit hash, forty characters.

Deleting and renaming

Lowercase -d removes only a branch whose work has already been merged somewhere else. If the work is saved nowhere, git refuses:

$ git branch -d feature-x
error: the branch 'feature-x' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D feature-x'

$ git branch -D feature-x  # delete it anyway
Deleted branch feature-x (was f57b8c6).

Capital -D asks no questions. Even it does not wipe commits off the disk: the pointer disappears, while the commits themselves can still be found by hash for a while through git reflog.

Renaming is -m. With two names it renames the branch you named, with one name the branch you are standing on:

$ git branch -m feature-x feature-y   # rename feature-x to feature-y
$ git branch -m draft                 # rename the current branch to draft

Common mistakes

git branch feature-x does not move you to the new branch. The classic scenario: someone creates a branch, makes a commit, and finds it in main. To create and move in one step, use git switch -c feature-x.

You cannot delete the branch you are standing on: error: cannot delete branch 'main' used by worktree at '/home/me/report'. Move somewhere else first, then delete.

Where this is in the book

Chapter 5. Branches: parallel versions of a project introduces a branch as a pointer and shows why you would keep several versions of a project at once.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.