Git version control

Intro

Git is software which helps you to manage changes to your files. It works especially well with plain text files, like code. For a quick Git lookup, this guide is excellent. I strongly recommend working through the Software Carpentry Git course, remembering to change Github for Bitbucket (because we have an academic licence). Jenny Bryan's class on working with RStudio and Git is very good.

This wiki will take you through some usual tasks, like starting a new project, your day-to-day workflow and working with others. If there are other things you would like to see here, please ask or submit an issue.

Note: you can use tab to auto-complete directory and file names.

Starting a new project

Starting a new project could mean two things:

1. You have a totally blank canvas
2. You have an existing project you want to use Git with.

This section will cover each of these.

Totally new project

You've created a new folder and are about to begin a project, what's your next step? First, have a think about folder structure; I like to have folders for data, code (repo) and docs, as a minimum. This blog post has some great ideas on structuring your work.

Depending on how you work and how you structure your project, you will have different options for what you're managing with Git. If you are version controlling your whole project (not ideal with data, spreadsheets or Word-type files), you want your git directory in the main project folder. If you are only version controlling code you can put the git directory in your code/repo folder. The only difference is where you run the git init command.

First we can create a new repository on Bitbucket using the "+" icon on the left-hand menu. If you set the repo owner to sruclees you can assign your new repo to a project, which will help keep us organised. You're then presented with an overview pane, with two options at the bottom: "I have an existing project" and "I'm starting from scratch". The existing project option describes the approach if you have an existing Git project on your local machine and want to connect it to Bitbucket. The from scratch option helps you if you do not have a Git project, but have an empty folder. Follow the appropriate choice and you'll be set. If you have an existing project which doesn't use Git, then the next section is for you.

Migrating an existing project to Bitbucket

Do not worry about there being a right time to start using Bitbucket, it's designed to help you develop!

This section will help if you have an existing project, which isn't using Git.

First, you can create a remote mirror of your project in Bitbucket using the "+" icon on the left-hand menu. If you set the repo owner to sruclees you can assign your new repo to a project, which will help keep us organised. You're then presented with an overview pane, with two options at the bottom: "I have an existing project" and "I'm starting from scratch". Nearly ignore these, and we'll use a custom set below:

# change directory (navigate) to the one you want to version control
cd Documents/project

# Initialise it for use with Git
git init

# Connect it to Bitbucket (get the link from the existing project help)
git remote add origin https://...

# Copy your existing work to Bitbucket
git add *
git commit -m "initial commit"
git push -u origin master

You now have a version controlled folder on your computer and a mirror of it at Bitbucket. Have a read of the subsequent sections for how to work with these.

Your day to day workflow

If you are working alone on a project, from a single computer, Git is really straightforward. Your Git project exists on your local machine (using git init) and can also be mirrored on Bitbucket (or Github, Gitlab, etc.). See the previous section for more details.

There are three commands you need, and the following describes what they do:

• git add takes a snapshot of your file(s)
• git commit copies that snapshot into your local file history
• git push copies that local file history to your remote (Bitbucket).

So to use these, you must first navigate to your repository folder with cd, and can then use them at will. For example, you're adding a feature/function to a script and finish it, at this point you run git add, use git commit to record it with a message and finally git push to sync it with your remote repository. These are shown below:

git add file1.txt file2.R

git commit -m "your succinct description of change"

git push origin master

As you're working in bash (the terminal language), you can use wildcards. So git add * adds all files in that directory, git add *.R adds all files with an R extension. If you want Git to ignore certain files (like login files for a database), you can do this with a .gitignore file. Please read this lesson from Software Carpentry for detail.

Working across multiple computers presents an extra step. When you complete work on one machine make sure you have pushed any changes to Bitbucket. You can then use git pull origin master to bring those changes to your other computer.

These are the basic commands, you will likely need others and some of these are covered in the following sections.

Working with others

This section describes how to work with others. It is split into two parts, with the first covering general interaction and the second explaining how to solve conflicts.

Basic collaboration

When you want to collaborate in Bitbucket, your team need access to the repository. By default, any new repository you create in the SRUC-LEES team will be visible to all within the LEES team (you can change this in settings), but they will not have write permission. To grant them write permission to your repository, open your repository overview page (for example), click the 'Send invitation' button, type their name and change their access permission.

They can now clone the repository to their local machine with the https URL at the top of the page. Their command will look something like this:

git clone https://mikerspencer@bitbucket.org/sruclees/help.git

The above creates a directory called help and stores the files in there. If you keep your code in a directory called "repo", or want to clone into a specific folder, you can do this by name or using a "." (. means current directory), e.g.

git clone https://mikerspencer@bitbucket.org/sruclees/help.git .

Your collaborator now has a complete copy of your project history on their machine. You both now need to push work from your local machines to the remote repository (Bitbucket), and periodically (e.g. each morning) pull changes that any collaborators may have made. This push/pull workflow is the same one you use if you work across multiple computers. At some point, you or your collaborator will push a change on the same line. In Git this is called a conflict, and the next section describes how you solve it. Otherwise, Git will merge together different versions for you.

Mistakes

If you commit files that shouldn't be there, you'll need to remove them from your history. Do this with BFG repo-cleaner.

This work is licensed under a Creative Commons Attribution 4.0 International License.