A short introduction to Git and GitHub
The minimum workflow for keeping file revisions under control
When working on a script (or manuscript), version control enables the possibility to restore the last working version. Software development, where multiple collaborators are editing different pieces of the same package, pushed the needs for version control systems to the highest standards (the most common example is the Linux kernel, an impressive open source collaborative effort that… lead to the development of Git itself).
If you use Google Documents, you are already familiar with a user friendly implementation of version control, as you can revert a set of no longer needed changes.
Git is a powerful (that means also: complex and very difficult to use) version control system. What made Git very popular across non software developers is GitHub, a web-based hosting service for version control using Git behind the scenes. GitHub became so popular among life scientists (not only bioinformaticians) that has gained a place in Nature’s commentaries.
Easier done that said
This article aims to describe how to start using a git repository using GitHub.
Usually when introducing a new software you start sharing its philosophy and core concepts, and finally put examples. The Git workflow is potentially complex, but several layers of complexity are only necessary when more people are collaborating so this introductory tutorial will focus on the single user that wants to keep track of changes example, and it will be GitHub based although the very same commands will apply with alternative Git providers.
Sign up to GitHub
If you don’t have a GitHub account, sign up (it’s free). You can then create a new repository using the “+” menu.
Then you can choose a name for your repository, that can be thought like a project directory.
Remember that free GitHub repositories will be public: all the files you store there will be openly available. GitHub is perfect for sharing code with the community (and to practice with Git as well). Once you learn how to use Git you can use alternative providers for private repositories, like BitBucket.
It’s very useful to have GitHub putting a first file int he repository, and you can do so by clicking “Initialize this repository with a README” before submitting the form.
Accessing your repositories: locations
All your repositories are available at https://github.com/yourusername/ and each specific repository has a webpage like:
https://github.com/yourusername/repository-nameWhile the “git” file to interact with the repository from the command
https://github.com/yourusername/repository-name.gitA minimal Git cycle from the command line
Cloning a repository
This is probably something most users are familiar with: cloning a repository means getting a local copy of it. When we simply want to download a software package someone is versioning on GitHub, we can clone it.
Remembering how to access our repository path (see above paragraph), the command is (replace telatin with your username, and git-demo with your repository name):
git clone https://github.com/telatin/git-demo.gitThis will create a “git-demo” directory in our current path, with the full content of the repository (i.e. the readme file!).
Editing and adding files
The magic of the repository is stored in a hidden “.git” subdirectory, while everything else is working as any other directory.
We can create a new file and edit the existing Readme, for example:
Commit: putting a flag on the changes done
We can keep editing and adding files, but when we need to say “let’s fix this point”, it’s the time for a commit. This will create a landmark in our repository, we will be able to roll back to this current version in the future, fore example.
The commit step is done by adding the files we want to commit (some times we just want to save the state of some files), and then performing the commit step itself. It’s mandatory to add a comment to the commit, with the -m parameter.
Both commands will print some output highlighting the chages git detected from the previous release.
Upload your changes to the GitHub repository
Our local repository, after the commit, contains some changes that are not yet available in the remote one. To upload these changes simply type:
git pushYou’ll be asked for your username and passwords (everyone can clone an open repository, but only the owner can upload files or accept changes proposed by others).
Again, git will summarize the changes applied to the remote repository.
Where are all those version, then?
When you clone a repository, you are automatically getting all the releases, but the files you see are at their latest version.
Graphically you can see all the versions of a GitHub repository going to the “commits” page (e.g. https://github.com/telatin/git-demo/commits/), or by clicking the commits link from your repository home page.
Each commit has a unique identifier, that you can get from the commits page:
You can find the unique identifiers also from the command line, typing the following command:
git logTo restore a specific commit you’ll need the unique id¹, then:
git checkout UNIQUE_IDThere’s more than this
A single user scenario as depicted in this primer is the minimum Git you can think of to get started. Even for single users, though, there are interesting features available on the shelf, like the possibility to create branches.
Suppose you have a script that is working well for a task but you want to update it. You start editing it and its going to be experimental and sometimes not even functional for a while. The simplest thing you can do is keeping a working copy somewhere (or checkout the last stable commit, if you prefer), but should you need to make small fixes to the stable version? See for example “What a branch is” to see that Git can help us also with this scenario.
Further readings
Updated on 2019: GitHub now has an excellend and incredibly easy to follow series of tutorials that will drive you to branching, improving your documentation with markdown and much more!
Notes
¹ This whole tutorial oversimplifies every single step. See for example this question.
