CMCC Using Forks - CMCC-Foundation/CMCC-CM GitHub Wiki

Model development work on CMCC-CM takes place in a user's GitHub fork. This page provides an overview of forks and how to use them for efficient model development.

Contents

What is a GitHub Fork?

A fork is a GitHub concept, it is not part of the git language. A GitHub fork is an ordinary git repository stored on GitHub except that GitHub remembers its association with the repository that was used to create the fork. Forks provide two main advantages for model development.

  • A GitHub fork provides you a place to do development that does not interfere with anyone else's work.
  • A branch in a GitHub fork can be presented as a proposed addition or change to a model via a pull request.

Create a GitHub Fork

The instructions here apply to CMCC-Foundation/CMCC-CM or to any of its component models (e.g., CMCC-Foundation/CAM). Just substitute the model repository you are working on for <repo> below.

To create a fork, go to the main website for your model (e.g., https://github.com/CMCC-Foundation/CMCC-CM) and click the fork button in the upper right of the screen:

From the "Owner" dropdown, select your personal GitHub account (usually the first item).

Note: If next to your account is "(fork already exists)", then you already have a fork. Even if this fork was originally created from an organization other than CMCC-Foundation, you can use it for your CMCC development work since you will still be able to open a pull request (PR) back to the CMCC-Foundation GitHub organization.

Clone your GitHub Fork

% git clone https://github.com/<GitHub userid>/CMCC-CM
% cd CMCC-CM
% git remote add CMCC https://github.com/CMCC-Foundation/CMCC-CM
% git fetch --tags CMCC

For help setting up a new clone see Working with clones.

Create a new development branch

Create and checkout a branch for your work. Normally, your branch should start from the CMCC-CM branch:

% git branch <new_branch_name> CMCC/cmcc-cm
% git checkout <new_branch_name>

  1. Make modifications or changes to the branch as you see fit and run some relevant tests.

  2. Commit new changes to local git clone, e.g.:

% git add <new_file(s)>
% git commit -am "<description of changes>"

where <description of changes> should describe all the changes in this commit. To enter a longer commit message, omit the m and the "<description of changes>" and an editor window should open that allows you to enter a detailed message. Note that the first command is only needed if you added new files to your clone (but always take a moment to think about it as forgotten files are a common source of problems that occur during testing). If you aren't sure what files have been added or removed, then type the command:

% git status

which will list all added, removed, and modified files, including files which are in the git repo's directories, but which are not being tracked by git itself.

  1. Push changes back to personal fork:
% git push <origin> <new_branch_name>

where <origin> is the name of the source repository (the default name is 'origin', you might have chosen a different name when you created the clone).

⚠️ **GitHub.com Fallback** ⚠️