Viewing the revision history
Previous | Next | Guide to using Git with GEOS-Chem
- Introduction to Git
- Installing Git
- First-time Git setup
- Cloning (i.e. downloading for the first time)
- Ignoring files
- Viewing the revision history
- Using Git GUI
- Branching
- Committing
- Tagging
- Merging
- Receiving updates (aka pulling)
- Using patches to share your updates with others
- Advanced Git usage
- 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.
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