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 our repository. Any modifications we commit now will be added to that 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. If we need to restore a deleted branch we can use git checkout -b <new/old name of branch> <SHA of its last commit>. The SHA-value has been touched upon, previously.

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＞. 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>.

Sometimes we want to switch to a different branch, but we have uncommitted changes in the current branch. In such a case, Git will not allow us to switch. If we do not want to perform a commit we can use the git stash functionality. With it we can safely put away all changes since the last commit. Afterwards, we can restore what has been put into the stash with git stash pop. Here is an example:

 1otherUser@HPC.NRW:~$ git checkout main
 2error: Your local changes to the following files would be overwritten by checkout:
 3	Branching
 4Please commit your changes or stash them before you switch branches.
 5Aborting
 6otherUser@HPC.NRW:~$ git stash
 7Saved working directory and index state WIP on branchingTut: 802006b Add branch deletion to conflictless merge
 8otherUser@HPC.NRW:~$ git checkout main
 9Switched to branch 'main'
10Your branch is ahead of 'origin/main' by 15 commits.
11  (use "git push" to publish your local commits)
12otherUser@HPC.NRW:~$ git checkout branchingTut 
13Switched to branch 'branchingTut'
14otherUser@HPC.NRW:~$ git stash pop
15On branch branchingTut
16Changes not staged for commit:
17  (use "git add <file>..." to update what will be committed)
18  (use "git restore <file>..." to discard changes in working directory)
19	modified:   Branching
20
21no changes added to commit (use "git add" and/or "git commit -a")
22Dropped refs/stash@{0} (fe7bb4e2c792a6dcecd4e576a22a6640410cb078)

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 branchingTut they can then create a local branch based on the remote one. As the branch already exists in the remote repository, the option -b is not required for branch creation using checkout.

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. If you switch to a local branch that has further developed than its remote version, Git will inform you:

otherUser@HPC.NRW:~$ git switch main
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

git switch is still marked as experimental in the Git documentation, which is why we only mention it here.

Merging Branches

Once work on a branch has progressed sufficiently, the changes can be merged into "main", i.e. that "main" will contain all changes and additions from the other branch. If the changes on the branch concern a separate file or new section in existing files, the merge can be performed without any additional work. However, sometimes merge conflicts can occure, for example when two branches want to modify the same code sections or when "main" has changed after a branch has been created from it. We will cover both scenarios beginning with the easy one, where everything works fine.

Generally, git merge <name of branch to merge> combines the given branch into our currently active branch, but first we need some content to merge. For a conflict free merge we will do the following:

1. Switch to "main"
2. Make sure it is locally up to date
3. Create an new branch "tempBranch" out of "main"
4. Create a new file "tempFile" and add it to "tempBranch"
5. Merge "tempBranch" into "main", so that "tempFile" can also be found in "main"
6. Write something into the first line of "tempFile" on "main"
7. Write the same thing into the first line of "tempFile" on "tempBranch"
8. Write something into the second line of "tempFile" on "tempBranch"
9. Merge "tempBranch" into "main" again
10. Remove "tempBranch"

Above, we have purposefully not mentioned any commit operations. Try it yourself or check the solution below.

Solution and remarks For the sake of improved readability we have added some blank lines in the commands and output below.

Remarks to some lines can be found at the bottom.

 1user@HPC.NRW:~$ git switch main
 2Switched to branch 'main'
 3Your branch is up to date with 'origin/main'.
 4user@HPC.NRW:~$ git checkout -b tempBranch
 5Switched to a new branch 'tempBranch'
 6
 7user@HPC.NRW:~$ touch tempFile
 8
 9user@HPC.NRW:~$ git add tempFile 
