Git Tutorial: 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)

It is possible to have multiple stashes at once and even to apply them to other branches and much more. If you are interested we suggest Git's easy to understand section on working with stashes.

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:

otherUser@HPC.NRW:~$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  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 not arise. However, here it is unnecessary, because no file has been changed (only added for tracking). As can be seen in line 21, the option is ignored.
• 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.

Next, we will create a merge with a conflict. As mentioned before, a conflict can occur when two users try to modify the same parts of a code, because it becomes unclear which changes have to be incorporated into the merge and which not. To reproduce such a situation, we can mostly repeat the steps from the previous merge without conflicts. Here are some instructions with a solution and remarks below:

1. Create two branches "tempBranch" and "toMergeBranch" (does not matter of which branch)
2. Create a file "tempFile" on both branches
3. Write something in the first line of "tempFile" on "tempBranch"
4. Write something in the second line of "tempFile" on "toMergeBranch"
5. Merge "toMergeBranch" into "tempBranch" providing a merge message
6. Resolve the conflict (see conflict solving basics below)
7. Delete branches "tempBranch" and "toMergeBranch"

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 branch -a
 2* branchingTut
 3  creatingAndChangingRepositoriesTut
 4  main
 5  remotes/origin/branchingTut
 6  remotes/origin/creatingAndChangingRepositoriesTut
 7  remotes/origin/main
 8
 9user@HPC.NRW:~$ git branch tempBranch
10user@HPC.NRW:~$ git branch toMergeBranch
11
12user@HPC.NRW:~$ git switch tempBranch 
13M	Branching
14Switched to branch 'tempBranch'
15
16user@HPC.NRW:~$ rm -r *
17
18user@HPC.NRW:~$ touch tempFile; echo "write in first line" >> tempFile
19user@HPC.NRW:~$ git add .
20user@HPC.NRW:~$ git commit -m "Delete some files in branch and write tempFile"
21[tempBranch 8385a37] Delete some files in branch and write tempFile
22 5 files changed, 1 insertion(+), 620 deletions(-)
23 delete mode 100644 Branching
24 delete mode 100644 Creating_and_Changing_Repositories
25 delete mode 100644 Git_Tutorials
26 delete mode 100644 clonedRepoFile
27 create mode 100644 tempFile
28
29user@HPC.NRW:~$ git switch toMergeBranch 
30Switched to branch 'toMergeBranch'
31user@HPC.NRW:~$ rm -r * 
32user@HPC.NRW:~$ touch tempFile; echo "" >> tempFile; echo "something in second line" >> tempFile
33user@HPC.NRW:~$ cat tempFile 
34
35something in second line
36user@HPC.NRW:~$ git add .
37user@HPC.NRW:~$ git commit -m "Delete some files on branch and write tempFile second line"
38[toMergeBranch 529b936] Delete some files on branch and write tempFile second line
39 5 files changed, 2 insertions(+), 620 deletions(-)
40 delete mode 100644 Branching
41 delete mode 100644 Creating_and_Changing_Repositories
42 delete mode 100644 Git_Tutorials
43 delete mode 100644 clonedRepoFile
44 create mode 100644 tempFile
45
46user@HPC.NRW:~$ git switch tempBranch 
47Switched to branch 'tempBranch'
48user@HPC.NRW:~$ git merge -m "merge toMergeBranch into tempBranch" toMergeBranch
49CONFLICT (add/add): Merge conflict in tempFile
50Auto-merging tempFile
51Automatic merge failed; fix conflicts and then commit the result.
52
53user@HPC.NRW:~$ ls .git/
54branches/       config          FETCH_HEAD      hooks/          info/           MERGE_HEAD      MERGE_MSG       ORIG_HEAD       refs/           
55COMMIT_EDITMSG  description     HEAD            index           logs/           MERGE_MODE      objects/        packed-refs 
56
57user@HPC.NRW:~$ vi tempFile
58user@HPC.NRW:~$ git add tempFile 
59user@HPC.NRW:~$ git commit -m "Merge with toMergeBranch"
60[tempBranch 5e72b28] Merge with toMergeBranch
61
62user@HPC.NRW:~$ ls .git/
63branches/       config          FETCH_HEAD      hooks/          info/           objects/        packed-refs     
64COMMIT_EDITMSG  description     HEAD            index           logs/           ORIG_HEAD       refs/        
65
66user@HPC.NRW:~$ cat tempFile 
67write in first line
68something in second line
69
70user@HPC.NRW:~$ git switch branchingTut 
71Switched to branch 'branchingTut'
72
73user@HPC.NRW:~$ git branch -d tempBranch 
74error: The branch 'tempBranch' is not fully merged.
75If you are sure you want to delete it, run 'git branch -D tempBranch'.
76
77user@HPC.NRW:~$ git branch -D tempBranch 
78Deleted branch tempBranch (was 5e72b28).
79user@HPC.NRW:~$ git branch -D toMergeBranch 
80Deleted branch toMergeBranch (was 529b936).

• line 1: We create the branches while on branch "branchingTut", i.e. the new branches will have the corresponding files and we might want to delete them for this tutorial.
• line 16: Here we delete those unnecessary files. Do not worry, files and directories beginning with a dot (like .gitignore) are not affected by this.
• lines 33 - 35: File "tempFile" on branch "toMergeBranch" contains one empty line and some text in the second line.
• lines 48 -51: We get a merge conflict that cannot be automatically resolved (line 51) and therefore the merge message gets ignored. The conflict arises from branch "tempBranch" having text in the first line of "tempFile" while branch "toMergeBranch" has nothing in the first line. Having text in the second line of "tempFile" on branch "toMergeBranch" causes no conflict, as this does not directly contradict "tempBranch", which has no information about contents of the second line of "tempFile" (it does not exist there).
• lines 53 - 55: Here we show the merge related files MERGE_HEAD, MERGE_MODE and MERGE_MSG existing due to a conflict. MERGE_MSG contains information on the conflict causing files.
• line 57: Here we edit the conflicting file. More information on the that are provided further below.
• lines 57 - 60: These are the actual lines solving the merge conflict.
• lines 62 - 64: The conflict related files have disappeared now (compare with comment on lines 53 - 55).
• lines 73 - 75: "tempBranch" and "toMergeBranch" have been created from "brachingTut", but have not been merged into it. Therefore, we get an error when trying to delete them with option -d.
• lines 77 - 80: Option -D is the solution here. SHA values of deleted branches are shown.

Below we provide an example for a file containing a merge conflict. In this case, it is the file "tempFile" from the exercise above.

<<<<<<< HEAD
write in first line
=======

something in second line
>>>>>>> toMergeBranch

The <<<<<<< HEAD marks the beginning of a difference or conflict in the file on our current branch (the branch we wanted to merge into), ======= separates this content from the content in the branch we wanted to merge. Therefore, everything between ======= and >>>>>>> toMergeBranch is the corresponding content on branch "toMergeBranch". Anything outside of those markers is identical on both branches. Further, those markers can appear multiple times in one file, should several conflicts exist. An easy way to check which files contain conflicts is to look into ./.git/MERGE_MSG. This file is only present while a merge conflict persists.

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.
• Git documentary: Further information on the possibilities of stashes.