Difference between revisions of "Viewing the revision history"

From Geos-chem
Jump to: navigation, search
(Branches)
(Using the Git GUI browser for source code management)
Line 67: Line 67:
  
 
For more information about merging with Git, please see this section.
 
For more information about merging with Git, please see this section.
 
== Using the Git GUI browser for source code management ==
 
 
We recommend using the '''git gui''' for source code management.  Start this in your code directory:
 
 
      git gui &
 
 
which will bring up this window:
 
 
[[Image:GitGui.png]]
 
 
On the left there are 2 windows:
 
 
#'''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.
 
#'''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''' branch.  You 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 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.
 
  
 
== Further reading ==
 
== Further reading ==

Revision as of 16:42, 19 June 2019

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

Using Gitk to examine the version history

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.

At the top left of the gitk screen, you will see the graph of revisions. This is explained in more detail in the next section.

Gitk.png

Items visible in the graphical display of the version control history

With the Gitk window, you can easily see the version history.

Commits

A commit denotes source code that has been added to the Git repository. In the Gitk browser version history window, each commit is represented with a blue dot.

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 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: thess represent the states of the code in your local clone of GEOS-Chem:

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):

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 version 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

--Bob Yantosca (talk) 15:40, 19 June 2019 (UTC)


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