Create, switch, rename, delete

Why this matters

These four operations are the branch vocabulary you will use daily. They are simple, but two of them have a sharp edge (switching with uncommitted edits, deleting an unmerged branch), and older instructions on the internet use git checkout for everything, which confuses beginners. This lesson gives you the modern commands, the edges, and the translation.

Create and switch

$ git switch -c docs/12-windows-install-steps

Switched to a new branch 'docs/12-windows-install-steps'

-c means "create". The branch starts at the commit you were on (so update main first), and HEAD moves to it. To start from somewhere else without switching there first: git switch -c hotfix/23-region-name v1.2.0.

Switching to an existing branch:

$ git switch main

Switched to branch 'main'
Your branch is up to date with 'origin/main'.

git switch - goes back to the previous branch, like cd -. A typo gets a clear refusal:

$ git switch nope

fatal: invalid reference: nope

And a switch that would overwrite uncommitted edits is refused too — commit or stash first (lesson 5.7):

error: Your local changes to the following files would be overwritten by checkout:
	README.md
Please commit your changes or stash them before you switch branches.
Aborting

Edits that do not touch files differing between the branches simply come along; that is convenient when you realize you started editing on the wrong branch before committing.

Rename

$ git branch -m docs/12-windows-install-steps docs/12-windows-steps
$ git branch

* docs/12-windows-steps
  main

-m for "move". With one argument it renames the current branch. If the old name was already pushed, the remote still has it: push the new name (git push -u origin docs/12-windows-steps) and delete the old (git push origin --delete docs/12-windows-install-steps), or, better, rename before the first push.

Delete

$ git branch -d docs/33-faq-windows

Deleted branch docs/33-faq-windows (was 3008743).

Lowercase -d is the safe delete: Git checks that the branch's commits are reachable from another branch (merged) and refuses otherwise:

$ git branch -d feature/21-difficulty-filter

error: the branch 'feature/21-difficulty-filter' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D feature/21-difficulty-filter'
hint: Disable this message with "git config set advice.forceDeleteBranch false"

-D deletes anyway. The refusal is worth a look every time: if the branch was merged by squash on GitLab, Git cannot see that (the squash commit is different from the branch's commits) and -D is fine; if the branch simply was never merged, -D abandons the work. git branch --merged and --no-merged list which is which:

$ git branch --no-merged

  fix/15-empty-distance

You cannot delete the branch you are on; switch to main first. Remote branches are deleted separately (lesson 6.8).

The old way: git checkout

Before Git 2.23, one command did both jobs and more:

git checkout still works and appears in most older tutorials; the new commands exist because the old one silently did very different things depending on whether its argument was a branch or a file. Read checkout in a tutorial as whichever of the two new commands fits.

In the tools

Common mistakes

• Creating a branch while on another feature branch. It inherits that branch's commits. Check git status's first line before switch -c.
• -D by reflex. Read the refusal; --no-merged tells you what you would lose.
• Renaming after pushing and ending up with two remote branches. Rename first, or clean up the old remote name.
• Reading git checkout in a tutorial as something dangerous. It is just the old spelling of switch or restore.