Difference between revisions of "Viewing the revision history"

From Geos-chem
Jump to: navigation, search
(Viewing the revision history)
 
(48 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
__FORCETOC__
 
__FORCETOC__
'''''[[Ignoring files|Previous]] | [[Next]] | [[Guide to using Git with GEOS-Chem]] | [[Getting Started with GEOS-Chem]] | [[Main Page|GEOS-Chem Main Page]]'''''
+
'''''[[Ignoring files|Previous]] | [[Using Git GUI|Next]] | [[Guide to using Git with GEOS-Chem]]'''''
  
== Using the Git GUI browser ==
+
#[[Introduction to Git]]
 +
#[[Installing Git]]
 +
#[[First-time Git setup]]
 +
#[[Cloning (i.e. downloading for the first time)]]
 +
#[[Ignoring files]]
 +
#<span style="color:blue">'''Viewing the revision history'''</span>
 +
#[[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]]
  
We recommend using the '''git gui''' for source code management.  Start this in your code directory:
 
  
      git gui &
+
== Examining the Git revision history ==
  
On the left there are 2 windows:
+
You can use the following methods to view the [[#Individual components of the Git revision history|Git revision history]], which represents the evolution of the GEOS-Chem source code with time.
  
#'''Unstaged Changes:''' An unstaged change is a modification that Git does not know about yet.  If you modified any files since the last commit, then they should be displayed in this window.  Also, right above this window you will find the name of the current checked-out branch.
+
=== Use Gitk to see a graphical display ===
#'''Staged Changes:''' These are changes that Git will add to the repository the very next time you make a commit.
+
  
In general, anytime you need to modify the source code, you should NOT do it on the '''master''' branchYou should [[#Creating branches|create a new branch]] for your modifications.  Then you can test your modifications ad nauseum until you are sure that everything is functioning as it should.  When your modifications are complete, you can [[#merging|merge your branch]] into the '''master''' branch. You can then [[#Deleting branches|delete the branch]] you created. 
+
The best way to examine the contents of your Git-backed GEOS-Chem source code is to use the '''gitk''' viewerThere are two ways to do this:
  
The advantage of this approach is that if you ever need to start over from scratch, you can just go back to the '''master''' branch and you will get back the state of the code before your modifications were added.
+
(1) Change into your code directory and start '''gitk''' as follows:
  
== Using the Gitk browser ==
+
gitk --all &      # This will show ALL open branches
  
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:
+
(2) Or if you are using the '''git gui''' GUI browser ([[#Using the Git GUI|more on Git GUI HERE]]), you can invoke '''gitk''' from the '''Repository/Visualize master's History''' menu item.
  
:(1) Change into your code directory and start '''gitk''' as follows:
+
(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, [[#Individual components of the Git revision history|please see this section below]].
  
        gitk --all &      # This will show ALL open branches
+
[[Image:Gitk.png]]
  
:(2) Or if you are using the '''git gui''' GUI browser ([[#Making revisions|more on that below]]), you can invoke '''gitk''' from the '''Repository/Visualize master's History''' menu item.
+
=== Use git log to see a text-only display ===
  
At the top left of the '''gitk''' screen, you will see the graph of revisions. Each dot represents a commit, along with the log message that accompanied each commit. 
+
If you wish to obtain a text representation of the revision history, you can use the <tt>git log</tt> command.   For example, typing:
  
Note that at the most recent commit (i.e. the line at the very top) there are 2 green boxes, one labeled '''master''' and one labeled '''remotes/origin/master''':
+
git log -b master
  
#'''remotes/origin/master:''' This was the state of the repository on the remote server when you checked it out for the first timeTherefore, this is the "pristine", unchanged code that you got from the download.
+
will print these commit messages of the master branch(If you omit the <tt>-b</tt>, it will print the revision history on the current branch.)
#'''master:''' This is the current state of the local repository now.  Since we haven't done anything to the code yet, '''master''' and '''remotes/origin/master''' point to the same commit.
+
  
If you click on any of the commits in the top left window, in the window below, you will see the log message and a list of changes to the source code. The old code is marked in <span style="color:#FF0000">'''RED'''</span> and the new code is marked in <span style="color:#008000">'''GREEN'''</span>At right you will also see a list of files that were changed during the commit.
+
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 ...  
  
With '''gitk''', it's really easy to see how the code has evolved over time.
+
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 [[#Use Gitk to see a graphical display|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 <span style="color:#FF0000">'''RED'''</span> and the new code is marked in <span style="color:#008000">'''GREEN'''</span>.  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 [[#Use Gitk to see a graphical display|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 [https://datasift.github.io/gitflow/IntroducingGitFlow.html GitFlow] method of naming branches:
 +
 
 +
'''Local branches:''' these represent the states of the code in your local clone of GEOS-Chem:
 +
 
 +
{| border=1 cellspacing=0 cellpadding=5
 +
|-valign="top" bgcolor="#CCCCCC"
 +
!width="250px"|Local Branch
 +
!width="750px"|Description
 +
 
 +
|-valign="top"
 +
|<tt>master</tt>
 +
|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.
 +
 
 +
|-valign="top"
 +
|<tt>bugfix/NAME</tt>
 +
|These branches contain bug fixes that will be quickly merged back into the master branch (thus neccessitating a bugfix version release).
 +
 
 +
|-valign="top"
 +
|<tt>feature/NAME</tt>
 +
|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.
 +
 
 +
|-valign="top"
 +
|<tt>dev/NAME</tt>
 +
|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):
 +
 
 +
{| border=1 cellspacing=0 cellpadding=5
 +
|-valign="top" bgcolor="#CCCCCC"
 +
!width="250px"|Remote Branch
 +
!width="750px"|Description
 +
 
 +
|-valign="top"
 +
|<tt>remotes/origin/master</tt>
 +
|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.
 +
 
 +
|-valign="top"
 +
|<tt>remotes/origin/bugfix/NAME</tt>
 +
|Bug fix branches that have been pushed to the remote repository.
 +
 
 +
|-valign="top"
 +
|<tt>remotes/origin/feature/NAME</tt>
 +
|Feature branches that have been pushed to the remote repository.
 +
 
 +
|-valign="top"
 +
|<tt>remotes/origin/dev/NAME</tt>
 +
|Development (Dev) branches that have been pushed to the remote repository.
 +
|}
 +
 
 +
 
 +
In the [[#Use Gitk to see a graphical display|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 ==
 
== Further reading ==
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:40, 19 June 2019 (UTC)
+
#[https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History ''Viewing the commit history'' (Pro Git book)]
 +
#[https://git-scm.com/docs/git-log ''Git log (Official Git documentation)]
 +
#[https://datasift.github.io/gitflow/IntroducingGitFlow.html ''GitFlow'' (DataSift)]
 +
 
  
 
----
 
----
'''''[[Ignoring files|Previous]] | [[Next]] | [[Guide to using Git with GEOS-Chem]] | [[Getting Started with GEOS-Chem]] | [[Main Page|GEOS-Chem Main Page]]'''''
+
'''''[[Ignoring files|Previous]] | [[Using Git GUI|Next]] | [[Guide to using Git with GEOS-Chem]]'''''

Latest revision as of 20:27, 5 August 2019

Previous | Next | Guide to using Git with GEOS-Chem

  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


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 (DataSift)



Previous | Next | Guide to using Git with GEOS-Chem