A brief intorduction to how to set up use GitHub Desktop

Contents:

• Setting up GitHub for the first time
• Using GitHub Desktop to clone a new copy of your repository
• Using GitHub Desktop with your existing repository

Setting up GitHub for the first time

Git and Github are critical tools for any programmer. Git is an Open Source and very widely used version control system that is used to keep track of all of the work that you have done on a particular coding project, which allows you (for example) to have multiple versions of your code at the same time or to revert your code back to a previous point in history. Git stores all of your code, history and everything else in a Git Repository, which on your computer looks just like a regular directory.

GitHub is a website owned by Microsoft that provides functionality to store online Git Repositories, which you can use to sync projects across multiple machines, collaborate with other programmers, keep a backup of your code and history, release Open Source code to the community, and lots of other things too!

GitHub Desktop is a software package produced by Microsoft that acts as a front end to Git. You can use it to keep your code up to date with the remote Git Repository hosted on GitHub. In this course, we will be using software called GitHub Desktop to hadle all of our Git operations.

the use of Git and GitHub are an important part of our learning, and (critically) an important part of how you are assessed. You will need to submit your assessment code as a GitHub repository (with complete history), and inadequate version control will severely limit the number of marks that you are able to attain. Please make the effort to get used to it early!!

Set up and activate an account on GitHub with the username gis-[student number], for example, if you had student number 123456789, then your user account would be gis-123456789. Please do this even if you already have another GitHub account - but only do it once for this course! Be sure to remember your username and password!

Once you have your GitHub account sorted, you can get set up to begin the course:

Go to this GitHub repository to get the template for the course. Click on the green Use this template button in the top tight and select the option for Create a new repository. Name the repository understandinggis, set visibility to Private and click the green Create Repository button:

When the process is finished, click on the Green <> Code button and select the SSH tab, then click the button to the right of the grey box (containing text beginning git@github...) to copy the contents to your clipboard (if you have any issues with this, you can just highlight the URL and copy it in the normal manner)

Go to your P Drive folder (just double click on the icon on your Desktop) and see if you have a Directory called UGIS there already. If you do, open it and make sure it is empty. If not, create one in Windows Explorer (or Mac Finder) just as you normally would.

Open GitHub Desktop and make sure you are logged in (using your GitHub account username and password)

Select your understandinggis directory in the list on the left (this is your remote repository) and click the blue clone button at the bottom:

In the box that pops up, use the Choose button to navigate to your UGIS directory (this will be your local repository). Click the Clone button:

It will take a few seconds to do the clone and you are then ready to go.

Using GitHub Desktop to clone a new copy of your repository

GitHub Desktop is installed in the HBS and ALB computer labs already. If you are working on your own machine, then you need to make sure that you have Installed GitHub Desktop

Open it, and log in.

If you are adding your repository to a new machine, then you will need to follow these steps:

Create a directory called UGIS somewhere on your system - probably in your Documents.

Select your understandinggis directory in the list on the left and click the blue clone button at the bottom

In the box that pops up, use the Choose button to navigate to your UGIS directory, this is where it will store the local version of your understandinggis repository

It will take a few seconds to do the clone and you are then ready to go. There is just one more step…

In Spyder, open and run the download_data.py script (watch the outputs to monitor progress, as it will take a little while) - this will install the necessary datasets for the course in your UGIS directory.

You are now set up and ready to go! If you keep the Changes tab open, then any edits you make in your repository will appear in the list.

Here is how to use it:

• When you are ready to commit, simply add a short message to the Summary box (ignore the Description) and click the blue Commit to main button.

• When you are ready to push (I would just do this every time you commit), either click the blue Push origin button that appears in the panel on the right (which will only be there just after you commit), or the Push origin button in the black bar at the top (which is always there).

OR

• If you have switched machine, then you will need to sync your local repository to the remote. To do this, click on the small arrow next to the Push origin button in the black bar at the top, and select Fetch Origin

Using GitHub Desktop with your existing repository

GitHub Desktop is installed in the HBS and ALB computer labs already. If you are working on your own machine, then you need to make sure that you have Installed GitHub Desktop

Open it, and log in.

If you already have a copy of the understandinggis repository, all you will need to do is point GitHub Desktop at it. Here’s how:

Use the Windows menu to open GitHub Desktop (if you are on a Mac, just open it from Spotlight or your your Applications directory) and make sure you are logged in.

Either select Add an Existing Repository from your Local Drive and browse to your understandinggis directory, or simply drag and drop your understandinggis directory from Windows Explorer (or Mac Finder) into the GitHub Desktop Window - then press Add Repository

You are now set up and ready to go! If you keep the Changes tab open, then any edits you make in your repository will appear in the list.

Here is how to use it:

• When you are ready to commit, simply add a short message to the Summary box (ignore the Description) and click the blue Commit to main button.

• When you are ready to push (I would just do this every time you commit), either click the blue Push origin button that appears in the panel on the right (which will only be there just after you commit), or the Push origin button in the black bar at the top (which is always there).

OR

• If you have switched machine, then you will need to sync your local repository to the remote. To do this, click on the small arrow next to the Push origin button in the black bar at the top, and select Fetch Origin