Background

If you are new to this style of project collaboration, one of the things that you may find challenging is the interface with git. To ease the pain, this page sets out some basic commands & guidelines for working with this project and making sure you have the latest code & that your collaborators have your latest fantastic changes.

Basic commands [with some explanation]

Assuming you are using a Mac when you open a Terminal window, it is generally in your home directory (usually, your user name). So, to navigate to the project directory you need to have some basic unix command skills to get around.

The very basic is [typing in a Terminal window]:

cd Desktop/management_upwelling # Or whatever the project folder name is.

cd stands for change directory. In the case above, the command is saying “change directory to Desktop and the folder management_upwelling”.

Once you are in the project directory, it is pretty easy to work with git.

git add -A # this command is saying “git add all of my changes please”

and then to commit (i.e. save your changes) it is as simple as:

git commit -m 'description of whatever it was that you were doing' # this command is saying “git commit the changes with the message 'description of whatever it was that you were going'”

By convention, we try to provide meaningful descriptions so that in a long trail of project history, we are able to trace back to changes that you made. These are kept in the git version control, which is handy if you need to go back to earlier versions of the code.

Great. You have added your changes, committed them. Now what?

git push origin master # this ‘pushes’ your changes to the github repository

Git will let you know if you are behind in the development of the project, in which you should:

git pull origin master # this is also handy if you haven’t been doing much but you want to see what everyone else collaborating on the project has done.

If you want to have a quick view of the project development:

gitk

Managing conflicts

Sometimes git will identify conflicts between code versions. What it is basically saying is that it cannot decide which is the correct version and is asking you to confirm which is the most up-to-date. It does this by placing weird HEAD>>>>>>>>>> and other gobbledegook around the conflicting sections.

As a general practice, we encourage you to revise these for all .R code and determine which is the correct version. For data files (e.g. *.csv) and other data objects, this can be incredibly tedious, but more often than not, easy to fix.

Be patient. Go through the conflicts and resolve them individually, and then:

git add -A

git commit -m 'resolving conflicts with master' # or whatever the nature of the conflict was.

If things get tricky or git is giving you bizarre error messages

Here we enter into the Dark Art of git.

First & foremost, don’t despair. There is great github documentation and “how-to’s” if you get stuck.

For this project, we encourage using vim as a text editor, which if you get a conflict message in your Terminal window, all you need to do is hit the esc key followed by the : and then q and then you are free!

If you are using emacs or some other text editor, sorry you are on your own (and/or you can help collaborators by describing the work-arounds on this page).

Image credit: https://xkcd.com/1597/