36
$\begingroup$

Suppose that coauthors from two or more different institutions are writing a paper in latex, and would like to do better than repeatedly emailing drafts back and forth.

They realize they can open for free a dropbox account, share the password, and synch the version of the paper on their computer with the one on dropbox. If two people are simultaneously editing the same section, however, they'll overwrite each other changes.

They have also heard that version-control systems like SVN and Git have tools to merge concurrent changes, which work reasonably well. The documentation of these products, however, is rather hard to read, and it is more focused on how to undo changes and how to manage different "branches" rather than on the basic needs of coauthors writing a paper.

Is there a simple step-by-step exposition on how to use a version-control system in this setup:

  • central repository
  • local copies
  • "smart" merge
  • no branches

?

Of the standard version-control systems, which one is the easiest to use? (We are talking theoretical computer science professors here.)

Are there even simpler tools that only do synch with smart merge, without version control?

Conversely, do people who use version-control systems to even write a single-authored paper really feel that the unlimited-undo capability is worth the extra complexity?

Improve this question
$\endgroup$
5
  • $\begingroup$ Very interesting question. $\endgroup$
    – Oleksandr Bondarenko
    Jan 30, 2011 at 21:20
  • 1
    $\begingroup$ Indeed. I haven't found anything better than SVN so far, but it's sometimes a bit tedious to get the newcomer to use it properly. I look forward to answers providing user-friendlier solutions. $\endgroup$
    – Anthony Labarre
    Jan 30, 2011 at 22:12
  • 2
    $\begingroup$ I like this question too! @Luca: You may also be interested in Version control for collaboration (with word-level diffs)?. $\endgroup$
    – Sadeq Dousti
    Jan 30, 2011 at 23:07
  • 1
    $\begingroup$ In some branches of CS, it's common to write papers (and slides) as literate source. Tools such as lhs2tex (people.cs.uu.nl/andres/lhs2tex) are useful in this regard. The upshot is that source code examples in the paper are compilable and checked, and results may even be automatically generated. In such cases, a genuine dvcs seems like the only sane thing to do :-) $\endgroup$
    – sclv
    Jan 30, 2011 at 23:17
  • $\begingroup$ btw dropbox has rudimentary version control: you can roll back to a previous version of any file. but merging will have to be manual, which can be a bummer. still, even with svn, i imagine it's still a good idea to pass virtual tokens around? what i've done is split the latex file into a different file for every section and just use dropbox. $\endgroup$
    – Sasho Nikolov
    Jun 4, 2011 at 1:19

8 Answers 8

Reset to default
12
$\begingroup$

First off: If your are interested in real-time collaborative editing, try something like gobby. It lets you literally edit a document at the same time.

As for revision systems, I am only familiar with SVN. This is what you do, after installing subversion, of course:

  1. Get someone to set you up a repository and give you URL, username and password
  2. Go to where you want to have your lokal copy
  3. In a shell (command line?), type: svn co url://to.your/repository (check-out). Now a new folder with the repository's contents appears.

That's all. Now the most basic commands:

  • Whenever you add a new file foo, enter: svn add foo
  • Whenever you want to remove a file, enter: svn rm foo
  • Whenever you have made changes, enter: svn ci (check-in)
  • Whenever you want to get the newest stuff, enter: svn up (update)

There are also commands for moving, copying, branching, resolving conflicts, ... but as long as you do not try funny stuff, you are fine with the above. If anything breaks or seems to, backup your edits, delete the whole folder and checkout the whole thing anew. That's for svn like rebooting for Windows.

Addendum: I see you seem to be concerned about "smart merges". I assume that you refer to have to different versions of a file merged, with the assumption that two people added things in disjoint parts of the paper. As far as I know, svn would treat that as a conflict, and probably rightly so. I don't think that there is a general procedure that ensures you get what you want after two people manipulated the same source. There are graphical svn clients that visualise such conflicts and help you resolving them; they are pretty much diff-viewers were you can choose which version to keep for every conflicting line). It will require work, though.

Improve this answer
$\endgroup$
13
  • 6
    $\begingroup$ Also, you should use ToriseSVN to handle all interaction with SVN graphically; it makes everything a breeze. $\endgroup$
    – Noon Silk
    Jan 30, 2011 at 23:41
  • 3
    $\begingroup$ I'll add to this that rather than setting up your own SVN server, I recommend using a free hosted service like unfuddle.com. It's fairly painless and private. $\endgroup$
    – Anand Kulkarni
    Jan 31, 2011 at 0:00
  • 2
    $\begingroup$ thanks, and thanks to Anand for the suggestion of unfuddle, this was exactly the 1-minute tutorial that I was looking for. I tried setting up a repository on unfuddle, making two local copies on different computers, making inconsitent edits, and checking in, and it does perform the smart merge as Suresh says. (If two users make inconsistent changes, the second one to check in does get an error message; but if the second one updates, and then checks in, the update makes the smart merge locally, and the check-in puts the smart merge in the central repository.) $\endgroup$
    – Luca Trevisan
    Jan 31, 2011 at 1:23
  • 1
    $\begingroup$ about Raphael's off: etherpad.org - another really real-time editing tool. very promising... $\endgroup$
    – Alessandro Cosentino
    Jan 31, 2011 at 4:15
  • 1
    $\begingroup$ I should say that many people prefer git over svn, but I have no experience with it myself. $\endgroup$
    – Raphael
    Jan 31, 2011 at 10:12
