Viewing the revision history

From Geos-chem
Revision as of 17:12, 21 June 2019 by Bmy (Talk | contribs)

Jump to: navigation, search

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. Git and Github tutorials


Examining the Git revision history

You can use the following methods to view the Git revision history, which represents the evolution of the GEOS-Chem source code with time.

Use Gitk to see a graphical display

The best way to examine the contents of your Git-backed GEOS-Chem source code is to use the gitk viewer. There are two ways to do this:

(1) Change into your code directory and start gitk as follows: 

gitk --all &       # This will show ALL open branches

(2) Or if you are using the git gui GUI browser (more on Git GUI HERE), you can invoke gitk from the Repository/Visualize master's History menu item.

(3) You will see the graph of revisions in the top-left window of the gitk screen. For more information on how to read the revision history, please see this section below.

Gitk.png

Use git log to see a text-only display

If you wish to obtain a text representation of the revision history, you can use the git log command. For example, typing: 

git log -b master

will print these commit messages of the master branch. (If you omit the -b, it will print the revision history on the current branch.) 

commit 8577e97061414ea84de7717aac8803ef23b869ad (HEAD -> master, tag: 12.3.2, origin/master, origin/HEAD)
Author: Bob Yantosca <yantosca@seas.harvard.edu>
Date:   Thu Apr 18 15:35:56 2019 -0400

    Now pick box closest to local noon, using local time in seconds
    
    In time_mod.F, we have added a function GET_LOCALTIME_IN_SEC, which
    returns the local time in seconds in the range 0-86400.
    
    The local time in seconds is then used to compute the field
    State_Met%IsLocalNoon.  This will be used for local noon
    J-value diagnostics
    
    Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

commit f083b7a6d3f9a0bf988d9a00d57a03bbe763a247
Author: Melissa Sulprizio <mpayer@seas.harvard.edu>
Date:   Thu Apr 18 10:12:56 2019 -0400

    Rename manual fertilizer NOx diagnostic
    
    The diagnostic 'FERTILIZER_NO' has been renamed to 'EmisNO_Fert' for
    consistency with the naming convention used in HEMCO_Diagn.rc. To
    enable saving out the fertilizer NOx emissions via HEMCO, simply add
    the following line to HEMCO_Diagn.rc:
    
       EmisNO_Fert        NO     104    -1  -1   2   kg/m2/s  NO_emission_flux_from_fertilizer
    
    Signed-off-by: Melissa Sulprizio <mpayer@seas.harvard.edu> 

... etc ...

If you only wanted to see the first 5 commits on the master branch, type: 

git log -b master -5

If you wanted to see the first line of each commit message on the master branch, type: 

git log -b master --oneline

which will display the following output: 

8577e970 (HEAD -> master, tag: 12.3.2, origin/master, origin/HEAD) Now pick box closest to local noon, using local time in seconds
f083b7a6 Rename manual fertilizer NOx diagnostic
00e7349c Update diaglist_mod.F to classify diagnostics beginning in "Inv" as emissions
dc79aca5 Now loop over (I,J) when computing State_Met%IsLocalNoon
510622fe Remove #ifdef MODEL_GEOS blocks where we read UCX inputs  from netCDF
b9beda0a Comment out calls to debug routine Print_Global_Species_Kg
3ab8d7a9 Cosmetic fix: Change "senescing plants" to "decaying plants" for consistency with HEMCO files
e00b37ac UCX now reads updated surface volumne mixing ratio file
... etc ...

Individual components of the Git revision history

With the Gitk window or git log, you can easily see the Git revision history. The Git version history is composed of the following components:

Commits

A commit denotes source code that has been added to the Git repository. In the Gitk browser revision history window, each commit is represented with a blue dot. Each commit will also have a descriptive messsage, whose first line you can see in either the Gitk or git log output.

If you click on any of the commits in the top left Gitk window, then you will see the commit log and a list of changes the source code displayed. The old code is marked in RED and the new code is marked in GREEN. At right you will also see a list of files that were changed during the commit.

For instructions on how to make commits with Git, please see this section.

Tags

A tag just a descriptive marker to highlight important commits. These show up as the yellow flags in the Gitk revision history window shown above. For example, commits that correspond to GEOS-Chem version releases are tagged with the GEOS-Chem version number (e.g. 12.3.2).

For information on how to tag commits, please see this section.

Branches

A branch represents a certain line of development. Git branches are "lightweight", that is, they can be created, merged, and deleted easily.

GEOS-Chem uses the GitFlow method of naming branches:

Local branches: these represent the states of the code in your local clone of GEOS-Chem:

Local Branch Description
master This branch contains the current stable GEOS-Chem version. This is the only branch you should clone when downloading the GEOS-Chem source code to your system. Code in the master branch has been benchmarked and validated.
bugfix/NAME These branches contain bug fixes that will be quickly merged back into the master branch (thus neccessitating a bugfix version release).
feature/NAME These branches contain new features that will be merged into GEOS-Chem. Code in these branches may be undergoing testing or changes, and are not considered stable.
dev/NAME These branches are new GEOS-Chem versions in development. They contain one or more bug fixes or features. Code in these branches may be undergoing testing or changes, and are not considered stable.


Remote branches: These represent states of the code at the remote GEOS-Chem repository (such as at Github):

Remote Branch Description
remotes/origin/master This was the state of the repository on the remote server when you checked it out for the first time. Therefore, this is the "pristine", unchanged code that you got from the download.
remotes/origin/bugfix/NAME Bug fix branches that have been pushed to the remote repository.
remotes/origin/feature/NAME Feature branches that have been pushed to the remote repository.
remotes/origin/dev/NAME Development (Dev) branches that have been pushed to the remote repository.


In the Git revision history shown above, note the green boxes labeled master and labeled remotes/origin/master. The green box labeled master is boldfaced, which means that it is the currently checked-out branch. Also note that both master and remotes/origin/master point to the same commit. This means that the code in your local clone is at the same state as that in remote repository.

For more information about branching with Git, please see this section.

Merges

A merge is when two branches are combined together into a single commit. In GEOS-Chem, the bugfix and feature branches are merged into dev branches, which are then benchmarked and validated. After validation, a dev branch will be merged into master, which results in a new model version.

For more information about merging with Git, please see this section.

Further reading

  1. Viewing the commit history (Pro Git book)
  2. Git log (Official Git documentation)
  3. GitFlow

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

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=Viewing_the_revision_history&oldid=43210"