Outline#
Welcome to the Branching chapter, where we delve into one of the most powerful features Git has to offer. Branching is what makes Git stand out from other version control systems. It allows you to diverge from the main line of development and work on multiple features, bug fixes, or experiments simultaneously, all without affecting the stable version of your project. The cost of it is minimum. No chaos, no conflicts—just organised, fearless tinkering!
In this page, you’ll learn the basic commands of Git branches. Whether you’re managing a solo project or collaborating with a large team, understanding branching will benefit you to keep your work organized, streamline your workflow, and avoid the chaos that can come with merging code from multiple contributors.
Branching#
So far, we only work in the “main” branch. Actually, Git allows us to create separate branches of our project. Each teammate can work on a different branch containing different changes so that a big task can be broken down into small pieces. To take advantage of git branching, you will need to communicate with teammates to finalize task allocation and learn how to review others work on GitLab. The video below will show you how to create, switch, and remove branches in practice.
We’ll learn how to merge and rebase branches later. Let’s focus on the fundamentals first.
When working as a team, the “main” branch should be the primary branch where the stable version of the project lives. Instead of working on the “main” branch, we should create a feature branch for each task and merge it into the “main” branch after development is finished. Let’s start by checking existing branches.
$ git branch
* main
As the output shows, this project only has one branch - the “main” branch. The star * at front indicates we are now at the “main” branch.
Create a New Branch#
Assume we are working on Task 1-create a main function. Let’s create a new branch for it.
git branch task-1-create-main-function
The name of new branches should be meaningful and unique! You can imagine the pain when your teammates see branches like “do-something” or “fix-stuff”. Now we need to switch (or checkout) to this new branch.
Checkout to a Branch#
After creating a new branch, we can switch to it by:
$ git checkout task-1-create-main-function
Switched to branch 'task-1-create-main-function'
If you see the same output, you are now at the new branch.
There’s a shortcut! You can run git checkout -b task-1-create-main-function to create and switch to the new branch in just one step.
Starting from version 2.23, you can run git switch -c task-1-create-main-function instead to create and switch to the new branch. To switch to an existing branch, simply remove -c. In addition, you can switch to the previous branch by running git switch -.
However, you may see a common error below in the future:
error: Your local changes to the following files would be overwritten by checkout:
[a list of filenames]
Please commit your changes or stash them before you switch branches.
Aborting
Git warns that “your local changes to the following files would be overwritten by checkout”. This means you forget to commit your changes on this branch. You may confirm it by checking the git status.
& git status
On branch xxx
Your branch is ahead of 'origin/xxx' by 1 commit.
(use "git push" to publish your local commits)
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: [filename_1]
modified: [filename_2]
...
no changes added to commit (use "git add" and/or "git commit -a")
You should see a list of modified files in the log. Since Git tracks all file changes, these changed files may be overwritten by files with the same names in the new branch. If so, these changes will be lost. Git surely wouldn’t allow this to happen. To resolve this issue, simply use git add and git commit to commit these changes before switching to the new branch.
If you don’t want to commit your changes, you can run git stash to temporarily stash your work. This command will keep your changes in a stash without committing them. After you are done with your work in another branch, you can switch back to this branch and restore your changes by running git stash pop.
Remember, each branch is independent to each other. Your changes in this branch will not affect the “main” branch. That’s it! You are now at the new branch. After you finish your work in this branch, you need to push it to GitLab repository to share your work with your teammates. You may use git push -u origin task-1-create-main-function to push this branch to the GitLab repository.
Before pushing, we recommend to do an additional step to avoid unexpected troubles. Keep it in mind as we will discuss it in page 9.
What else can git checkout do?#
git checkout can not only switch between branches. It can also undo unstaged changes!
For example, assume you have mistakenly done some changes to a file and you luckily haven’t staged it. If you certain that this file in the last commit is working, you can use that to replace it in the workspace by running git checkout -- <filename>. Just keep in mind that this works only for changes that have not been staged!
Remove a Branch#
Creating new branches is pretty easy. However, teammates together may create too many feature branches and this could lead to confusion. Actually, this happens a lot in the workplace.
For example, one teammate creates several feature branches for something and pushes them to the GitLab repository. After the job is done, the new work in those branches gets merged into the “main” branch and the feature branches shall be cleaned up, but the creator forgets to do. At this point, no one else is 100% sure whether these branches should be removed, and thus these branches stay there forever! You just need to give it a month or so to see how badly the branch list is polluted. To avoid such a scenario, it’s important to develop a good habit of cleaning up old feature branches.
To remove a branch, you cannot stay in that branch (You can’t remove yourself!). So you need to switch to any other branch first.
Next, use the following command to remove the “task-1-create-main-function” branch:
$ git branch -d task-1-create-main-function
Deleted branch task-1-create-main-function (was ad4fe0b).
Now “task-1-create-main-function” branch has been removed. However, Git may warn you with the following error message in the future:
error: The branch 'branch_name' is not fully merged. If you are sure you want to delete it, run 'git branch -D branch_name'.
It means this branch was never merged into any other branches. Git worries that you may lose your changes on this branch forever and thus asks you to confirm that you do want to remove it no matter what. If you truly want to remove it, run git branch -D branch_name as Git suggests.
But how to remove a remote branch? Page 11 will show you how.
Further Reading#
Learn Git Branching is a browser-based game that teaches you Git branching, and it’s fun!
Moving On#
Great! You’ve now mastered the most commonly used Git commands that cover the majority of daily operations. It’s time to confidently apply these basic techniques to manage our personal projects with a commit+push cycle in the next page.