1 of 33

Peeking Inside a Software Engineer's Git Toolbox

March 28, 2024

Cheryl Craig

CGD AMP and CSEG Software Engineer

This material is based upon work supported by the National Center for Atmospheric Research, which is a major facility sponsored by the National Science Foundation under Cooperative Agreement No. 1852977.

2 of 33

What is Git?

According to CoPilot:

Git is like a magical time-traveling notebook for your code. Imagine you’re writing a story, and every time you make a change, you jot it down in this notebook.
Each change you make (like fixing a typo or adding a new chapter) gets recorded in the notebook. But here’s the cool part: you can flip back and forth between different versions of your story!
So, Git is a tool that helps developers manage their code history. It keeps track of every change made to a project, allowing collaboration, experimentation, and safekeeping.

Git is the tool that scientists and software engineers use to keep track of CESM

3 of 33

What is my favorite tool for git?

diffmerge

This tool is useful for :

Viewing changes you've made before you push them back to your github repository

Viewing and editing merge conflicts

Ties into the git difftool and git mergetool commands that git has by providing a user friendly interface

Disclaimer: There are many ways to interact with git and achieve the same effect, this is just the way that I find works best for me

4 of 33

Why do I need a tool?

How many times has this happened to you?

You are actively working on some new development in your git clone
You get pulled aside to do something else "quick", but don't push your work back to the git repository since you were in the middle of things
The other work takes much longer than you expected
When you return, you can't remember what edits you had made

So what do you do?

git status

5 of 33

What do you see?

Depending on how prolific you were you may see something like this:

Changes to be committed:

modified: Externals_CAM.cfg

modified: bld/build-namelist

modified: bld/configure

modified: bld/namelist_files/namelist_defaults_cam.xml

modified: bld/namelist_files/namelist_definition.xml

modified: cime_config/testdefs/testlist_cam.xml

modified: doc/ChangeLog

modified: src/chemistry/modal_aero/modal_aero_convproc.F90

modified: src/physics/cam/cloud_fraction.F90

modified: src/physics/cam/clubb_intr.F90

modified: src/physics/cam/convect_shallow.F90

modified: src/physics/cam/macrop_driver.F90

modified: src/physics/cam/rk_stratiform.F90

6 of 33

Wow - I made more changes than I remember - what are they?

Now you need to see what you changed. So you type:

git diff

7 of 33

That is painful as you have pages of output like:

diff --cc src/physics/cam/zm_conv_intr.F90

index d5da099b,d559ce4b..00000000

--- a/src/physics/cam/zm_conv_intr.F90

+++ b/src/physics/cam/zm_conv_intr.F90

@@@ -8,11 -8,13 +8,19 @@@ module zm_conv_int

! January 2010 modified by J. Kay to add COSP simulator fields to physics buffer

!---------------------------------------------------------------------------------

use shr_kind_mod, only: r8=>shr_kind_r8

- use physconst, only: cpair

+ use physconst, only: cpair, epsilo, gravit, latvap, tmelt, rair

use ppgrid, only: pver, pcols, pverp, begchunk, endchunk

++<<<<<<< HEAD

+ use zm_conv, only: zm_conv_evap, zm_convr, convtran, momtran

+ use zm_microphysics, only: zm_aero_t, zm_conv_t

8 of 33

A much better way to view

Instead type:

git difftool

Important note (this requires diffmerge being set in your .gitconfig file)

These details will be on the last slide

10 of 33

Actual changes

(old on left, new on right)

11 of 33

Visualization of changes within entire file

12 of 33

Step to next changed set of lines

13 of 33

git difftool

Will step through all files changed one-at-a-time

git difftool <filename>

Will look at diffs just in that file

14 of 33

You have completed your project, but the head of the main development repo has made progress as well.

Time to merge:

git merge …

�You see:

izumi$ git merge origin/atmos_select_zm_support

Auto-merging zm/zm_conv_convtran.F90

CONFLICT (add/add): Merge conflict in zm/zm_conv_convtran.F90

Auto-merging zm/zm_conv_evap.F90

CONFLICT (add/add): Merge conflict in zm/zm_conv_evap.F90

Auto-merging zm/zm_conv_momtran.F90

