Git with Terminal

The ultimate tool for file versioning with Git in the DE Africa Sandbox is the Terminal. You can open a Terminal window from the Launcher tab by clicking on the Terminal icon.

In this section, we will show how to use Terminal to create a branch and push changes to your fork. This involves typing commands into the Terminal command line.

It is assumed you have forked and cloned the deafrica-sandbox-notebooks repo as described in the Connect to Git section. Familiarity with the section Git with the Git menu, including concepts such as push, pull, branch and commit will be useful. If you are new to Git, you are encouraged to try both tutorials.

Please ensure you have also updated your fork to match digitalearthafrica:master by selecting Fetch upstream and Fetch and merge from your fork’s GitHub page.

A recap on why we create a branch to make changes:

• The master branch is the main branch that contains all the most up-to-date and tested code

• Every time you want to add a new feature or test code, you make a new branch

• The new branch contains all of the code from master, but any changes made to that branch do not affect master

• Once you are confident your changes are working, you can request to add your changes back to master in a Pull Request (covered in a later section of the guide)

Terminal: a breakdown

The Terminal interface has two main components:

1. The current directory you are in

2. The command line, where you can type commands

Check your clone is up to date

1. Open a Terminal window from a Launcher tab. You can open a new Launcher tab by pressing the + button at the top of the File Browser menu.

Terminals automatically start in your home directory. Type ls and press Enter on your keyboard to show all files and folders in your home directory.

2. Change the directory of your Terminal to your clone of the deafrica-sandbox-notebooks repo. This can be done by using cd, the “change directory” command. The syntax is cd <folder name>/.

In Terminal, type:

cd dev/deafrica-sandbox-notebooks/

and hit Enter. Notice your directory has now changed: the $ is now after /dev/deafrica-sandbox-notebooks.

3. Check your clone is up to date by running:

git pull

This will pull any changes between your fork and this local clone.

Terminal tips

• Press the Tab key on your keyboard to auto-complete file paths and file names. This is much faster and generally more accurate than typing manually.

• Press the Up arrow key on your keyboard to access Terminal commands you have previously executed. Great for repeating a command.

• The File Browser does not show which directory your Terminal is in. Terminal directory location and File Browser folder location are completely independent.

• The File Browser does show the content of the branch you are in. This means files in one branch but not another will appear or disappear when you switch branches. Therefore, it is always good to know which branch you are on.

• Terminal commands are case-sensitive.

By convention, Terminal code is often identified with a ! at the start of the line, but for clarity will not be used in this tutorial as ! is not required in Terminal itself. (Jupyter Notebooks allow Terminal commands to be run inside .ipynb files by using code cells starting with !; this is not covered here.)

Tutorial: Use Terminal to create a new branch and make changes

We will use the Terminal in the Sandbox to:

• make a new branch;

• add a file (this will be done using File Browser, although it can be done by Terminal);

• commit the changes; and

• push the changes to the remote repo.

Your Terminal commands may be different if you have named your repositories or branches differently from the examples provided here or in the Connect to Git tutorial, or if they are located in a different folder arrangement.

Make a new branch

1. In the Terminal, navigate to your deafrica-sandbox-notebooks directory if you aren’t there already.

cd dev/deafrica-sandbox-notebooks/

2. Make a new branch using the git checkout -b command. git checkout moves between branches, and the -b creates a new branch.

git checkout -b git-terminal

You will see the message Switched to a new branch 'git-terminal'.

Add a new file

1. Open the File Browser. Navigate. Click on the Notebook > Python 3 icon in the Launcher to make a new Jupyter Notebook file.

2. The file will automatically open.

3. Type something in the first cell of the file, for example print("This is a change to the git-terminal branch"). Ensure the dropdown menu at the top of the file says “Code”. Press Shift + Enter on your keyboard to execute the cell. This will print the text you entered underneath the code cell.

4. Let’s rename the file. Right-click on the file in the file browser and select Rename.

