GitHub

1. Introduction

GitHub is a Git based code hosting platform. "It lets you and others work together on projects from anywhere."

GitHub makes it easy to get involved in code development, and provides hosting for basic websites. It is popular and reliable.

For a history of GitHub have a look at the GitHub Wikipedia Article

If you accept the GitHub Terms of Service, please create an account choosing a username comprising lower case letters and numbers. You do not need a GitHub account to complete this course, but it is recommended.

2. Getting Started with GitHub

Complete the Hello World Tutorial.

Git client software is available via 'AppsAnywhere' at the University of Leeds which is accessible remotely via the 'Academic' University Windows Virtual Desktop . Alternatively, follow these instructions to setup a Git Client on your local machine.

Complete the GitHub Create a Repository Tutorial and clone the repository to the local machine you are using by following the GitHub Clone a Repository Tutorial.

If you have followed correctly, you should now have a 'hello-world' local git repository cloned from a 'hello-world' remote repository on GitHub.

Now to practice making changes and keeping things synchronised: First, make a change in the local hello-world repository, commit the change, and then push the change to the remote repository on GitHub:

Open your local copy of 'README.md' in a text editor, make a change (for example, add a line of text) and save the file.
Open the git client command line interface and change to the local repository directory.
Commit the change to the local repository and then push this change to the remote repository on GitHub using the following commands:
```
git add .
git commit -m "change this commit message so it is informative"
git push
```

There are alternative ways to do this, but this way is recommended.

Now, check on GitHub that the 'README.md' file there is updated. You may need to reload the page in order to see the change.

Next, change the file on the remote GitHub repository using the browser and commit the change there: To edit the README click on the 'Edit Button' which looks like a pen (in dark mode it looks like the following where the button is identified with a red elipse: GitHub README edit
button ). Once you have finished editing, action the 'Commit changes' button to save the changes.

The remote repository is now 'ahead' of the local repository (which is 'behind'). To synchronize, pull the committed remote repository changes to the local repository: In the git bash tool in the repository directory directory enter:

git pull

You should see confirmation of this pulling the remote repository changes to the local repository.

There is a lot to GitHub that we are not going to use or learn about in this course including: forking repositories, creating branches, creating issues, resolving issues by submitting and accepting 'pull requests'. These are all commonly taken steps in collaborating on shared code bases in the GitHub ecosystem which is typically what a lot of team programming involves.

Something you may have to learn about is to deal with 'merge conflicts'. This is when changes have been made to the same file and in the same places such that the act of sychronizing the repositories now requires decisions to be made about which changes to keep. Let us deal with that in an ad hoc manner if and when it happens.

One of the main benefits of using git or a similar repository like system is that all changes are recorded and versioned, so it is possible to reset to an earlier version should this be desired, and this takes the difficulty away from doing all this in a more manual way.

3. Python Code Repository Setup

Create a new repository on GitHub which will be your code repository for this course, call it something simple (you can rename it later), include a README, and in the '.gitignore' section choose the 'python' option. Spend some time to choose a license and select this from the options available. There are a few different kinds of license. You are advised to choose an open source license and not write your own from scratch. The license is a legal document that states terms of use, modification and redistribution and provides a disclaimer to indemnify you if something goes wrong.

Clone your new repository so you have a local repository set up as was done with the 'hello-world' repository. Create a new folder/directory in the new repository called 'test'. Start Spyder; add a python command and save the code in a file in the newly created 'test' directory. Add and commit changes to the local repository and push the changes to the remote repository as was done with the 'hello-world' repository. Check the new file appears on GitHub.

Run the new Python file you have created. A directory named __pycache__ might appear in the test directory. This contains interpreted files generated by the Python interpreter. The GitHub '.gitignore' settings for Python will not push this directory contents to GitHub - which is what is wanted.

4. GitHub Pages

Create another repository on GitHub - your GitHub Pages Website. Follow the GitHub Pages Quickstart Tutorial

5. Taking Stock

The benefits of using GitHub and the command line interface for git might not yet be clear and this may seem a complicated distraction, but it is important to be aware of current programming practice and hopefully you will realise the benefits during the course as you become more familiar with programming and using git/GitHub.

As mentioned, there is a lot more to GitHub than has been covered here. Practised creating repositories, cloning, pulling, committing and pushing is something is good for now.

If you have decided against using GitHub, then consider using GitLab; Sourceforge, or BitBucket instead.

If you do not want to use these either, then consider using: Git, Mercurial or Subversion to set up a local repository.

As a minimum, please ensure your files are organised, versioned and backed up.