CONFLICT (add/add): Merge conflict in zm/zm_conv_momtran.F90

Auto-merging zm/zm_convr.F90

CONFLICT (add/add): Merge conflict in zm/zm_convr.F90

Automatic merge failed; fix conflicts and then commit the result.

15 of 33

Now what?

If you examine your file, you'll see something like this:

<<<<<<< HEAD

logical, intent(in) :: new_logical

integer, intent(in) :: pcols, pver, pverp

! Original had a tipo

logical, intent(in) :: domomtran(:) ! revise comment

=======

integer, intent(in) :: my_new var

integer, intent(in) :: pcols, pver, pverp

! Original had a typo, but added more info

logical, intent(in) :: domomtran(:) ! final comment

>>>>>>> atmos_phys_main_for_talk

16 of 33

You can avoid that mind numbing process if

you have diffmerge and it's 3-way diff installed

After your git merge has done what it can automatically merge and has told you that there are conflicts, you can say:

git mergetool

Will step through all files which have conflicts one-at-a-time and allow you to resolve the conflicts

git mergetool <filename>

Will bring up that one file with conflicts and allow you to edit it

Reminder again (this requires diffmerge being set in your .gitconfig file)

These details will be on the last slide

17 of 33

What you see when you say "git mergetool"

18 of 33

Pop up window indicates 2 conflicts

All of the other changes have been automatically merged, so you only need to deal with the conflicts
Note – sometimes this window is hidden behind a DiffMerge popup - you need uncover this window to hit the OK button before you can proceed

19 of 33

Final Merged code

Code merging in

"Your" code

20 of 33

Step to next conflict

First conflict already highlighted

21 of 33

Right mouse click on first conflict

First conflict: two new lines which were added in same location - want to keep both

22 of 33

Right mouse click gives you a choice of options, including "Insert This"

23 of 33

Line is inserted in merged "final" code

24 of 33

Right mouse click on my code's line

25 of 33

Right mouse click gives you slightly different options, including "Append This"

26 of 33

Both lines are inserted in merged "final" code

27 of 33

Step to next conflict (no longer highlighted as I hit it and it is the last one)

Notice highlighting moved down to next conflict

28 of 33

Second conflict has modifications want from both files

Want first line from this file

Want second line from this file

The middle pane is a visual editor, so there are numerous ways to proceed

You can put both modifications in as in previous example and delete lines you don't want

You can copy/paste the lines you want from each section into the middle section

You could type by hand in the middle section what you want

29 of 33

Save your changes and then close the window

30 of 33

If you said: git mergetool

The mergetool will now advance to the next file with conflicts. It will repeat until all conflicts are resolved

When you have resolved all your conflicts, if you say: git status

You will see:

All conflicts fixed but you are still merging.

(use "git commit" to conclude merge)

Changes to be committed:

modified: zm/zm_conv_momtran.F90

Follow the directions and say: git commit

Will finish the merge process (no comment needed as the merge is supplying it)

�MERGE IS DONE!

31 of 33

What do I need to do to get this tool?

It is a one-time change

Edit your .gitconfig file (which resides in your home directory) to contain the following:

[diff]

tool = diffmerge

algorithm = histogram

[difftooldiffmerge]

cmd = diffmerge \"$LOCAL\" \"$REMOTE\"

[difftool "diffmerge"]

cmd = diffmerge $LOCAL $REMOTE

[difftool]

prompt = false

[merge]

tool = diffmerge

ff = false

[mergetool "diffmerge"]

cmd = diffmerge --merge --result=$MERGED $REMOTE $BASE $LOCAL

[mergetool]

keepBackup = false

32 of 33

Where do I find this information?

It resides on the ESCOMP/CAM github wiki page:

https://github.com/ESCOMP/CAM/wiki/git-and-GitHub#complete-modifications-needed-for-using-the-graphical-tool-diffmerge-for-git-difftool--and-git-mergetool

— OR—

Bonnie will have this link in this week's CGD Weekly Update

Important Note: While diffmerge exists in a public area on izumi and derecho, it is a tool that I have needed to ask system administrators to put onto the machines (it is free). On derecho, they needed to put it in a container.