How to push your configuration to GitHub

Technical
,
1

Purpose

These instructions describe how to upload your own modifications to an ACCESS-NRI model configuration to GitHub. It can be useful to do this to share your files with a collaborator, or to get help with debugging. These instructions push a single folder to a single remote repository so are best used when wanting to push a single experiment to GitHub.

Prerequisites

  1. You need to have an NCI account and to join project vk83.
  2. You need to have your own GitHub account
  3. You need to have authorised with GitHub
  4. You need to have an experiment ready to upload (see here for instructions on setting up an experiment)

gh commands

gh is included in payu modules supported by ACCESS-NRI. As long as the payucommand is available gh should be also.

This is how you make the payu command available:

module use /g/data/vk83/modules
module load payu

Push to remote repository

Change into your experiment directory.
Configurations developed via payu already come with a git history (which will be uploaded to the repository created here) but it is a good idea to check if there are any changes that need committing before pushing:

git status

You will get a list of files and changes that won’t be pushed to the remote repository. If you want these to be added then do git add file (where file is the relative path to the files you want added). The command:

git commit -m "description of these files"

will then add the files to the list to be uploaded.

Now you can create a repository from your experiment directory using

gh repo create

Follow the prompts and enter the information requested. Repository name will default to the directory name of your control directory. The repository owner should be your GitHub username used to authenticate. Choose public visibility. The remote name is just an alias to your repository that git uses when doing a push or pull.

? What would you like to do? Push an existing local repository to GitHub
? Path to local repository .
? Repository name XXXXX
? Repository owner xxxxxxxxx
? Description A nice description of the purpose of the repository
? Visibility Public
âś“ Created repository xxxxxxxxx/XXXXX on GitHub
  https://github.com/xxxxxxxxx/XXXXX
? Add a remote? Yes
? What should the new remote be called? myrepo
âś“ Added remote git@github.com:xxxxxxxxx/XXXXX.git
? Would you like to push commits from the current branch to "myrepo"? Yes

Push subsequent changes to remote repository

Before you can push changes to your remote Githib repository you need to commit your changes locally:

git add path_to_file/file_that_has_changed
git commit -m “text that describe the changes you made”

Note that you can turn runlog on in config.yaml and your changes will automatically be committed when you run your experiments:

runlog: true

To push your changes to your remote repository, you need to know the name of your remote repository and the branch.

To get the name of your repository you can check your remote repositories

git remote -v

You should get an output like this:

myrepo	https://github.com/*******/**********.git (fetch)
myrepo	https://github.com/*******/**********.git (push)
origin	https://github.com/ACCESS-NRI/access-om3-configs/ (fetch)
origin	https://github.com/ACCESS-NRI/access-om3-configs/ (push)

Where **** indicate paths to your personal remote repository.
Which shows that your local repository on Gadi is connected to the original configuration repository (origin) and your new repository on your personal github page. The first word on each line is the repository name. We want the one connected to your personal account (in this case this is “myrepo”, it is not “origin”).

To get the branch name you can run

git branch -v

You should get 2 lines of output that are similar to this:

  dev-1deg_jra55do_iaf #### commit message
* expt                 #### commit message

The * indicates the name of the current branch. In this case it is expt.

To push your changes remotely, you now can run

 git push myrepo expt

where you substitute “myrepo” and “expt” with the repository and branch names discovered above.

Download someone else’s configuration

When downloading the configuration files from someone else’s repository, it is a good idea to chat to them first so that:

  1. you can ensure you are not duplicating their work
  2. they can advice you on any bugs or limitations in their configuration, and
  3. you can start conversations about how to acknowledge their contribution.

You can download someone else’s repository using payu:

payu clone -b expt -B branch_name https://github.com/username/access-om3-configs/ mycopy

Where branch_name is the name of their branch. This is found at the top left hand corner on the GitHub repository page (e.g. in this example the branch is dev-025deg_jra55do_ryf). Username is the GitHub username of the person managing the repository and mycopy is what you want to call your experiment.
You can modify and run this experiment using the same instructions for setting up experiments.

1 Like