GitHub (https://github.com/) is a popular web-based system for storing and managing source code. While there are several alternatives, GitHub is particularly popular with people writing and sharing open source Python code, and this is the source code management system that we will use in this book.

Before delving into the specifics of GitHub, let's start by looking at how source code management systems work in general and why you might want to use one.

Imagine that you are writing a complex module and have opened your module in a text editor to make a few changes. While making these changes, you accidentally select 100 lines of code and press the Delete key. Before you realize what you've done, you save and close the file. Too late: those 100 lines of text are gone.

Of course, you might (and hopefully will) have a backup system in place which keeps regular backups of your source files. But if you had made changes to some of the missing code in the past few minutes, you are likely to have lost those changes.

Now consider a situation where you've shared a module or package with a colleague, and they decide to make a few changes. Perhaps there's a bug that needed fixing or a new feature they wanted to add. They change your code and send it back to you with a note describing what they've done. Unfortunately, unless you compare each line in the original and modified versions of your source files, you can't be sure exactly what your colleague has done to your files.

A source code management system solves these types of problems. Instead of just having a copy of your module or package sitting in a directory on your hard disk, you create a repository within a source code management system such as GitHub, and commit your source code to this repository. Then, as you make changes to your files, fixing bugs and adding features, you commit each change that you make back to the repository. The source code repository keeps track of every change you have made, allowing you to see exactly what has been changed over time and, where necessary, undoing changes that were made previously.

You aren't limited to having just one person work on a module or package. People can fork your source code repository, creating their own private copy of it, and then use this private copy to fix bugs and add new features. Once they've done this, they can send you a pull request which includes the changes they have made. You can then decide whether or not to merge those changes into your project.

Don't worry too much about these details, though—source code management is a complex topic, and there are lots of sophisticated tricks you can perform using tools such as GitHub to manage your source code. The important thing to remember is that you create a repository to hold the master copy of the source code for your module or package, commit your code into this repository, and then continue to commit each time you fix a bug or add a new feature. The following illustration summarizes this process:

The trick with a source management system is to commit regularly—every time you add a new feature or fix a bug, you should immediately commit your changes. This way, the difference between one version and the next in the repository is only the code which adds that one feature or fixes that one problem. If you make a number of changes to your source code before committing, the repository will be a lot less useful.

Now that we've seen how source code management systems work, let's implement a real example to see how to use GitHub for managing your source code. First off, go to the main GitHub site (https://github.com/). If you don't have an account with GitHub, you will need to sign up, choosing a unique username, as well as supplying a contact e-mail address and password. If you have used GitHub before, you can sign in with the username and password you have already set up.

Note that it's free to sign up and use GitHub; the only limitation is that every repository you create will be public, so anyone who wishes to can see your source code. You can set up private repositories if you want, but these do incur a monthly charge. However, since we are using GitHub to share our code with others, having a private repository doesn't make any sense. You'd only need a private (paid) repository if you wanted to share your code with a select group of people while preventing anyone else from accessing it. If you're in the position of having to do this, though, paying for a private repository is the least of your concerns.

Once you have signed in to GitHub, your next task is to install the command-line tools for Git. Git is the underlying source code management toolkit used by GitHub; you'll use the git command to work with your GitHub repository from the command line.

To install the required software, go to https://git-scm.com/downloads and download an installer for your particular operating system. Once this has finished downloading, run the installer and follow the instructions as it installs the git command-line tools. When this is finished, open a terminal or command-line window, and try typing the following command:

git --version

All going well, you should see the version number of the git command-line tools you have installed.

With these prerequisites out of the way, let's use GitHub to create an example repository. Go back to the https://github.com/ web page and click on the + New Repository button highlighted in green. You will be asked to enter the details of the repository you want to create:

To set up your repository, enter test-package for the repository's name, and choose Python from the Add .gitignore drop-down menu. A .gitignore file is used to exclude certain files from the repository; using a .gitignore file for Python means that the temporary files Python creates won't be included in the repository.

Finally, click on the Create repository button to create the new repository.

Now that the repository has been created on GitHub, our next task is to clone a copy of that repository onto your computer's hard disk. To do this, create a new directory named test-package to hold your local copy of the repository, open up a terminal or command-line window, and use the cd command to move to your new test-package directory. Then, type the following command:

git clone https://<username>@github.com/<username>/test-package.git .

Make sure you replace both instances of <username> in the preceding command with your GitHub username. You will be prompted to enter your GitHub password to authenticate yourself, and a copy of the repository will be saved into your new directory.

Because the repository is currently empty, you won't see anything in your directory. However, there are some hidden files that git uses to keep track of your local copy of the repository. To see these hidden files, you can use the ls command from a terminal window:

$ ls -al
drwxr-xr-x@  7 erik  staff   238 19 Feb 21:28 .
drwxr-xr-x@  7 erik  staff   238 19 Feb 14:35 ..
drwxr-xr-x@ 14 erik  staff   476 19 Feb 21:28 .git
-rw-r--r--@  1 erik  staff   844 19 Feb 15:09 .gitignore

The .git directory holds information about your new GitHub repository, while the .gitignore file contains the instructions you asked GitHub to set up for you to ignore the Python temporary files.

Now that we have an (initially empty) repository, let's create some files in it. The first thing we need to do is choose a unique name for our package. Because our package is going to be submitted to the Python Package Index, the name must be truly unique. To achieve this, we'll use your GitHub username as the basis for our package name, like this:

<username>-test-package

For example, since my GitHub username is "erikwestra", the name I would use for this package would be erikwestra-test-package. Make sure you select a name based on your GitHub username, to make sure that the package name is truly unique.

Now that we have a name for our package, let's create a README file describing this package. Create a new text file named README.rst in your test-package directory, and place the following into this file:

<username>-test-package
-----------------------

This is a simple test package. To use it, type::

    from <username>_test_package import test
    test.run()

Make sure you replace each occurrence of <username> with your GitHub username. This text file is in reStructuredText format. reStructuredText is a formatting language used by PyPI to display formatted text.

When the user views your repository on GitHub, they will see the contents of this file neatly formatted according to the reStructuredText rules:

If you want to learn more about reStructuredText, you can read all about it at http://docutils.sourceforge.net/rst.html.

Now that we have set up the README file for our package, let's create the package itself. Create another directory inside test-package named <username>_test_package, replacing <username> with your GitHub username, and place an empty package initialization file (__init__.py) inside this directory. Then, create another file inside the <username>_test_package directory named test.py, and enter the following into this file:

import string
import random

def random_name():
    chars = []
    for i in range(random.randrange(3, 10)):
        chars.append(random.choice(string.ascii_letters))
    return "".join(chars)


def run():
    for i in range(10):
        print(random_name())

This is just an example, of course. Calling the test.run() function will cause ten random names to be displayed. More interesting is the fact that we have now defined the initial contents for our test package. However, all we've done is created some files on our local computer; this doesn't affect GitHub at all, and if you reload your repository page in GitHub, none of your new files will show up.

To have our changes take effect, we need to commit our changes to the repository. We'll start by taking a look at how our local copy differs from the one in the repository. To do this, go back to your terminal window, cd into the test-package directory, and type the following command:

git status

You should see the following output:

# On branch master
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#  README.rst
#  <username>_test_package/
nothing added to commit but untracked files present (use "git add" to track)

The description can be a bit confusing, but it's not too tricky. Basically, GitHub is telling you that there's a new file, README.rst, and a new directory, named <username>_test_package, which it doesn't know about (or, in GitHub parlance, is "untracked"). Let's add these new entries to our repository:

git add README.rst
git add <username>_test_package

Make sure you replace <username> with your GitHub username. If you now type git status, you'll see that the files we created have been added to our local copy of the repository:

# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#  new file:   README.rst
#  new file:   <username>_test_package/__init__.py
#  new file:   <username>_test_package/test.py

Whenever you add a new directory or file to your project, you will need to use the git add command to add it to the repository. At any time, you can see if you've missed any files by typing the git status command and looking for "untracked" files.

Now that we've included our new files, let's commit our changes to the repository. Type the following command:

git commit -a -m 'Initial commit.'

This commits a new change to your local copy of the repository. The -a option tells GitHub to automatically include any changed files, and the -m option lets you enter a brief message, describing the changes you have made. In this case, our commit message is set to the value "Initial commit.".

Now that we've committed our change, we need to upload from our local computer to the GitHub repository. To do this, type the following command:

git push

You will be prompted to enter your GitHub password to authenticate yourself, and the changes you have committed will be stored into your repository on GitHub.

Now that your changes have been pushed to the server, you can reload the page on GitHub, and your newly created package will appear in the repository:

You will also see the contents of your README.rst file displayed below the list of files, describing your new package and how to use it.

Whenever you make changes to your package, make sure you run through the following steps to save your changes into the repository:

There's a lot more to using GitHub, of course, and a great many commands and options that you will no doubt want to explore once you get into it—but this is enough to get you started.

Once you've set up a GitHub repository for your Python module or package, it will be easy to share your code with someone else. All you need to do is share a link to your GitHub repository, and the other person can download the files they want.

To make this process even easier and make your packages searchable so that they can be found by a wider audience, you should consider submitting your package to the Python Package Index. We'll look at the steps involved in doing this next.