12
$\begingroup$

I notice that no one is giving the "small" tutorial for GIT, so I'll try to cover it. GIT is faster and superior to SVN, but maybe it is easier for you to get an SVN account on a server at your university, since SVN is well established. Also may of your collaborators would know how to use it.

Even if you collaborate using SVN you may want to use GIT for your own local versioning (I do!).

First bit of warning: GIT is very powerful and for basic usage is only slightly harder to use than SVN (e.g., one option to be added in the command line; two steps commit for central repository).

Second bit of warning: GIT has the philosophy of considering a set of changes to be atomic (a $\Delta$ as they call it) even if the set spans several files. Also in GIT you have the notion of local repository and central repository. GOOD: You can work offline. BAD: You need two steps commit to a central server.

Basic commands assuming you already have a repository

  • Clone a repository: git clone <url>
  • Update your local repository: git pull <repo> or just git pull if you cloned as above.
  • The pull command really does both git fetch and git merge. The former "fetch" stuff from the central server, and the second apply a merge of your files and the ones of the server.

The merge is automatic as long there are no simultaneous edits on the same parts of some files. If the merge fails you working directory remains in a "merge state", which means that you have to fix the conflicts and then you have to commit the merged copy. If you still have unmanaged conflicts in you files then the commit would fail again, no garbage committed.

  • Add a new file to be committed: git add <file name>.
  • Commit changes to you local repository: git commit -am "<textmessages>" or git commit -a if you want to edit the commit messages.
  • Push the changes in your local repository to the central repository.

Notice that for pushing changes to your central repository you first have to commit to your local repository and the you have to push all the commits (even more than one) to your central repository.

Create a user-local repository

  • Creation of a repository git init in any folder you like.
  • Done!

Create a public-shared repo (also private if you pay cash) with a nice GUI.

Crate as many private/public repository with different groups of users but no GUI.

  • Ask for an SSH account with no password on an accessible machine.
  • Don't worry since authentication is done by SSH keys.
  • Install Gitosis according to this tutorial.
  • Now you can administrate you own git server by editing a single file and committing it to the repository!

Git does not need a central server: any folder in your computer can be used as repository, so you can play with git and make your tests offline. You can initialize one repository and simulate three collaborators in three other folders without sending one bit on the net. This is because any cloned copy of the repository is a full featured repository to which you can commit. This is good if you want to work in a flight between USA, China or Europe.

Improve this answer
$\endgroup$
1
  • 1
    $\begingroup$ Since I wrote my answer above, I have come to prefer Git, too. If you like Github but are hesitant to give your intellectual property to a company (and/or pay for that privilege), check out Gitlab. $\endgroup$
    – Raphael
    Feb 26, 2014 at 6:58
8
$\begingroup$

