Viewing the revision history

From Geos-chem
Revision as of 16:53, 19 June 2019 by Bmy (Talk | contribs) (Further reading)

Jump to: navigation, search

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

Using Gitk to examine the revision 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 Git revision history.

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.

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:

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)



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