Getting started with Git

If you are accessing dea-notebooks via the DEA Sandbox or National Computational Infrastructure and wish to save your work between sessions, you will need to either clone a copy of our default resources or download your work each session. This is required because changes made to Jupyter notebooks in the DEA Sandbox or NCI environment are regularly overwritten as part of automatic updates, meaning any changes you make may be lost.

To create a personal copy of dea-notebooks, you will need to get started with Git - a version control system that supports collaboration on code-based projects by intelligently tracking changes in files.

Read more about GitHub and Git.

Sign up for a free GitHub.org account

The Creating an account on GitHub guide will help you to set up a free GitHub account, allowing you to create personal copies of dea-notebooks and contribute your own code back to the repository.

To work with Git and dea-notebooks, you can complete your Git-related actions directly in the github.com browser and via the command line in the DEA Sandbox and NCI environment. DEA Sandbox also has a Git toolbar in the left-hand workbench menu that simplifies many git tasks, eliminating most of the need to work on the command line.

Getting your own copy of dea-notebooks

To avoid losing your work between DEA Sandbox (or NCI) sessions, you will need to:

• "Clone" or create a copy of the dea-notebooks repository into a new folder
• Create a new "branch" of the repo which serves as a personal workspace where you can work on code until you are ready to submit it back to dea-notebooks

To do this inside the DEA Sandbox:

1. Log in or sign up to the DEA Sandbox.

   The sandbox will contain default Notebooks from the stable branch of the dea-notebooks repository. Learn more about the DEA Sandbox.

   :warning: Warning
   Changes to these default Notebooks will not be saved, so we have to create our own copy of them to work on.

   

2. Open a new command-line terminal by clicking the blue "+" (New Launcher) button in the top-left corner to open the Launcher then click to open the Terminal. This is a Linux terminal for your Sandbox environment.

3. Navigate to your home directory by typing the following:

   cd ~
   

4. Clone a copy of dea-notebooks into a new folder called dev by typing the following:

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

5. Configure a git email and name (email should match the email you used to sign up to Github):

   git config --global user.email "[email protected]"  # Change this to your email
   git config --global user.name "Your Name"  # Change this to your name
   

6. Then, navigate into this folder as follows:

   cd dev
   

7. Create a new branch with a name of your choice (replace 'your-branch' with a relevant branch name to you).

   git checkout -b your-branch develop
   

You will now have a persistent version of dea-notebooks where your changes will not be overwritten by automatic updates. When you are ready, changes you make to this branch can be sumbitted back to dea-notebooks as a "pull request".

Keeping up to date

Don't forget to regularly compare to the default notebooks to check for updates and changes. You can do this by manually comparing to the top level notebooks in your DEA Sandbox directory, or you can use git to check out the latest changest automatically and "merge" them into your branch:

git checkout develop
git pull
git checkout your-branch  # replace 'your-branch' with the name of the branch you created above
git merge develop

This Git cheatsheet can help you get started.

Next steps

Now that you have cloned dea-notebooks and set up a new branch, you can follow the guides below to:

• Edit an existing Notebook, or
• Create a new Notebook