Go to:
In the research world, often one has to collaborate with some people to write documents: articles, reviews, proceedings, ...
For the largest part of the community, Latex is the preferred language for writing scientific documents. A common practice is to share a Dropbox folder containing the draft, so that it can be accessed by all the collaborators for reading, but there is the problem that it's impossible to write at the same time, because the system takes only the most recent version of each file and the modification made by some of the users may be lost.
One solution is to split the draft in several separate files, so that everyone can edit a different file. The files are then merged into the final document.
This is not always possible, for different reasons, and the limits of the Dropbox system appear.
The problem of collaborative and simultaneous writing of a document inspired a lot of services and softwares that allow to solve the problem.
For writing Latex documents, one among the different possibilities is Overleaf, formerly known as WriteLatex. It is a website where people can create and share projects, that can be edited through the online interface. If the users are smart enough to avoid working on the same sentence or words, thing that would be quite unpractical, the document can be easily modified at the same time in different browsers and the compiled PDF is shown in real time on the screen.
This is what one can obtain through the online web interface, but there is more.
Since January 2015, Overleaf offers the possibility to have a git repository connected to each project, that can be edited offline and then pushed to Overleaf.
The repository link can be retrieved in the Project page. For those that are used to version control systems, the following commands will be very familiar. For the others, I wrote a short tutorial here.
Once you have created your project and have obtained the corresponding git link
(it will be something like https://git.overleaf.com/1234567abcdef),
this is what you have to do.
Firstly, the repository must be cloned in an empty folder in your computer.
Create an empty folder, cd to it and use:
git clone https://git.overleaf.com/1234567abcdef
Now you have a copy of the project files in your local folder. You can edit them, add new files, compile and do whatever else you want, without worrying about what your collaborators are doing. Merging the different versions of each file will be easy.
After you did all you changes, you have to commit them.
A commit tracks all the modifications that you did, file by file and line by line,
and saves only the differences with respect to the previous version.
List all the changes since last commit with git status
and commit them using the command
git commit -a.
You will be asked to write a message that is used to quickly understand what you did in this commit.
Modifications done through the online interface are stored in commits accompained by the "Update on Overleaf." message,
but it is preferable to be more explicative when committing locally,
in order to help to keep track of what each collaborator did.
When you are done with the offline version, you must push the local data to the online version.
This may be extremely easy or may require some time, depending on what happened to the online version while you were working offline.
You can update your (already existing) local repository using
git pull
pull fetches the data on the remote repository and updates what you have offline:
it is better to do a pull before starting to edit.
The opposite, updating the remote with the local data, is done using
git push
push will update the online version,
and people working on the project through the web interface will see your changes.
The push command, however, is not always allowed.
If the remote version changed while you were editing the local version you will receive an error message and
you have to do some further steps to merge the two versions.
Firstly you have to pull the remote version.
The merge of the two versions will start after the data will be fetched by pull.
If it doesn't, you can merge manually the remote branch (called "origin/master") to the local branch:
git merge origin/master
Possibly, the merge will be automatic and the modifications will be joined without your intervention. If there are modifications involving the same line or portion of lines in both the local and remote versions, you may be required to solve the conflicts in order to complete the merge. This is done using some specific tool, with
git mergetool
Once the conflicts have been solved and the merge has been completed,
you can finally push the local to the remote repository, so that everybody will see your changes.
Since git works saving only the modifications of each file, it is very convenient to write your Latex document using only short lines. Latex does not care the presence of "newline" characters, so you can write any sentence into several short lines. This allows you to find easily the modifications when solving conflicts between different commits: git, as most of the tools like diff, shows the modifications comparing the lines. Think this: if one single character in a very long line was changed, very likely you must read the entire line to find what it happened. If the line is short, it will be much easier! This is a good practice even when not dealing with Overleaf.
Another good idea would be to avoid modifying the empty lines and spaces in the parts of the document already present, since git considers any variation in the files. This means that any additional space or newline must be committed and it may just increase the things to be checked if one wants to see all the previous modifications.