Google Documents ( https://docs.google.com ) provides great tools for authoring documents together (including real time editing). It stores everything online for you and integrates well with your Gmail account. By default Google Docs does not have LaTeX compatibility, but you can enable it by going here:

http://docs.latexlab.org/

I am not sure how well it works for rollback, but I am sure there is a feature for it. I have heard of some people using Google Wave's LaTeX plug-in to work out preliminary sketches for papers.

Improve this answer
$\endgroup$
3
  • $\begingroup$ Sorry, but that's probably like building the prototype of your new invention in your competitor's lab. I know that Google's tools are popular, presumable because of there ease of use and availability, but I doubt they are very often the best choice. Setting up a decent working environment is not too hard once you have put in a little inital effort. I feel that that should not be too much of a demotivator for people who spend about ten years after school in order to qualify for their job. $\endgroup$
    – Raphael
    Jan 30, 2011 at 23:28
  • 4
    $\begingroup$ I don't compete with Google... so for me it just seems like using the easiest tool available, which seems to be one of the requirements OP asked for. Just because it doesn't run in your command line doesn't necessarily make it a bad tool. If it lacking some functionality you need, then it is an open source project, and you can use your experience to add to it. Further, if you use the development version you can even use your local LaTeX compiler instead of the one on their servers. $\endgroup$
    – Artem Kaznatcheev ♦
    Jan 30, 2011 at 23:38
  • $\begingroup$ Don't get me wrong, I am no CLI-only guy. I greatly enjoy graphical editors, for example (although I dislike WYSIWYG). Fact is, there are alternatives that are not provided by the biggest data miner on earth. I used the term "competitor" since, afaik, Google does some research in computer science, especially machine learning flavors. $\endgroup$
    – Raphael
    Jan 31, 2011 at 10:11
7
$\begingroup$

I make my coauthors learn Mercurial, and I used to make them learn Subversion. If you are a Subversion fan, just read this, it is all true.

No matter what system you use, by far the hardest thing is to get the other person to install the software and start using it. Skype is the perfect solution. Recent versions of Skype allow "desktop sharing" which really helps when you want to lead your coauthor through the installation procedure. And I have used straight desktop sharing combined with Skype to write a paper with my coauthor. It works pretty well.

What is really needed is a "Github for scientists". Something that gives a repository, has version control, collaborative editing, etc. Guess what, there is http://www.scribtex.com/.

Improve this answer
$\endgroup$
2
  • $\begingroup$ I'm using Github right now to write a survey with a collaborator. It's convenient enough and I don't feel the need for online collaborative editing since we're usually working in different sections. $\endgroup$
    – Suresh Venkat
    Aug 27, 2011 at 23:17
  • $\begingroup$ bitbucket would give you the advantages of github with some privacy. I am testing it. $\endgroup$
    – J..y B..y
    Sep 27, 2013 at 14:41
5
$\begingroup$

here is a new collaborative online Latex editor called WriteLatex that looks promising, as a near one-stop shop for many scientific writing needs/requirements.

  • works on mobile
  • has realtime preview
  • easy/private sharing
  • finds latex errors
  • allows add on latex libraries/styles
  • cloud storage

the coauthor John Hammersley posted an announcement in tcs se meta here and he's responsive to feedback (5 more votes on the ad & it will appear on the main site). it looks like it could evolve into a valuable tool for the tcs community over time and maybe the authors will be able to implement some popular features specifically on request.

Improve this answer
$\endgroup$
2
$\begingroup$

What about simple systems, solutions:

It's out of question, but sometimes there are situations where part of group is capable of simple solutions like SVN, while other part of group is capable of distributed version control like GIT. In such situations cooperation is possible:

Improve this answer
$\endgroup$
2
$\begingroup$

I recently discovered sharelatex.com and used it with my collaborator to coauthor a paper. I liked it so much my current plan is to use it for all my projects. Some notable features:

  • Real-time in-browser TeXing (like Google Docs, but made for TeX, syntax-highlighting and all).

  • In-browser compiling and PDF viewing

  • Supports projects with multiple files

  • Has a history feature

  • Syncs with Dropbox (soon to be released publicly, from its current beta status). This way you can offload the saving of backups etc. to Dropbox. Depending on how it's done, this should also let you use sharelatex even if your coauthors don't want to, as long as they are willing to use Dropbox to share files.

  • You can download/upload your project at any time, so you're not stuck using sharelatex if something goes wrong or you change your mind or whatever.

The only downside (but I think it's worth it): although using sharelatex is free, some of its features are not. Notably, to use Dropbox sync (when they release it), or if you want more than 6 coauthors to work on the same sharelatex project, you have to pay \$8/mo. or \$80/year [as of April 2013]. Once they release Dropbox sync though, it seems like a very fair price to me.

[Disclaimer: I have no relationship with sharelatex or its employees other than that I use their product.]

Improve this answer
$\endgroup$
1
  • $\begingroup$ It's open source now! (And, fwiw, there's also writelatex which is similar but can be used for quick fun without registration.) That said, I would not put my intellectual property in a commercial cloud (until it's published). $\endgroup$
    – Raphael
    Feb 26, 2014 at 6:55
-5
$\begingroup$

SVN is the tool developed for this purpose. I would put in the effort to learn it. It is not more complicated than learning to use say the algorithm2e Latex package or one of the pdf slide creator Latex packages.

Having said that, I use CVS instead of SVN. There is better support from the CS admins at our institution (the SVN server is more user managed). Plus, I appreciate that the underlying version files are still there and editable if something goes very-very wrong.

There are 2 drawbacks when compared to SVN. File renames are not as nice, but I can live with that (pick a good name first time). The second problem is that one needs a local CS account to access the repository. Therefore from another institution access is only possible if an account is created first. Of course I do not expect this to be a real problem anywhere; a local department member can probably sponsor that account.

The local access restriction is due to the fact that the admins do not want to support a pserver. (Harder to secure etc.)

Improve this answer
$\endgroup$
1
  • 3
    $\begingroup$ Downvoted because this doesn't really address the question's request for step-by-step help and because most of the advantages and disadvantages listed seem to be localized to the home institution of the answerer. $\endgroup$
    – David Eppstein
    Dec 30, 2012 at 18:33

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.