Since I started working with Software Carpentry (SWC), I’ve had to adjust quickly to working with a version control system. In the last few weeks, SWC switched from using Subversion to Github, and I had the chance to use both. I really like using Github, although I didn’t have long to try out Subversion. This post is dedicated to documenting how I use Github.
Most importantly: don’t be afraid to just try things! Github keeps copies of everything you do over time, as well as a clear history/log of all the changes that have been made. It is always possible to revert back to an old version of the repository, so you don’t have to worry about breaking things beyond repair. It’s okay to tinker.
(0) What is version control, and why do I need it?
Version control is a tool you can use to develop projects. It is a reliable way to share files between different computers and users. It allows people to work simultaneously on the same project while still tracking all the changes they make and managing any conflicts that arise in the changes. It keeps a permanent history of the state of all files in the project. That means that you can easily return to an earlier version of your project, without having to try to backwards edit.
In order to use Github, you have to make an account and install Git. The account is free, and quick and easy to make. The software is also quick to download and install. Here is a tutorial about setting up Git on your computer.
(1) Make or Find a Repository
If you are starting a new project, then you need to setup a new repository. A repository is just the place you’re going to story all your files, and it’s abbreviated as a “repo.” Github has a really great tutorial about how exactly to do the setup process, complete with very clear and helpful screenshots.
A lot of the time, you won’t actually need to create a new repo – although I definitely recommend trying it, even with something simple like your resume or CV (see SWC instructor Katy Huff’s CV repository for a good example). The nice thing about version control, though, is that only one person needs to create the initial repository, and then anyone can access it.
So, if you aren’t the pivot-person on a certain project, for example, you may not have to create the initial Github repo. Instead, your boss or some other member of the team would have already established the repo, and you just need to use it. If that’s the case, you need to find the repository on Github. The easiest way to do so is just to ask! For an example, Software Carpentry has a repository that contains all the code for their website, which can be found here.
(2) Get the Repository on your Local Machine
Once you find the repository you want to work with, you need to get a copy of it on your local computer. Right now it’s out there in cyberspace, hosted by Github.
Note: if you created the repository yourself, you probably already have a copy on your local machine, so you can skip some of these steps.
In order to get a copy, you need to “fork” the repository. When you fork a repository, you make you own copy of it on Github (online, not yet on your computer). Forking is used any time you want to contribute to a project or use a project as the starting point for your own. By this point, you should have found the project you want to work on (Step 1). Next, simply click the “Fork” button. You will be guided through a short series of prompts.
But, the repository still only exists on Github. Now you need to get it onto your local computer. If you’re not familiar with using the terminal on your computer, then I am including instructions on using the Github graphical user interface which intalls when you install Githhub.
In order to get the files on your local machine using the terminal, simply open a terminal, navigate to the desired directory, and use the command:
$ git clone repository-you-want-to-clone
(But make sure to substitute repository-you-want-to-clone with the link circled in green below.) When the command is finished executing, you should have all files on your machine.
Alternatively, to get a local copy without using the command line shell, simply click the button circled in red above – note that it should say Clone in Windows if you’re working on a Windows machine. Clicking the button will create a pop-up that asks to open Github on your local machine (tell it yes) and then will ask you to decide where you want to save your repository on your machine.
Once you tell it where to save, the files will be downloaded to your machine, viewable in your Github software, and can be accessed like any others.
(3) Making Changes
You can edit the files on your computer like you would any other file. The changes that you make are tracked over time, and can be viewed from Github or from the command line. To see the changes on the command line, try using:
$ git diff
As an example, I’m going to modify the README.md file in the repository I just forked and cloned, so that it says that I edited it. From the command line, I navigate to the directory where my repository is. Then I try “git diff” to see the following output, which reflects my changes:
I can see the same changes reflected through the Github local interface. By looking at the “Changes” tab along the left, I see:
(4) Commit Changes
Once you are happy with your changes, you can commit them. When you commit changes, you store your progress locally on your machine. Just like before, you can do this via the command line, or via the Github interface.
From the command line, you must first specify which files you want to commit. I only changed README.md, so I need only add README.md:
$ git add README.md $ git commit -m "testing a commit"
The “-m” flag just adds an optional message to accompany the commit.
Alternatively, in Github, you can select which files you want to commit, add the message (and a detailed description), and commit:
A list of your commits then appears in the Unsynced Commits section:
(5) Push Changes (Online)
Although you have committed your files locally, you still will not see the updates appear on Github online. In order to do so, you must push (or sync) your files. Via the command line, simply use the following command:
$ git push
Alternatively, in Github, simply click the Sync button seen in the image in Step 4.
No matter which technique you use, you can double-check that your files are synced with the online repository by checking the website of your forked repository:
(6) Pull Changes
Sometimes you will have a repository that has multiple people who can commit to it. When that happens, you may need to get changes made to that repository by others and update your own local files. Doing so is called pulling a repository.
From the command line:
$ git pull origin master
Or, in Github, choose the Branch tab on the left, and then click the Sync Branch button at the top right.
(7) Pull Requests
Sometimes, you will work on a forked repository, and you will want your changes to be incorporated back into the master repository. To do so, you can initiate a “pull request” via the Github webpage. Navigate to your forked repository, and then click the “Pull Request” button. It will automatically send a notification to the creators of the original repository, asking them to look at your suggestions. When they approve your request, they can merge your changes into the master repository.
(6) Get “Upstream” Changes
When you have a forked repository, it will not automatically incorporate changes made to the master repository. In order to get these changes, you need to track the “upstream” repository. Doing so takes two steps – fetching and merging.
From the command line:
$ git fetch upstream $ git checkout master $ git merge upstream/master