Guide to using DEA Notebooks with git

If you're developing notebooks for dea-notebooks, or reviewing someone's work there, it's useful to work with Git to track and push changes. This guide covers how to get set up with Git, along with how to use Git for development and review.

The guide is currently split into two sections:

1. Guide to using Git on the DEA Sandbox
2. Additional tips for using Git on the NCI

---

Guide to using Git on the DEA Sandbox

Setup

On launch, the sandbox is pre-populated with notebooks from the dea-notebooks repo. Specifically, with copies of the notebooks in the DEA_Sandbox folder on the master branch. However, for development and review, you'll need your own copy of the dea-notebooks repo that won't be overwritten by the sandbox's launch behavior. WARNING if you don't do this, you'll lose all your stuff when the repo gets updated, which happens at unpredictable intervals.

To get your own copy of the repository:

1. Open a terminal from the JupyterLab Launcher (click the "+" New Launcher button on the top-left of JupyterLab, then click "Other > Terminal")

2. Make a new directory to work in by typing:

   mkdir dev

3. You should see the dev directory appear in the file structure. Enter the new directory by typing:

   cd dev

4. Clone the notebooks repository by typing:

   git clone https://github.com/GeoscienceAustralia/dea-notebooks.git

5. Enter the notebooks directory by typing:

   cd dea-notebooks

Starting a new branch

1. Start a new branch (using develop as the base) by typing the command below (replace branch_to_work_on with a name of your choice)

   git checkout -b branch_to_work_on develop

Committing changes and pushing to GitHub

1. See which files you've changed by typing:

   git status

2. See the changes to notebooks by clicking the git extension button in the notebook

3. Add the files you want to commit by typing git add followed by the filenames you want to add or --all to add everything

4. Commit the files with a message by typing:

   git commit -m "Simple commit message"

5. Push your changes by typing git push

   • If this is the first push from this branch, you'll need to type:

   git push --set-upstream origin branch_to_work_on

6. Enter your Github username and password to complete the push. If you do not have a Github account, create one here.

Troubleshooting: If this is your first time using dea-notebooks, you will probably receive a remote: Permission to GeoscienceAustralia/dea-notebooks.git denied error. To resolve this, an existing member of dea-notebooks will need to invite you to the repository (Settings > Collaborators and Teams > Search by username, full name or email address > Add Collaborator)

Troubleshooting: If you get the error message: remote: Invalid username or password. fatal: Authentication failed for 'https://github.com/GeoscienceAustralia/dea-notebooks.git/', follow the guide to creating a personal access token here (only the "repo" tickbox needs to be selected in order to push to dea-notebooks). Once you have generated a token (a string of letters and numbers), save the token in a safe location (if you lose this you can regenerate it again). Now you can git push and when git asks for your user name and password in the sandbox, enter your GitHub username e.g. BexDunn and instead of entering your GitHub password, enter your token string e.g. 3i4htrou3fgffgyy45tysiduhg6779yho87rtiouhihrego7wery:

git push
Username: your_username
Password: your_token

Creating a pull request to add content to develop

Work can be added to the develop branch using a "pull request". A pull request will take all changes made to a branch and merge this into another branch (typically, develop). Because we don't always want all changes on a branch to be merged in, we need to first create a temporary pull request branch containing only the changes we want.

Creating a temporary pull request branch containing new work

1. Avoid merge conflicts later on by getting the latest version of the develop branch:

   git checkout develop
   git pull
   

2. Create a new temporary branch that is an exact copy of develop. This is where the files you want to publish will be placed (change temp_branch_name to a simple name of your choice that describes the changes you are making):

   git checkout -b temp_branch_name develop

3. Copy the files (e.g. Scripts/dea_datahandling.py) you want to publish from your main branch (e.g. branch_to_work_on that we created above) to this new temporary branch:

   git checkout branch_to_work_on -- Scripts/dea_datahandling.py

4. The new file (e.g. Scripts/dea_datahandling.py) will be added to the staging area of temp_branch_name, check using:

   git status

5. Commit the new file using:

   git commit -m 'your_message'

6. Push the temporary branch up to Github so we can create a pull request:

   git push --set-upstream origin temp_branch_name

Creating a pull request on Github

1. When you’ve pushed your changes and are ready for feedback, visit the pull requests page on the DEA Notebooks repository:

   https://github.com/GeoscienceAustralia/dea-notebooks/pulls

2. The name of the temporary branch you just pushed should appear in yellow. Click the green "Compare and make pull request" button to the right.

3. This will take you to the 'Open pull request' page.

4. Add a description of your changes, and select people you’d like to review it

5. Post it in Slack and ask for feedback

Contributing to someone else's pull request

1. To make changes/updates/edits to someone else's pull request, first check out the branch you want to edit (e.g. pull_request_branch):

   git checkout --track origin/pull_request_branch

2. Commit and push any changes you make, which will become part of the open pull request

Staying up-to-date

• You can update your branch by checking it out, then typing git pull

  • You should regularly do this for the develop branch

• To get the latest updates from the develop branch back into your own branch, follow the steps below (this can also be useful to check for conflicts between your branch and develop):

  git checkout develop
  git pull
  git checkout branch_to_work_on
  git merge develop
  

• When the text message pops up to give the merge commit a name, it will be in the Vi editor. To accept the default message, hit Esc on your keyboard, followed by :wq

Guide to using Git on the NCI

The above instructions should work for setting up Git on both the DEA Sandbox and the NCI (via the Virtual Desktop Infrastructure or VDI). However, there are some important things to keep in mind:

• To get started with dea-notebooks using git on the NCI, the first step is to clone this repository to a suitable location. This will most likely be a location you can access on the VDI, so you can easily work with your notebooks. Note that this repo is likely to become quite large, so make sure you have enough space in the location you clone the repository to (i.e. probably not your home directory, but a directory on /g/data/ should be perfect).
• If you haven't used Git on the VDI before, you will need to set up some SSH keys before you will be able to clone the repository. To set up the SSH keys, follow the instructions here to generate an ssh key pair in your home directory on the vdi. You will need to generate the key, register it with your ssh agent, and then add the newly generated id_rsa.pub public key to your GitHub account.