5. Type your new file name. Here we have called it my-change. It has the file extension .ipynb.

Commit changes: track new files

1. Go back to your Terminal tab and run

git status

This will show output indicating current branch and untracked files, such as the new file you just created.

2. As suggested in the Terminal output, we use git add <filename> to start tracking the file.

git add my-change.ipynb

Run git status again to see the file name has changed to a green colour and it no longer says untracked.

3. Go back to my-change.ipynb and add some text or code. Save the file.

4. Switch back to the Terminal tab and run git status again. The modifications show up as unstaged changes.

Run git add my-change.ipynb again to include the new modifications in your commit.

4. When all the changes you want to make in that commit are staged, run the command

git commit -m "This is a brief description of my commit."

The text in the quotation marks should be replaced with a brief description of the commit.

5. Run git status again, and your committed changes have disappeared. The output will say nothing to commit, working tree clean.

Commit changes: set upstream

The easiest way to set upstream is as follows:

1. Run:

git push

2. This will give you the error message fatal: The current branch git-terminal has no upstream branch.. It will suggest to you a command that looks like:

git push --set-upstream origin git-terminal

3. The suggested code is usually correct. Use your mouse to copy the suggested line of code. Copy by pressing Ctrl+C then click back to your command line text cursor. Paste using Ctrl+V and press Enter to run.

4. Enter your GitHub username and Personal Access Token or similar, as prompted.

Push committed changes

1. Return to your Terminal tab. Run:

git push

2. Enter Git credentials as prompted.

Congratulations, you’re all done. As suggested in the previous section, you can now go to your fork on the GitHub website and check for your new branch, git-terminal, as well as the new file only visible there.

Git checklist with git status

Things to check when you log into the Sandbox and start working on your open-source code project:

• Have you fetched and merged upstream so your fork is up-to-date with the original repository?

• Which branch are you on? Is that the correct branch to be working from?

• Have you pulled and merged the latest changes to your clone from your fork of the repository?

The git status command will help you identify which branch you are currently on, as well as list any staged or unstaged changes, and any untracked files.

Terminal command summary

• cd <folder path> Changes directory to the new folder path

• cd .. Goes up one on the folder path (back one folder)

• cd Resets directory to home

• ls Shows files and folders in the current directory

• git status Summary of your Git repository

• git pull Pulls commits from the remote to local

• git checkout -b <new branch name> Creates new branch based off current branch and checks out the new branch

• git checkout <branch name> Checks out existing branch

• git add <file or folder> Stages all changes in the file or folder

• git commit -m "description" Commits staged changes to a commit described by the description

• git push Pushes commits to the remote repo

With a bit of practice, Terminal commands are faster than using the Git menu interface, and can provide a greater level of control and flexibility.

Common issues

• Terminal error “fatal: not a git repository”. This occurs when your Terminal directory location is not a folder linked to a Git repo. Your home directory is not linked to Git, and your dev folder is not linked to Git.

• One of my files has disappeared but I did not delete it. You could be on the wrong branch. Run a git status to check your current branch. Use git checkout <branch name> to move between branches.

• Git is not accepting my Git password when credentials are requested. For security reasons, the Sandbox requires a Personal Access Token separate to your password, or another form of multi-factor authentication. They are simple to set up. See the official GitHub article and guide linked on the Connect to Git page.

As Git is well-documented online, it is recommended you Google search any issues when troubleshooting.

GitHub wiki tutorial

A concise version of this tutorial can be found on the deafrica-sandbox-notebooks wiki. It also contains useful Terminal commands not described here.

Next steps

One way or another, you have made changes to your fork of the repository. You’ve branched, committed, pulled and pushed, and your code is ready to be seen by the masses.

The only problem — it’s on your GitHub repository and no one else knows it’s there. Time to fix that: the next section shows you how to make a pull request. Pull requests allow users to propose code mergers between repositories and branches through a documented review system.

Click Next to continue.