Guide to working within your own Git repository on the Sandbox

While the DE Africa Sandbox comes with a series of notebooks, you may like to develop your own, or even collaborate with others! To do this, you can make your own git repository to store your notebooks, and load them into the Sandbox.

This guide will assume you have some familiarity with git, particularly how to use it on the command line. If you're not comfortable with git, we'd recommend working through some introductory tutorials to get more familiar with the terminology.

Setup

You'll need a Github account, as well as a repository. To set up a new repository for you project, see https://docs.github.com/en/github/getting-started-with-github/create-a-repo

Adding your repository to the Sandbox

1. Visit the home page of your repository.

2. Click the green Code button, and copy the displayed URL. It should be something like https://github.com/<user_name>/<repository_name>.git

3. Open and log in to the DE Africa Sandbox

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

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

   mkdir dev

6. You should see the dev directory appear in the file structure. In the terminal, enter the new directory by typing:

   cd dev

7. Clone your repository by typing:

   git clone https://github.com/<user_name>/<repository_name>.git

   where the URL is the same as the one you copied in Step 2. This will create a new folder that has the same name as your repository. This folder will sit inside the dev folder.

8. Enter the repository directory by typing:

   cd <repository_name>

Working with your repository

You can now work directly in the new repository folder. This section will cover how to add files and changes and then commit them to GitHub. Once you commit your changes back to Github, others can see your work and update it!

Committing changes and pushing to GitHub

1. Add a new notebook file to your repository folder, you can leave it blank for now.

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

   git status

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

4. Add the files you want to commit by typing git add <filename> or git add --all to add everything in the repository.

5. Commit the files with a message by typing:

   git commit -m "Simple commit message"

6. 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 <branchname>

7. If you go to your repository on Github, you should see the files and changes that you commited. Each time you're ready to share your work, add the files, commit the files, and push the files.

Updating your repository

We recommend you do this regularly to receive changes that others have contributed.

1. Get a view of the up-to-date version of the original repository by typing

   git fetch upstream

2. Ensure you're in your repository's main branch by typing

   git checkout main

3. Merge the changes from the original repository by typing

   git merge upstream/main

4. Add these changes to any branch you're working on (see "Starting a new branch" below) by typing

   git checkout <branchname>

   git merge main

   Make sure to replace <branchname> with the name of your branch, e.g. feature-newnotebook

Starting a new branch

Branches are a useful way to keep work self-contained until you're ready to add it to the main repository.

1. Start a new branch (using main as the base) by typing

   git checkout -b <branchname> main

   Make sure to replace <branchname> with the name of your branch, e.g. feature-newnotebook

Working on an existing branch

1. Checkout an existing branch by typing

   git checkout --track upstream/<branchname>

   Make sure to replace <branchname> with the of the branch you want to use, e.g. feature-existingnotebook. You can see a list of branches available on the original repository by typing

   git branch -r

   and noting which ones begin with upstream/