The git branch command is the main tool we use to manage branches in our Git project.
As we saw in the previous article, in Git branches are just lightweight labels, which allow us to have independent lines of project evolution.
Git’s philosophy is: “Create branches for everything”. Are you going to fix a typo? Create a branch. Are you going to test a new library? Create a branch.
They are cheap to create and easy to destroy. In this post we will see how to do it with the git branch command.
List branches: What’s in my project?
The first thing we usually do when entering a project is to see the landscape. To see what branches exist in your local repository, simply type:
git branch
The result will be something like this:
develop
feature/login
* main
testing
- The list: Shows you all available local labels.
- The asterisk (*): Indicates where you are right now. The asterisk points to the branch your
HEADis pointing to. In this case, we are working onmain.
Create a new branch
To create a new line of work we do,
git branch branch-name
For example:
git branch feature/new-menu
Common confusion. When you run this command, Git creates the branch, but does not move you to it.
If you run git branch right after, you will see:
feature/nuevo-menu
* main
The asterisk is still on main. You have created the label, but you are still “on” the main branch.
To move to the new branch we will have to use git switch (which we will see in the next article).
Delete branches
Once you have finished a task and have merged the code into the main branch, that “feature” branch is no longer useful. You can delete it if you want.
The standard way to delete a branch is with the -d (delete) option:
git branch -d feature/nuevo-menu
Git is very protective. Before deleting the branch, it will check if you have already merged it.
- If the changes from that branch are already in the current branch, it will delete it without complaint.
- If the branch contains changes that you have not merged (and which would be lost forever if you delete it), Git will give you an error:
error: The branch 'feature/nuevo-menu' is not fully merged.
Forced deletion (-D)
Sometimes you want to delete a branch with unmerged changes. For example, you made a branch to test an idea, the idea was a disaster and you want to throw all that code in the trash.
In that case, we use the capital D (which is an alias for —delete —force):
git branch -D feature/failed-experiment
This will delete the branch and the commits associated with it will be lost (they will become orphaned until the garbage collector eats them up).
You cannot delete the branch you are sitting on. Git will not allow you to delete the branch marked with the asterisk *.
First you have to move to another branch (main) and from there delete the other one.
Rename branches (-m)
Sometimes you misspell the name when creating it (feature/botno instead of boton). Or the scope of the task changes.
To rename the branch you are currently on:
git branch -m new-correct-name
If you want to rename a different branch (without moving to it):
git branch -m old-name new-name
