Version Control at PRIF

Introduction

Version control is a general term for a category of software and working practices used to record, track and share changes to files in all kinds of industries.

For projects with fewer collaborators and shorter timetables (like a journal article), this can often be achieved with general productivity tools like Word, Dropbox, or Google Drive. But for projects involving dozens or hundreds of people, thousands of files, and many thousands of cumulative changes (such as our eLearning project, your phone's operating system, or Facebook), a dedicated version control system (VCS) is needed.

Working with a VCS generally looks like this:

• You start with a folder containing all your project files (this is called a repository or repo).
• You make changes to those files as you normally would.
• You select some or all of your changes (this is called staging)
• You commit your staged changes, along with a written description, to your project's permanent history.
• When you work on a team, you synchronise your repo with a copy on a shared server (this is called pushing), so your colleagues can in turn download (pull) your changes and continue working with them. Pushing may also trigger automated workflows to check your work, send notifications, or (in our case) publish them to the web.

PRIF's Version Control Setup

There are many open-source and commercial tools that enable some or all of the processes outlined above. At PRIF, we use the following:

• git is our VCS
• Github is our shared remote (it also hosts our issue tracking, documentation, automates some of our work, and does a bunch of other stuff). You should make your own Github account, which we'll add to our organisation so you can access our code.

We use the git command line interface (git-cli) by default (meaning our documentation and tutorials are based on git-cli), but it's not a requirement. There are many other ways to use git, including free and paid desktop apps, built-in features in VS Code and other editors, and the Github web interface. Any of those methods will work fine for our purposes.

Using Git and Github

• Open the command line and use cd and ls to navigate to your projects directory. (If you've never used the command line, I've written a few words about it here)
• Use cd and ls to navigate to the folder where keep your work files
• Run git clone <URL> to download a copy of your project's repo (replace <URL> with your repo's URL). You can try out this step with our demo repo at https://github.com/Peace-Research-Institute-Frankfurt/git-tutorial.git. This will create a new folder named after your project's repository. You only have to do this once, when you first start working on a project.
• Use cd to navigate into the newly-created folder
• Use git pull to sync your repo with the remote. If you just cloned the repo you can skip this step, otherwise you should always do it before making changes to the repo.
• Make your changes
• Run git add to stage some or all of your changes. Use git add --all to add all changes you made to the repository
• Run git status to view a list of your staged changes and make sure they're what you expected
• Run git commit -m "<your message>" to commit your staged changes. Replace <your message> with a short, plain-English statement describing your changes.
• Run git push to sync your repo with the remote.

If you'd to try this in a safe environment, you can either create a new repository in your personal Github account, or use our tutorial repo.

Common Errors

• Error: Updates were rejected because the tip of your current branch is behind... when trying to push: This means someone else has made changes to the remote while you were working. Run git pull to incorporate the remote changes before pushing again.
• Error: Please tell me who you are... when trying to commit: This means you haven't set an identity to which your commits should be attributed. You can fix this by running git config --global user.name "<your name>" and git config --global user.email "<your email>". You should use the same email you used to sign up to Github. Also see this guide.

Further Reading

• For a comprehensive treatment of git and version control generally, refer to Pro Git (Chacon/Straub, 2014).
• If you'd like a more approachable text, Git for Humans (Demaree, 2016) is a good one.
• For more on the command line, see Working the Command Line (Sharp, 2016).