23

I will soon write a new article with new collaborators (my first paper with other people, I'm in math). For some context, I know one of them well, but I've never met the others in person.

I use Git to manage all my papers. I'm wondering if I should suggest the use of Git to them? If so, how much should I press the issue, what should I say when suggesting it?

I can use it alone and apply their changes manually, but it would be infinitely easier if everyone just used a VCS -- and not just for my own personal comfort, because Git (or any VCS) does make writing the paper easier, IMO.

The main issue is Git's learning curve. I can offer to make everything as simple as possible (set up the repository myself, help out with technical issues they might have, direct them to tutorials), but academics are busy people, and they might not want to learn a whole new system for just one paper (even though I believe that were I they, I would then use Git for everything...).


I've gotten a lot of answers that don't apply at all to my situations, so to clarify: I'm in (pure) mathematics, where all manuscripts are written in LaTeX. So

  1. version control using, e.g., Git, is appropriate, since LaTeX is a plain text format (and not some WYSIWYG thing), and

  2. it requires a little bit of technical know-how already, so it's IMO safe to assume that other collaborators are not completely tech-illiterate.

  • 4
    Maybe Git is not the right tool for this job. In my experience, writing a paper does not require the same kind of sophisticated tool support as working with many software branches in parallel does. Therefore, you could as well suggest SVN, which is less powerful than Git, but also much easier to learn. – lighthouse keeper Feb 25 '17 at 21:54
  • 8
    Based on my own experience — Oh, god, yes. I'd rather eat glass than go back to email or Dropbox. – JeffE Feb 26 '17 at 4:17
  • 6
    @BrianBorchers For a regular git user, using version control for a paper draft requires less effort than the alternatives. – Federico Poloni Feb 26 '17 at 8:32
  • 3
    @FedericoPoloni In my experience, most of the people who are not developers are not regular git users and would very hardly undertake the effort to learn it. – Massimo Ortolano Feb 26 '17 at 8:34
  • 4
    @MassimoOrtolano Are you a Latex user? I feel that most of the arguments you'd use to convince a collaborator to use Latex would work also for version control. "Sure, it has a steep learning curve, but..." – Federico Poloni Feb 26 '17 at 8:41

14 Answers 14

14

I recently was on the other side of this - I learned git to work with a collaborator on a paper (written in LaTeX). While git is fun, and it's good I learned it, I am not convinced the net time savings were that large, and I found the first steps very frustrating. I would not generally recommend you ask collaborators to learn git - but only ask if they already know it. For papers, maybe things like overleaf/etc might be better?

Giant time losses:

  • Trying to figure out how to properly discard changes I made but didn't want to merge, when stash didn't seem to work right...
  • Accidentally doing bad commits, etc, and trying to figure out how to move backwards.

This would obviously get easier the more you worked with it, but I found that in the first few months, there was some problem like that, and I ended up deleting everything and re-downloading - this xkcd sounds about right: https://xkcd.com/1597/

Upside:

  • Fewer ugly email chains
  • Made integrating small edits late in the process a lot easier - I was more willing to make tiny wording changes when it didn't require someone else to integrate it into the final draft, and that I could do it on my time.
  • 2
    The main purpose of tools like Git/Mercurial/SVN is version control. If somebody modifies your awesome paragraph in a way that you don't like, you want to know who did it, when they did it, how to revert back etc. This could be done easily with version control tool, and not overleaf I guess. – qsp Feb 26 '17 at 3:55
  • 1
    Your problems: discard changes, bad commits were asked several times in stackoverflow. This is trivial if you use git right. – qsp Feb 26 '17 at 3:56
  • 11
    "This is trivial if you use git right" "Check stack overflow." Of course! But in my experience, it is not trivial to learn to use git right, and if every time you make an error, you need 30 minutes on SO to debug it... not great. – AJK Feb 26 '17 at 4:32
  • 11
    In my experience as a new git user (but an experienced coder), I didn't start seeing benefits until 1 yr+ into a collaboratively written paper. I suspect the learning curve is going to be worse for, e.g. a senior faculty member who has less time to spend debugging! – AJK Feb 26 '17 at 4:34
  • The problem with such an evaluation is - git (or SVN) prevents a lot of potential time loss that you don't see when you use it. If you have a handcrafted exchange system for word docs or send latex files around you will loose quite some time if at some point something with the versions gets mixed up and you need to figure out how to undo part of the changes - or which is the version you want. That being said, for small projects Google Doc can do an awesome job too. – Frank Hopkins Feb 1 '18 at 15:06
10

Of course you can ask if all are happy with git but as soon as anybody is unfamiliar with it, do not push it. Then go with anything everyone finds OK (may it be svn, Dropbox, or even be sequential processing via Email - I had all of these). In my experience this will make the process much smoother (in other words: Your headache will be smaller this way than it would when there would be somebody on the team who can't work with git - but note that "smaller" may still be huge).

  • 1
    Disagree. If you find a tool more useful, push for it. Just don't expect to win. – JeffE Feb 26 '17 at 4:16
  • 1
    Unfortunately, anything that involves manually copying files around that constitute different versions of the same document creates a whole set of headaches on its own. – O. R. Mapper Feb 27 '17 at 14:55
  • There are tricks of using Dropbox with git without messing up your repository. So, if one partner uses git, the other one can use Dropbox and they both live happily after. Hint: the Dropbox folder commits to an external repository, and the git is not synchronised. – Captain Emacs Feb 28 '17 at 10:38
  • 1
    If you manage to push your tool through this time, chances are higher you have no headache pushing for it next time ... consider it a long term investment. – Frank Hopkins Feb 1 '18 at 15:07
9

Many people have already answered with good points. Let me add some insights from my collaborations where other co-authors were sometimes (convinced to) using Git, but other times not.

My advice is to explain to your co-authors the benefits of using Git and suggest them to use it, and offer help to setup things to minimize their effort and learning curve. However, don't insist on it if they don't want to.

I've done this once with a paper co-authored with a fellow postdoc, and this worked really well: I first suggested to him some graphical interfaces for using Git, but he actually quickly preferred switching to the command line tools. It was helpful that we were sharing an office, so I could easily help him, he picked up on Git quickly and things went smoothly. Since then he's been using Git for his papers too.

On the other hand, if your collaborators cannot be convinced, Git can still be helpful for yourself by keeping the history of your own modifications, and merging in their contributions via branching. This means that you can (more) easily offer to resolve conflicts due to simultaneous editing of the document. That way, your co-authors may see some benefits of using Git, even though they don't have to deal with it at all. I'm using this setup for some other collaborations, where either we share the paper back and forth by email, or it resides in Dropbox. In this case I make sure that in Git I strip off any version numbering in the paper's filename, to make difference tracking easier.

Finally, various online services such as Overleaf (or others already suggested) allow collaborative editing and at the same time offer a Git (or other VCS) interface. I'm using this setup in another paper I'm writing where one co-author also uses Git and a third does not.

  • If I may ask, how did you find the Overleaf git interface? Are the commit points and messages reasonably sane? Is it easier to integrate with "normal" git usage? – Federico Poloni Feb 27 '17 at 19:26
  • My co-author pointed it out, see overleaf.com/blog/… Yes, it's exposed as a normal Git repo. We have no relevant "commits" from edits on overleaf yet, so I don't know how that would look (the user does show as "Anonymous" at least). From git point of view the only restriction so far seems that the main file is named main.tex, but I could e.g. add extra image files without problems. – Jaap Eldering Feb 28 '17 at 3:37
8

Git only works if your collaborators are actually willing to write plain text instead of WYSIWYG. In the biomedical sciences the use of MS Word is pervasive and people tend to love their tools just as much as we love using Git and $EDITOR.

To answer your question, you first need to know what your starting point is. Do you only have to convice them to use Git or do you also need to convince them to use plain text?

The idea behind plain text is simple, but still, many people find it hard to grasp. So do not underestimate the necessary education effort. Once people appreciate the advantages of plaintext, they might also have an easier time understanding the benefits and usage of Git.

And then there also other solutions like Authorea and Overleaf that other people already mentioned. If your main goal is to avoid sending manuscript drafts via e-mail, this might be a much easier solution that also works for less technical people.

  • +1 for this. Git is only really useful if the primary form the manuscript will take is in plain text. – Fomite Feb 28 '17 at 3:19
  • 6
    I'm in mathematics and we will have to write the paper in LaTeX anyway. Git works perfectly fine for that. – user69964 Feb 28 '17 at 17:42
4

My experience suggests that few people are interested in using version control in general, and you risk reducing the number of people further by insisting on a harder to use system like Git. Even if you get your collaborators to use Git, the results might not be pretty. I'd recommend something simpler like SVN, which is probably still too complicated for most people. As others have recommended, Google Docs and similar software would be even easier.

More details from a particular case: Several years ago I took a class with several group projects including code and short reports. Using version control made sense, especially given that everyone in my group was a programmer (the class was not nominally related to programming). One member insisted on using Git, with mixed results. Git is powerful, but it's not easy for newbies. I got tired of re-adding lines of code and text because one member of the group didn't know how to properly merge. I doubt this issue would have happened with SVN because the process is much more straightforward.

  • I'm not certain that a class project is really relevant experience for writing a scientific paper. But thanks. – user69964 Feb 28 '17 at 17:43
  • 1
    I'd be interested in hearing why you don't think the class project case is relevant. I think all of the salient features are present, just in a shorter time frame. In the end, you submit single versions of papers (or reports in the class), not multiple. I don't see the benefit of Git's branching workflow over SVN's in either case. Just seems like more trouble for no gain. Version control over Google Docs or something else, I can see the benefit of, though. – Ben Trettel Mar 2 '17 at 19:10
4

You can try integration of git with Authorea. They are based on git but have a Google Docs interface. Thus, based on your preferred workflow you can achieve a push-pull workflow through git or a real-time collaborative environment à la Google docs.

A new version control system for writing research papers

4

Git is an efficient tool for collaboration and version control if you work with others who know it. Given the steep learning curve, it may not be efficient at all if your collaborators don't know Git yet.

In particular if this is a one-off collaboration, you may not be able to recuperate the time that you have to invest in troubleshooting and teaching your collaborators how git works.

Only push someone to use your preferred tool if you are prepared to provide support.

1

It may be better to approach this differently: you may want to ask them what they plan to use for version control. If they are not sure, you could suggest Git. But my guess is that you will face significant reluctance since the learning curve for Git is steep and your colleagues might not want to learn if they feel that it's not the best use of their time.

1

I'm not sure what the advantage to using Git for the entire workflow is and it can put a burden on a collaborators who are not as keen to learn it. My group does very heavy interdisciplinary work and generally the workflow is as follows:

  1. The manuscript is written collaboratively in Google Docs which has revision history.
  2. Citations are managed using citation managers such as Zotero.
  3. Included items such as figures are kept in the same directory as the Google Doc.
  4. Once everyone is happy with the manuscript, it is typeset in LaTeX to be submitted for peer review.

Since the computing skills in the group range from "comfortable using office productivity tools" to "advanced software engineer" this workflow seems to be the best in terms of overall productivity.

0

When you have a substantial publications list, you can start to push about something like this. But not at this stage.

You can put the versions in Git yourself, and give your collaborators access, and you can offer to provide guidance in case they are interested in uploading a version themselves.

  • 7
    I strongly disagree with the sentiment that you must wait until you "have a substantial publication list" before pushing for a collaboration tool. (Note that "pushing for" is not synonymous with "insisting on" or "holding your breath until you get".) – JeffE Feb 26 '17 at 4:16
  • 2
    @JeffE - Can you clarify, after suggesting it once, if the collaborator doesn't seem interested, how many times would you be comfortable repeating the suggestion -- imagining yourself at the OP's stage in his academic career? – aparente001 Feb 26 '17 at 5:08
  • "I've set up a git repository at [address]. If you haven't used git before, here is the minimal list of commands you need to remember: [pull, add, push, commit]. If you prefer to use a graphical interface, I recommend [XXX]; please let me know if you'd like my help setting it up on your machine." – JeffE Feb 26 '17 at 21:30
  • 1
    @JeffE - The only difference I can see is that I said "offer to provide guidance," and you went ahead and provided guidance. Other than that I don't see any practical difference. I said, "give your collaborators access." I advised against pushing. I don't see any pushing in your proposal. Unless you're imagining repeating the message. Pushier still would be to raise the emotional volume on the second or third iteration. But you apparently aren't proposing to do that. // Why don't you post an answer? – aparente001 Feb 27 '17 at 7:52
0

Unless they are software developers, then don't think that they'll have any clue what a git is and maybe not even what a command line is.
Something like Office 365, Google docs or a wiki would be much simpler. Not as powerful, but much simpler.
Simple and done beats powerful anyday.

  • We're going to use LaTeX so your suggestions are not really on-point. – user69964 Feb 28 '17 at 17:40
  • Well, that changes things. The OP didn't specify this. – MikeP Mar 1 '17 at 20:52
0

I would suggest to use some syncing application like Dropbox, Seafile or Owncloud. Many universities host an own owncloud belonging to the sciebo project.

This provides you with

  • sychronization
  • History and the possiblity to revert to an older version
  • Diff to older versions
  • Overview who worked in between and which paragraphs were changed by them

If you want to use version control it would be easier to use a linear system like svn to avoid explaining people how to merge diverged histories, which is really out of scope for writing a paper. If you prefer git you can use git-svn to use the svn with git.

-1

You should tell your collaborators to use SourceTrees, and git will become a piece of cake. No need to learn anything.

It is also good for Mercurial.

Good luck with your paper :)

-1

In my opinion, the learning curve with Git is worth the investment. It allows multiple collaborators and provides versioning. Also, you don't need to learn all of Git to take advantage of its features. Even basic commands and a simple workflow will save time in the long run. Also, Git is cloud-based with a host like GitHub or Bitbucket (just make sure you create a private repo). One consideration is the type of files you are versioning. LaTeX works well, because it's in text format (like source code). So you can easily diff with previous versions, view raw files in GitHub, etc. A Word document doesn't work as well in Git.

  • This does not really answer the question, as the social issues are a significant factor which is completely unaddressed here. – Tommi Brander Feb 2 '18 at 12:35

protected by Dirk Feb 27 '17 at 23:56

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

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