10
11user@HPC.NRW:~$ git commit -m "Add tempFile to tempBranch"
12[tempBranch b6bc099] Add tempFile to tempBranch
13 1 file changed, 0 insertions(+), 0 deletions(-)
14 create mode 100644 tempFile
15user@HPC.NRW:~$ git checkout main
16Switched to branch 'main'
17Your branch is up to date with 'origin/main'.
18
19user@HPC.NRW:~$ git merge -m "Merge tempBranch into main" tempBranch 
20Updating 7ea3b70..b6bc099
21Fast-forward (no commit created; -m option ignored)
22 tempFile | 0
23 1 file changed, 0 insertions(+), 0 deletions(-)
24 create mode 100644 tempFile
25
26user@HPC.NRW:~$ echo "firstLine" >> tempFile 
27user@HPC.NRW:~$ git add tempFile 
28user@HPC.NRW:~$ git commit -m "Write in first line of tempFile"
29[main 2a4a1d6] Write in first line of tempFile
30 1 file changed, 1 insertion(+)
31
32user@HPC.NRW:~$ git switch tempBranch 
33Switched to branch 'tempBranch'
34
35user@HPC.NRW:~$ touch tempFile; echo "firstLine" >> tempFile; echo "secondLine" >> tempFile; cat tempFile
36firstLine
37secondLine
38user@HPC.NRW:~$ git add tempFile ; git commit -m "Write in second line of tempFile"
39[tempBranch ee1bb34] Write in second line of tempFile
40 1 file changed, 3 insertions(+)
41
42user@HPC.NRW:~$ git switch main; cat tempFile
43Switched to branch 'main'
44Your branch is ahead of 'origin/main' by 2 commits.
45  (use "git push" to publish your local commits)
46firstLine
47
48user@HPC.NRW:~$ git merge -m "Merge with tempBranch without conflicts" tempBranch 
49Merge made by the 'recursive' strategy.
50 tempFile | 1 +
51 1 file changed, 1 insertion(+)
52 
53user@HPC.NRW:~$ cat tempFile
54firstLine
55secondLine
56 
57user@HPC.NRW:~$ git log --oneline
5820e8d8f (HEAD -> main) Merge with tempBranch without conflicts
598aa439f (tempBranch) Write in second line of tempFile
60
61user@HPC.NRW:~$ git switch branchingTut 
62Switched to branch 'branchingTut'
63user@HPC.NRW:~$ git branch -d tempBranch 
64error: The branch 'tempBranch' is not fully merged.
65If you are sure you want to delete it, run 'git branch -D tempBranch'.
66
67user@HPC.NRW:~$ git switch main
68Switched to branch 'main'
69Your branch is ahead of 'origin/main' by 15 commits.
70  (use "git push" to publish your local commits)
71user@HPC.NRW:~$ git branch -d tempBranch 
72Deleted branch tempBranch (was 8a4439f).
73
74user@HPC.NRW:~$ git branch -a
75  branchingTut
76  creatingAndChangingRepositoriesTut
77* main
78  remotes/origin/branchingTut
79  remotes/origin/creatingAndChangingRepositoriesTut
80  remotes/origin/main

Some remarks to the different lines:

• line 3: When switching to a different branch a message is shown whether the local branch is up to date with the remote one, or if it is ahead of it
• lines 11, 28, 38: Keep in mind that only committed changes can be merged into a branch, as everything that is not committed is not part of the repository and only lies in your working space.
• line 15: Same as line 1, but git checkout is used instead of git switch.
• lines 19 - 23: The option -m is used to directly provide a message to the automatic commit after a merge. This is usually an option to omit a subsequent commit, when a merge conflict will arise and will be (interactively) solved by the user immediately. As can be seen in line 21, the option is ignored here.
• line 24: File "tempFile" is created in the branch "main" in accordance with the merge.
• lines 46 & 47, 54 & 55: Initially, "tempFile" did only contain the first line with "firstLine" on branch "main". After the merge operation, it does also contain the second line with "secondLine" from branch "tempBranch".
• lines 48 - 51: Like in line 19, a commit message is provided to git merge via the option -m. Unlike in line 19, the commit is actually performed, as a file ("tempFile") was modified by the merge.
• lines 57 - 59: The log of branch "main" shows the merge message in line 58 and the last commit from branch "tempBranch" (executed in line 38).
• lines 61 - 65: Here a deletion of the branch is tried while being on branch "branchingTut". This yields an error, because unmerged changes might be lost, as the merge happened on branch "main". Further, line 65 mentions the forced delete using option -D, which was mentioned in the beginning of the branching tutorial.
• lines 67 - 72: Here the deletion of "branchingTut" works without problems, because its changes have been merged into our current branch "main". This shows, that usually Git takes the current branch as a reference for its operations.
• line 69: Please note that the local repository is 15 commits ahead of the remote repository. You should not clutter the remote repository with unnecessary pushes.
• line 72: Information regarding successful deletion of branch and its SHA (8a4439f), which can be used later to retrieve the branch through a checkout.
• lines 74 - 80: Branch "tempBranch" does not appear in our list of branches anymore.

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 branch operations (e.g., creation or deletion).
• switch: Similar to checkout, but reserved for switching branches. New feature, so functionality might change.
• fetch: Used to update information on remote repositories (and branches).
• merge: Used to combine one branch into another.
• stash: Used to temporarily store away uncommitted changes. Can be retrieved with a git stash pop.

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.