Workflow Collaboration

How to collaboratively write a document

First of all you need to get your own free GitHub account. If you like to invite other researchers for collaboration on your document, you have to create an organization for your account which can be achieved using your account settings you find in the top right corner on the GitHub page. In the settings you find the organizations option where you can create a new one. An organization allows you to manage repositories and to invite and manage other users with a GitHub account in groups for a project.

Fork for an online copy

If you are logged in you can visit the Open-Science paper repository to copy the project by clicking on the fork button in the top right corner. This gives you a copy of the repository under your account which can be accessed via a link looking like the one shown in the box below. You find the right link address to use on the top of your forked projects GitHub page. Now you can use the link to clone into your online copy of the document.

git@github.com:your_login/Open-Science-Paper.git

Clone for a local copy

First of all you should create a folder on your pc where you like to have your copy inside. I call it here for example "paper_writing_folder". The further steps of the description assume you to have a working installation of Git on your machine. The steps describe the process of getting your remote repository to your local machine by using the command line of your system. If you use Windows you will have to adopt the second and third step below to the right file path conventions and commands on windows. Note, that you have to replace the "git@..." path in step three with the right path of your forked online repository.

• Open a terminal

• Create a new folder

mkdir /path/to/your/paper_writing_folder/

• Change directory your paper_writing_folder

cd /path/to/your/paper_writing_folder/

• Clone for a local copy

git clone git@github.com:your_login/Open-Science-Paper.git

After that procedure you will find a copy of the repository in your chosen folder. Your collaborators will have to do the same on their machines of course.

Work on your local copy

Before you start to write anything, you should create a new branch for you to work on because it is not practical to work on the master branch. You can checkout which branches are already there and which one is activated by issuing the command git branch inside of your Open-Science-Paper repository folder. You can create and activate a new branch in one step with the command shown in the third of the steps below, where I use the branch name "author_cpfaff". If there are already branches in the repository and you only want to change between them you can use git checkout branch_name.

• Open a terminal

• Change to your repository

cd /path/to/your/paper_writing_folder/Open-Science-Paper

• Create and checkout a new branch

git checkout -b author_cpfaff

Now you can start to write the document with your preferred LaTeX Editor. I highly recommend Vim as editor for all text editing related tasks. It is a powerful editor with several modes which is completely controllable via keyboard. For all those who are more used to have a menu for choosing options there is also a graphical version of Vim called GVim which you can give a try. If you do not like Vim at all there are many other editors you can chose from. For an overview of editors you can read on here

If you add files to the folder structure of the document you also need to add them to the Git repository. If not added they will be listed as untracked files when you use the git status command which helps you to get an overview about the changes in your repository. You can add files by issuing the command in the box below. It is also allowed to have wild card characters so you can add multiple files to the git repository.

git add "your file/folder name here"

When you proceed with your document you should use the git commit command regularly. This commits your changes from the git index to your repository along with a log message (shown below). Here you can find an blog post about good practices in writing commit messages.

git commit -m "Your commit message"

If you like you can also push your branch to the remote repository by the command git push origin your_branchname. This allows other authors to see the changes on your branch and they can check them out if they like.

Collaboration workflow

Every collaborating author should have his own branch he is working on (git checkout -b author_yourname). You and every coauthor needs to update his own branch with the master branch every now and then by merging it. This is essential because otherwise the master and your working branch get to distant which can cause merge problems later on. The following commands can be issued to achieve this assuming you are on your working branch:

• Check out the master branch

git checkout master

• Pull remote changes and merge with local master

git pull master

• Check out your author branch again

git checkout your_author_branch

• Merge the master into your branch

git merge master

If you have finished writing a chapter or just a section, you may want to make those changes available to the other authors. For that you need to merge your working branch into the master branch and push it afterwards to the remote repository. To do this you should start with step 1 from the list above and then go on with the following:

• Check out the master branch

git checkout master

• Merge your author branch into master

git rebase your_author_branch

• Push the merged master to remote master

git push

• Change back to your author branch for working

git checkout your_author_branch

Especially when you write a text document collaboratively this second set of commands should also repeated frequently because it makes your text available to your collaborators. If all authors write on all files of the document the merge process can cause conflicts which then have to be resolved manually. This means to choose hunks of text from passages in differing files to keep them in one file as final version. Any three way merging tool you like can help you to do this relatively easy.

Just as a side note: Before merging your branch into the master and push it to the remote repository you should check if the document compiles properly to a PDF file. This will save other authors plenty of time because they will not have to debug the LaTeX errors you might have introduced somewhere in the document.