This page describes how to download the example code from the CAM-chem GitHub repository. It also gives guidance if you want to contribute to the repository. A nice overview of common commands is available on the Git cheat sheet from GitHub. Git is available for Linux (https://git-scm.com/download/linux), Mac (https://git-scm.com/download/mac) and PC (https://git-scm.com/download/win).
     

1. Downloading code

1.1 Easy: Download directly from GitHub

Go here: https://github.com/NCAR/CAM-chem to navigate to the code you require, then right click on the "Raw" button and choose "Save Link as" to save the code file.

Note: Doing this won't get any of the nice version control features used by Git.

1.2. Less Easy: Set up your own copy of the the CAM-chem repository.

This is best if you want all the code examples and to keep up to date with changes, or alternatively if you think you want to improve some code or even add to the repository.

First time use of Git, tell it who you are.

>git config --global user.email [you@example.com]
>git config --global user.name [Your Name]

Once that is done, clone the CAM-chem repository to a local location.

>git clone https://github.com/NCAR/CAM-chem [local-name]

Regularly keep the master branch up to date with the online master copy. (This won't change anything on your personal working branch - see below.)

>git checkout master         <--------- optional depending on if you are in another branch
>git fetch origin
>git merge origin/master

2. Contributing code

2.1 Working on your own code.

Make your own personal working branch, which will be a duplicate of the master branch. You can then work on code within your own branch of the code, and upload to GitHub under your branch name. 

>git branch [branch-name]

Move over to working in your branch and check you are working in your branch.

>git checkout [branch-name]
>git branch                  <--------- will show a * next to the current branch
or
>git status

Once you have some code you would like to store on GitHub, complete the following.

>git add [new-file]
>git commit -m "A message about the new file or updates"
>git push origin [branch-name]

You will be asked for your GitHub username and password. Your branch will be added to GitHub at https://github.com/NCAR/CAM-chem/tree/[branch-name]. Tip: Invoke >git status after each step to see what has been done.


Troubleshooting:

A. Updating the master branch in Step 1.2 will not update in your working branch. If you want to merge master branch updates into your working branch you will need to state that explicitly.

>git checkout [branch-name]
>git fetch origin
>git merge origin/master
>git push

2.3 Contributing to the CAM-chem master branch

If you have been working on your own code in your own branch and would like to merge with the master CAM-chem repository, you need to submit a pull request. First create code headers for any files you will submit, that includes at a minimum the following information.

Name of program
------------------------------------------------
Purpose of program/code
Required files
Example call to program/code
Code creator, date created
-----------------------------------------------

For example:

; lagged_corr_co_climate.ncl
;=======================================================;
; Concepts illustrated:
; - For use with MOPITT CO version 7, month anomalies
; - load CO data
; - load climate indices
; - calculate lagged correlations
;
; Files needed:
; - MOPITT anomalies
; - Climate Mode Index values
;
; To run type:
; ncl lagged_corr_co_climate.ncl
; RRB August 8, 2017
;=======================================================

Then create a GitHub pull request by navigating into your branch on GitHub and clicking the pull request in the top right.

Tip: If you have been working on a lot of code, create a new branch with just the things you wish to submit to the master branch.


  • No labels