How to clone, create branch, commit changes, push changes, and open a pull request
The steps are geared more towards the first time user.
With SSH keys, you don't need to enter your GitHub password every time you interact with a repository. This is particularly convenient when performing actions like pushing changes, pulling updates, or cloning repositories. This step is optional but definitely save your time later.
Open terminal, and paste the text below, replacing the email used in the example with your GitHub email address
ssh-keygen -t rsa -b 4096 -C "[email protected]"When you're prompted to Enter a file in which to save the key, you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key.
Now you can check your ssh key. Assume you save it at the default location:
cat ~/.ssh/id_rsa.pubCopy the contents of your key to your clipboard (we will need it later).
Once can follow this instruction to add ssh key to your github account.
If you have created SSH key (id_rsa) previously, you may need to add the following to /ncrc/home1/XX.XX/.ssh/config:
# START GitHub SSH key
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_rsa_git
# END GitHub SSH key
While you can perform code editing using the GitHub web interface, it's beneficial to have the GitHub CLI gh installed on your machine if you prefer working in a terminal environment.
Users who are interested in how to install Github CLI can follow this instruction. Considering that users may not have the authority to install software on HPC platforms (e.g., Gaea), here we will do the easiest way to just Download release binaries that match your platform.
Go to this website, and find one that match your platform. Here we will choose GitHub CLI 2.40.1 linux amd64 as an example.
wget https://github.com/cli/cli/releases/download/v2.40.1/gh_2.40.1_linux_amd64.tar.gz
tar -zxvf gh_2.40.1_linux_amd64.tar.gz
export PATH=/YOUR_PATH/gh_2.40.1_linux_amd64/bin:$PATH
gh auth loginThen, follow the on-screen instructions to finish the setup.
Yi-cheng.Teng@gaea53:/lustre/f2/dev/Yi-cheng.Teng/GFDL-MED/github> bash
Yi-cheng.Teng@gaea53:/lustre/f2/dev/Yi-cheng.Teng/GFDL-MED/github> wget https://github.com/cli/cli/releases/download/v2.40.1/gh_2.40.1_linux_amd64.tar.gz
Yi-cheng.Teng@gaea53:/lustre/f2/dev/Yi-cheng.Teng/GFDL-MED/github> tar -zxvf gh_2.40.1_linux_amd64.tar.gz
Yi-cheng.Teng@gaea53:/lustre/f2/dev/Yi-cheng.Teng/GFDL-MED/github> export PATH=/lustre/f2/dev/Yi-cheng.Teng/GFDL-MED/github/gh_2.40.1_linux_amd64/bin:$PATH
gh auth loginThen follow the on-screen instructions, first select GitHub.com.
Next select your preferred protocol for Git operations on this host. Here we choose SSH.
Next it will ask the location of your SSH public key to your Github account. Normally it should be like this $HOME/.ssh/id_rsa.pub if you follow Section 0.0 to create your SSH public key.
Next it will ask the title for your SSH key. Here we type : Gaea
Next it will ask how would you like to authenticate GitHub CLI. Here we choose Paste an authentication token. Then follow the on-screen instructions to finish the final step. To test if it works ok, user can try:
gh auth statusIt should report your current active github account.
There are two ways to clone the repository: SSH authentication (require SSH keys set up) or HTTP.
1.1 SSH (Require SSH keys set up first, Please check out Section 0.0 for more details.)
git clone [email protected]:NOAA-CEFI-Regional-Ocean-Modeling/ocean_BGC.git --recursive
cd ocean_BGC
git branchThis should clone the ocean_BGC repo and show you the branch name we just cloned.
* dev/cefigit clone https://github.com/NOAA-CEFI-Regional-Ocean-Modeling/ocean_BGC.git --recursive
cd ocean_BGC
git branchSince ocean_BGC is a public repo, you should be able to directly clone it without any issues using HTTP URL. However,
If the repository requires authentication, git will prompt you for your username and password. Alternatively, you can use an access token or SSH keys for authentication, depending on the hosting platform.
Also it is a good idea to configure git so that it will not ask you for your login credentials for every repository it downloads when using HTTP URL. So, if you haven’t done so already on your platform, run the following commands:
git config --global credential.helper 'cache --timeout=3600'
git config --global --add credential.helper 'store'This stores your git credentials in your home directory for one hour (3600 seconds). To remove the cached credentials and disable credential caching for git, you can use the following commands:
git config --global --unset-all credential.helperAfter executing these commands, git should no longer cache your credentials, and you'll be prompted to enter your username and password (or use another authentication method) the next time you interact with a git repository that requires authentication.
You can generate a Personal Access Token following the instruction here. We recommend users select at least the minimum required scopes: 'repo', 'read:org', 'admin:public_key'.
git checkout -b feature/clean_codeNow you create a new local branch named feature/clean_code Now, you can start editing the code! You can always use git branch to check which branch you are working.
# Make changes to files
git add generic_tracers/generic_COBALT.F90
git commit -m "change default value for imbalance_tolerance"you can always redo git add and git commit -m if you've made additional changes after the initial commit. Here's how you can do it:
# Make changes to other files
git add generic_tracers/generic_tracer.F90
git commit -m "change interface for cobalt 4p"git push origin feature/clean_code#Switch to the Main Branch:
git checkout dev/cefi
#Pull the Latest Changes from main branch:
git pull origin dev/cefi
#Switch to Your Feature Branch:
git checkout feature/clean_code
#Merge new chnages in main to Your Feature Branch:
git merge dev/cefi
#Resolve Conflicts (If Any):
#If there are any conflicts, Git will prompt you to resolve them. Edit the conflicting files, add them to the staging area using `git add`, and then continue the merge with `git merge --continue`.
#Push the Updated Feature Branch:
git push origin feature/clean_code
You can open a pull request on Github either through the website or using the Github CLI. If you prefer the CLI:
gh pr create --base dev/cefi --head feature/clean_code --title "Change default value for imbalance_tolerance" --body "as titled."First in your page of repo (e.g. ocean_BGC), click Pull Requests (located at the top row), and then click New Pull Request
In the next page, you can select your desired feature branch and compare it with the main branch or any other branches you are interested in. You can switch to split mode for better visualization, making it easier for you to compare the differences:
Sometimes you may not like your changes and want to go back to a previous commit. You can follow the step-by-step guide below for different scenarios:
# Go to the commit you want to go back to
git log
git reset --hard <commit-hash>
# If you've already pushed the commit to GitHub, force push to update the remote branch
git push origin <branch-name> --force# Go to the commit you want to go back to
git log
git checkout -b new-branch-name <commit-hash>
# Create a new commit that undoes the changes
git revert <commit-hash>
# Push the new branch to GitHub
git push origin new-branch-name# Go to the commit you want to go back to
git log
git reset --hard <commit-hash>
# Force push to update the remote branch
git push origin <branch-name> --force