Git Tutorials/Branching



Figure 1: Example of basic workflow with branching. The figure can show a local or a remote repository omitting depictions of commit and push operations to keep it simple (they happen somewhere on the dashed lines). Initially, two branches are created from the main branch. Two independent developments occur on those new branches visualized by the different colors green and orange. Theses branches can both belong to one or to two different developers. Once the green segment is finished, its contribution is merged into the main branch and work on the green segment branch stops. On the other side, the orange segment is developed simultaneously. When development is finished, a new branch is created from this branch. Instead of directly merging the orange branch into the main branch it continues development on some light purple features while in parallel some brown features are added to orange (e.g., solving bugs in orange code). Later, a merge operation combines the orange/brown and orange/purple branch together and subsequently those orange/brown/purple changes are merged into the main branch as well. At this point the main branch will contain contributions from all branches. Unlike the green branch, the orange/brown/purple branch continues to exist, because its purple features are still expanded and will later be merged again into the main branch.

Branching is an important feature of Git, which enables simultaneous work on different parts of a code with minimal interference between acting parties. As the name implies, branching refers to the creation of a separate line of repository tracking that branches of from your "main" repository (also called a branch, but can be understood as the trunk). When developing new features you do not necessarily want to directly commit your changes to "main", because they might interfere with your colleagues contribution of other features on a different branch. Even when differences do not directly interfere, they can still lead to a more cumbersome merge of both branches into "main", once all changes are complete. In larger projects this merge ing into the "main" branch is often blocked for most users. A so-called pull request must be made, so that a responsible person can pull your changes from your branch and merge them into "main". To view all existing branches use the git branch --list command:

1user@HPC.NRW:~$ git branch --list
2* main

We can see that currently the project contains only one branch called "main" (line 2). The "*" next to it is used to mark our current branch. Before we continue with the tutorial, a look at Figure 1 might be helpful. It visualizes the basic idea behind branching within a repository. Moreover, we can see the similarities between the relation of other branches to the main branch and the relation of a local repository to the remote repository.

Handling Branches

Creating a new branch is as easy as entering git branch <name of branch>:

1user@HPC.NRW:~$ git branch branchingTut
2user@HPC.NRW:~$ git branch --list
3  branchingTut
4* main
5user@HPC.NRW:~$ git branch -a
6  branchingTut
7* main
8  remotes/origin/main

In above example we can see that creating a new branch does not imply switching to it (the "*" is still next to "main"). Further, displaying all local and remote branches through git branch -a, we see that the new branch does only exist locally and not in the remote repository unlike "main" (line 8). The new branch will be identical to the last commit of the current branch, in our case "main".

To switch to a different branch we use git checkout <name of branch>:

1user@HPC.NRW:~$ git checkout branchingTut
2M	someFile
3Switched to branch 'branchingTut'
4user@HPC.NRW:~$ git branch -a
5* branchingTut
6  main
7  remotes/origin/main

Line 2 informs us about a Modified file named "someFile". This can happen if we make changes to our repository (like Adding or Modifying files), but do not commit them before switching the branch. Naturally, this also happens when we want to switch to a branch with different contents than in hour current branch. Keep in mind that a git checkout <name of branch> is not like a git clone operation and therefore does not make a full copy of a different code branch. Instead, it tracks the commit history of the chosen branch and reproduces the changes in your repository. Any modifications you commit now will be added to that branch.

Further remarks If we want to create a new branch and directly switch to it, we use git checkout -b <name of new branch>. Usually, a branch is created from the most recent commit of the branch you are currently on. If we want to create it from a different branch (and switch to it), we will have to use git checkout -b ＜name of new branch＞ ＜name of different branch＞. To delete a branch we type git branch -d <name of branch>. However, this will not be possible if the branch contains uncommitted changes. We either have to perform a commit first or use the option -D instead of -d. Deleting a branch as shown above only deletes its local version. A remote branch has to be deleted this way: git push <name of remote repository> --delete <name of remote branch> Renaming our current branch is done through the command git branch -m <new name of branch>.

Remote Branches

