Open Source Science with Git and Github: a tutorial
What is Git and why do you want it?
Git is a revision control management system12. It helps you keep track of changes to your files. You’ve probably had the following thing happen to you before:
I certainly have:
Notice:
- Different versions of the same document have different filenames.
- The date and author of a change are encoded haphazardly in the filename.
- Serial edits by different authors are concatenated in the filename, with no indication as to whose edit came first.
- These are just five files in one directory; other revisions are probably scattered around my various hard drives and as email attachments.
This is known as revision hell, and it happens when you don’t use revision control, even if you are working alone. Systems such as git save you from this.
There are (at least) three stages of git enlightenment:
- Maintain a linear history for a file or group of files.
- Use branches effectively to group related changes together, as well as maintain parallel versions.
- Use branches and pull-requests to collaborate effectively.
It took me a long time to pass all three, and I hope this tutorial will help someone get there faster.
A final thing to keep in mind while you’re learning: git is hard. It’s difficult enough to keep all the branching histories straight, but worse, its user interface is notoriously inscrutable and seemingly random. I consider myself a git “power user”, and I still often Google commands for it. I privately maintain a list of “git WTFs”, commands that make no sense at all. I hope to one day turn these into a book.
Now, after reading that, you might wonder, “why would anyone want to learn this?” The answer is that the backbone of git, how it maintains your data and communicates between different copies of your data, is extremely solid and well-thought-out. The UI needs work, yes, but that can always be improved. There are, in fact, many reasonable git “clients”, which make the day-to-day of git nicer. This tutorial, however, is about the hard basics. Understand those, and all other clients will feel deliciously simple.
Tutorial timeline (approximate)
- Installing and setting up git, GitHub, and others (30min)
- Git theory (30min)
- Working with git (1h)
- Working with GitHub (1h)
- Advanced topics discussion (15min)
- Putting it together: submit improvements to this workshop! (45min)
Click on the sections below to get started with git!