Merging

Previous | Next | Guide to using Git with GEOS-Chem | Getting Started with GEOS-Chem | GEOS-Chem Main Page

1. Introduction to Git
2. Installing Git
3. First-time Git setup
4. Cloning (i.e. downloading for the first time)
5. Ignoring files
6. Viewing the revision history
7. Using Git GUI
8. Branching
9. Committing
10. Tagging
11. Merging
12. Receiving updates (aka pulling)
13. Using patches to share your updates with others
14. Advanced Git usage
15. Git and Github tutorials

Overview

On this page, we provide information about merging branches together, as well as rebasing branches (i.e. putting all the commits in a branch on top of another branch).

Merging

Merging is the process of combining two Git branches together. It can be done either from the Git GUI (our recommended method), or from the command line.

Merging with the Git GUI

The easiest way to merge branches is by using the Git GUI. Follow these steps:

(1) Start Git GUI

git gui &

(2) Checkout the target branch—the branch into which you will merge another branch. In this example, let's assume that we will be merging into the master branch, so we would check out master.

(3) Select the Merge/Local merge menu item (or type CTRL-M).

(4) A dialog box will appear. Select the branch that you would like to merge into the target branch—which in this example is master.

(5) Click on Merge.

(6) View the revision history. You should see the two branches merged together.

Resolving conflicts caused by a merge

Sometimes you may encounter conflicts when merging one branch into another branch. This can happen when you are merging code from an older GEOS-Chem version into the latest version. A conflict is just Git saying, "I found some code in a place where I didn't expect to find it. Can you help me figure out which lines of code to keep and which to throw away?"

When you encounter a conflict, open the git gui window. You will see each file containing a conflict listed in the Unstaged Changes window. Clicking on each file will display the lines of code where the conflicts are located. You will see one or more slugs in the file. A slug is a block of text that displays the source code from the old branch and the new branch.

<<<<<<< HEAD
! This is old source code that already exists in the branch
...
=======
! This is new source code that is being merged into the branch
...
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086

At the top of the slug you see the string <<<<<<< HEAD followed by some source code. This is the "old" code, i.e. the code that existed as of the last commit. A separator line ======= then follows the source code.

Underneath the separator line, you will see the "new" source code, i.e. the code that we are merging into the branch. This source code is followed by the text >>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086. The long numeric string is the SHA1 ID (the internal ID # used by Git) corresponding to the commit that we are merging into the branch. Each commit has a unique SHA1 ID.

To resolve a file containing conflicts, do the following:

1. Open the file in your favorite text editor (vi, emacs, etc.)
2. Search for the word HEAD. This will take you to the location of each slug (where conflicts exist).
3. Decide which code that you want to keep.
4. Delete the code that you do not want to keep.
5. Delete the lines <<<<<<< HEAD, =======, and >>>>>>> 7797... If you keep these in the source code you will get compilation errors.
6. Repeat this process for each conflict that you find.

Once you have resolved the conflicts in each file, you can commit them back into the repository.

Rebasing

Rebasing is a special type of merging, where your commits are placed at the head of another branch. For more information on rebasing, please see these resources:

1. https://git-scm.com/book/en/v2/Git-Branching-Rebasing Rebasing (Pro Git book)]
2. An Introduction to Git merge and rebase (freeCodeCamp)
3. Git rebase (Atlassian Git tutorial)

Further reading

1. Git merge (Git documentation)
2. Basic branching and merging (Pro Git book)
3. Git merge (Atlassian Git tutorial)

---

Previous | Next | Guide to using Git with GEOS-Chem | Getting Started with GEOS-Chem | GEOS-Chem Main Page