If others are supposed to have access to our branch (or we want to have access from different locations), we need to make sure that it also exists in the remote repository by entering git push <name of remote repository> <name of branch>:

 1user@HPC.NRW:~$ git push origin branchingTut
 2Username for 'https://github.com': HPC.NRW-User
 3Password for 'https://HPC.NRW-User@github.com': ********
 4#Enumerating objects: 15, done.
 5Counting objects: 100% (15/15), done.
 6Delta compression using up to 12 threads
 7Compressing objects: 100% (13/13), done.
 8Writing objects: 100% (13/13), 42.00 KiB | 10.50 MiB/s, done.
 9Total 13 (delta 6), reused 0 (delta 0)
10remote: Resolving deltas: 100% (6/6), completed with 1 local object.
11remote: 
12remote: Create a pull request for 'branchingTut' on GitHub by visiting:
13remote:      https://github.com/HPC.NRW-User/Wikipages/pull/new/branchingTut
14remote: 
15To https://github.com/HPC.NRW-User/Wikipages.git
16 * [new branch]      branchingTut -> branchingTut
17 
18user@HPC.NRW:~$ git branch -a
19* branchingTut
20  main
21  remotes/origin/branchingTut
22  remotes/origin/main

This is very similar to the previous push operations with the only difference being that instead of the "main" branch in the remote repository, we will be using the "branchingTut" branch. As this branch did not exist yet, it will be created for us. In lines 18 to 22 we can see all existing branches including the newly created remote branch.

A remote checkout works the same way a local checkout does. The main difference is that your local repository might not be up to date with remote branch information, which is why we might miss updates on existing branches (as well as respective git log data). Below, you can see Git output for a user who cloned our repository after the first tutorial, but before branching was introduced:

1otherUser@HPC.NRW:~$ git branch -a
2* main
3  remotes/origin/HEAD -> origin/main
4  remotes/origin/main

In order to see the newest changes in the remote repository, they need to use the fetch command:

 1otherUser@HPC.NRW:~$ git fetch
 2Username for 'https://github.com': HPC.NRW-otherUser
 3Password for 'https://HPC.NRW-otherUser@github.com': 
 4remote: Enumerating objects: 15, done.
 5remote: Counting objects: 100% (15/15), done.
 6remote: Compressing objects: 100% (7/7), done.
 7remote: Total 13 (delta 6), reused 13 (delta 6), pack-reused 0
 8Unpacking objects: 100% (13/13), done.
 9From https://github.com/HPC.NRW-User/Wikipages
10 * [new branch]      branchingTut -> origin/branchingTut
11
12otherUser@HPC.NRW:~$ git branch -a
13* main
14  remotes/origin/HEAD -> origin/main
15  remotes/origin/branchingTut
16  remotes/origin/main

Line 10 informs them that a new branch exists in the remote repository. Lines 12 to 16 show that they can see the "branchingTut" branch, however, they still do not have a local version of it. Using git checkout <name of remote branch> they can then create a local branch based on the remote one.

Further remarks It is possible to display updated remote repository information without actually updating:git ls-remote origin git fetch <name of remote branch> can be used to only update information on one particular remote branch. If more than one remote repository is available, git remote update will update information on all of them. If we have several remote repositories, we need to further specify the desired branch: git checkout -b <name of branch> <name of remote repository>/<name of remote branch> git checkout is actually more versatile and not only used for switching or restoring branches. Therefore, beginning with version 2.23, Git introduced git switch <name of existing branch> for switching to a different branch. git switch -c <name of new branch> creates a new branch and switches to it. git switch is still marked as experimental in the Git documentation, which is why we only mention it here.

Best Practices

• Always start a new branch when working on a new feature and merge your changes and additions into the main branch, once the work is finished.
• Common branches are: main, develop, feature, release, hotfix. Naturally, those branches can have branches as well, e.g., when multiple features are being developed at the same time. However, depending on your environment, completely different naming conventions can be sensible.
• Several strategies exist on the structured creation of branches and branching conventions. We cover them here.

Glossary

• branch: Used for creating new branches and displaying branch information.
• fetch: Used to update information on remote repositories (and branches).

Useful Links

• Interactive GitHub course: Introduction and basic branch operations
• Paper on aspects of RSE: Section 3.2.3 contains information on different branching workflows and where they are employed.