<p>I've used git to collaborate on some documents written in latex. You'll have to adhere to some rules:</p>

<ul>
<li>Start each sentence on a new line, latex ignores these newlines as long as there is no blank line</li>
<li>Use the same configuration for formatting (tab/spaces/max text width)</li>
<li>For best results, create a .gitattributes file in your repository and add the line <code>*.tex    diff=tex</code>. This makes diff aware of the tex syntax and leads to more meaningful output.</li>
</ul>

<p>You can then use <code>git diff --color-words</code> and <code>gitk --color-words</code> to see word differences (also see this article <a href="http://idnotfound.wordpress.com/2009/05/09/word-by-word-diffs-in-git/" rel="nofollow">Word-by-word diffs in Git</a> on how to configure git to always use word-diff algorithm for displaying the git diff/git log).</p>

<p>To reduce the manual merges, I can recommend using separate files for sections and subsections (depending on the size of your document).</p>

CC BY-SA 2.5
2010-11-14T19:32:17.357Z
For people hesitant to work this way, you can use TortoiseGit if they don't like the git command line. If it is about the each sentence on a new line part, well as long as there is no maximum text width forced, this isn't that important. (I have worked on some projects without that rule)
Davy Landman
CC BY-SA 2.5
2010-11-14T18:48:40.657Z
I'll consider doing this for my own documents, it seems to be an easy way to achieve most of my aims.  But not everyone is keen to work this way...
András Salamon
CC BY-SA 3.0
2013-02-19T10:59:36.047Z
On the whole, I agree that git is a good choice. But why can separate files for (sub)sections reduce the number of manual merges? I also wonder how starting each sentence on a new line helps (sometimes sentences mix in the process of editing).
dd1
CC BY-SA 3.0
2013-02-20T10:04:53.660Z
regarding the separating files: at that time, I did not understand the exact details of git merging, so that is actually unneeded, but still advisable for other reasons. The sentence on a new line is very important, since most tools around git always show line changes, if you then use another strategy, say let the editor do linebreaks, every time someone changes 1 word in a paragraph, you will have to hunt were it happend, and in case of automatic merging: no way.
Davy Landman
CC BY-SA 3.0
2010-11-14T13:01:57.867Z
2013-02-19T03:07:11.363Z
2013-02-19T03:07:11.363Z
Davy Landman
<p>I suggest taking a look at:</p>

<p><a href="http://en.wikibooks.org/wiki/LaTeX/Collaborative_Writing_of_LaTeX_Documents" rel="nofollow">LaTeX/Collaborative Writing of LaTeX Documents</a>,</p>

<p>and the related paper:</p>

<p><a href="http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.118.4587&amp;rep=rep1&amp;type=pdf" rel="nofollow">Tools for Collaborative Writing of Scientific LaTeX Documents</a>.</p>

CC BY-SA 2.5
2010-11-13T19:03:05.180Z
Unfortunately the "best practices" in these documents are precisely the kinds of things one cannot force on collaborators.
András Salamon
CC BY-SA 2.5
2010-11-13T04:18:42.197Z
2010-11-13T04:18:42.197Z
Sadeq Dousti
<p>I really  want to echo others and suggest that you sit down and work out a nice SVN strategy. I use SVN to host my entire "research" structure:</p>

<ul>
<li>JabRef reference managing</li>
<li>Downloaded PDFs</li>
<li>Articles</li>
</ul>

<p>It's great because it contains everything, and of course provides a history. The caveat being you need your own server. But if you have some existing Windows machine (or whatever you a comfortable with) you can install it simply through <a href="http://www.visualsvn.com/" rel="nofollow">VisualSVN Server</a>. You then create appropriate accounts for collaborators, and give them access to an appropriate area (i.e. perhaps read-access to your JabRef bibtex file, and read/write to a shared 'in-progress' article area).</p>

<p><a href="http://tortoisesvn.tigris.org/" rel="nofollow">TortiseSVN</a> can be used as the Windows client for interacting with SVN. You need to be careful about moving/deleting files and copying folders (SVN will store metadata inside hidden folders in each of your folders, so you must execute the delete command from within SVN to get rid of it, it takes a bit of getting used to, but is worth the investment).</p>

<p>Then, when working with a collaborator, they clearly must also use SVN. But, again, the investment in learning is not worthless. And via some thought, you can also have it so you have read-only access to their jabref file (perhaps via the 'external' facility in svn).</p>

<p>In this way, with a bit of thought and a little bit of effort, you can be in a situation where you are editing documents as per normal, commiting changes nightly, updating in the morning and resolving all conflicts easily.</p>

<p>I really recommend it. The more people that set up their own SVNs the better, as it will only improve collaboration options in the future (though, of course, it would be beneficial if perhaps there was a 'standard' way of setting up a scientific repository).</p>

<p>-- Edit: Infact, I've written up such a proposal here: <a href="http://www.mirios.com.au:8081/index.php?title=Strategy_for_Scientific_Collaboration_with_LaTeX_and_SVN" rel="nofollow">Strategy for Scientific Collaboration with LaTeX and SVN</a>. It proposes to make use of the svn <a href="http://justaddwater.dk/2007/10/23/setting-up-subversion-externals-with-tortoisesvn/" rel="nofollow">externals</a> feature to allow easy collaboration between people with a similar setup. Let me know if it needs changing or is simply not appropriate.</p>

CC BY-SA 2.5
2011-01-30T23:54:00.603Z
2011-01-31T03:30:30.080Z
2011-01-31T03:30:30.080Z
Noon Silk
<p>While reading your great post and looking around for a solution myself I stumbled into the option to <strong>colorize changes at word level in gitk</strong>. The gitk parameter seems to be a new and/or undocumented feature since the auto-completion does not offer it and the <a href="ftp://ftp.kernel.org/pub/software/scm/git/docs/gitk.html" rel="nofollow noreferrer">gitk man page</a> does not list it.<br>
Here are the options the I found:</p>

<pre><code>gitk --word-diff=plain
gitk --word-diff=porcelain
gitk --word-diff=color
</code></pre>

<p>You can find several discussions on that topic searching for <a href="http://tinyurl.com/3sh79dw" rel="nofollow noreferrer">"diff --color-words" gitk</a>.</p>

<p><strong>Edit:</strong><br>
This is what is looks like ...</p>

<p><img src="https://i.sstatic.net/9Ans7.png" alt="Differences colored at a word-level using gitk"></p>

CC BY-SA 3.0
2011-08-13T22:30:07.833Z
2011-08-14T12:43:02.263Z
2011-08-14T12:43:02.263Z
JJD
<p>Most papers are now written collaboratively, and collaborators are often located in different places.  I have always used version control systems for my documents and code, and have also found version control critical for collaborative software projects, but it seems many researchers in theory avoid their use for writing joint papers.  To convince my collaborators that version control (revision control) is a good idea for working together, there seem to be some prerequisites.  <em>It is not possible to force everyone to worry about a specific set of conventions for line breaks and paragraphs, or to avoid tab/space conversions.</em></p>

<blockquote>
  <p>Does someone offer free hosting of small shared document repositories, with text-document-friendly version control that can handle word-level diffs (<strong><em>not</em></strong> line-based)?</p>
</blockquote>

<p>If not, then I would welcome other suggestions that are based on experience (let's avoid speculation, please).</p>

<p>I was thinking of Git, Subversion, Mercurial, darcs, or Bazaar, set up to handle word-level differences with wdiff, together with a simple way of setting up access secured by public keys (for instance via ssh).  However, none of the version control providers that I looked at seem to offer anything like this.  For scientific collaboration the "enterprise" features stressed by many of these companies are not very important (lots of branches, integration with trac, auditing by third parties, hierarchical project teams).  But word-level diffs seem critical yet unsupported.  In my experience, with line-level diffs for text files, everyone has to avoid reformatting paragraphs and editors that change tabs to spaces or vice versa cause problems; there also seem to be many spurious edit conflicts.  I have used wdiff and latexdiff quite successfully to help with manual merging of changes previously, so I am hoping a word-level diff would reduce such problems.</p>

<p>See related question at MO about <a href="https://mathoverflow.net/questions/3044/tools-for-collaborative-paper-writing">tools for collaboration</a>, and related questions over at TeX.SE, about <a href="https://tex.stackexchange.com/questions/1118/what-are-the-advantages-of-using-version-control-git-cvs-etc-in-latex-document">version control for LaTeX documents</a> and <a href="https://tex.stackexchange.com/questions/161/latex-packages-for-use-with-revision-control">LaTeX packages for version control</a>.  See also the <a href="http://www.svnhostingcomparison.com/" rel="nofollow noreferrer">SVN Hosting Comparison Review Chart</a> for a large list of hosting providers, for just one of the main version control systems.</p>

<hr>

<p><em>Edit:</em> Jukka Suomela's answer to the TeX.SE question "<a href="https://tex.stackexchange.com/questions/4182/best-latex-aware-diff-and-merge-tools-for-subversion">Best LaTeX-aware diff and merge tools for subversion</a>" seems to be the best suggestion so far, covering how to interpret the deltas on a word level.  Moreover, Jukka has explained how the differences between successive versions on the repository end are separate from the user-level differences used for conflict detection and merging of changes.  Jukka's answer at TeX.SE explicitly excludes simultaneous edits and merging, relying instead on the traditional atomic edit token to avoid edit conflicts.  Clarifying (and modifying) my original question, is there a way to ensure that edit conflicts can be resolved on a word difference basis, rather than on a line difference basis?  In other words, can <code>wdiff</code> or similar tools be integrated into the <em>conflict detection</em> part of the version control tools, similar to the way end-of-line differences and differences in whitespace can be ignored?</p>

CC BY-SA 3.0
2011-04-24T19:48:26.870Z
@Jukka: your comment seems the clearest, pointing out my misconceptions to do with computation and display of diffs, and outlining a better way to think about this.  Care to post it as an answer?
András Salamon
CC BY-SA 2.5
2011-01-30T23:44:34.973Z
@Andras: As Jukka says, you can use any diff strategy you like locally. Personally, I recommend BeyondCompare; but the built-in svn diff is "acceptable", given that it is free. How SVN does the diffs between the server is irrelevant to your problem.
Noon Silk
CC BY-SA 2.5
2010-11-12T18:21:36.140Z
Why wouldn't using bitbucket set-up with wdiff work? The diffs shown on the site wouldn't use wdiff, but locally it should "look right".
Mark Reitblatt
CC BY-SA 2.5
2010-11-12T18:36:04.503Z
why do you care about word-level diff ?
Suresh Venkat
CC BY-SA 2.5
2010-11-12T18:41:24.663Z
I don't quite understand the question. For example, in SVN, diffs displayed to a user are generated by the client, and it depends on your SVN client (and its configuration) whether you get word-based diffs or line-based diffs. The company that hosts your SVN repository doesn't affect this at all.
Jukka Suomela
CC BY-SA 2.5
2010-11-12T18:46:43.697Z
More related discussion: http://tex.stackexchange.com/questions/4182/best-latex-aware-diff-and-merge-tools-for-subversion
Jukka Suomela
CC BY-SA 2.5
2010-11-12T19:10:48.063Z
@suresh If you're editing (written) text documents, it's often a pain to have to scan a whole line in a diff to see that someone changed one comma. The correct behavior usually is to show the minimal unit of change. Or, consider the behavior if someone doesn't use line breaks. Then changing a single word will cause the whole paragraph to show up in the diff for you to find the tiny change.
Mark Reitblatt
CC BY-SA 2.5
2010-11-12T19:28:42.057Z
I do not think that word-based diffs are necessary to compare versions of a LaTeX source file if you write the source file in a way suitable for line-based diffs (that is, keep source lines reasonably short and do not move line breaks just to fill 72 columns).  This is kind of workaround and may not be the optimal solution, but at least it works sufficiently well in my case.  (But I have never used version control for collaboration.)
Tsuyoshi Ito
CC BY-SA 2.5
2010-11-12T19:53:59.080Z
I don't use hard line breaks to wrap lines. In my Latex source code, a physical line of text is usually a full paragraph of text. The editor can word-wrap it for display, depending on the current window width. It simplifies things a lot; there is never need to worry about things like should I re-word-wrap a paragraph, or to agree on the "right" line width with your co-authors. However, you will need a word-level diff tool to see the changes quickly.
Jukka Suomela
CC BY-SA 2.5
2010-11-13T19:05:01.230Z
Thanks to everyone for the comments.  I thought the server side had to be aware of word-level diffs, since deltas are the basic unit of revision control as I understand it.  Has this basic principle changed?
András Salamon
CC BY-SA 2.5
2010-11-14T03:15:48.617Z
@Andras As Jukka said in 3, the diff algorithm is ran on the client side. The client first reconstructs the two revisions to be compared, usually storing them in temp files. Then it passes the two files to the internal diff algorithm, or an external diff utility of your own choosing, which can be a word-level diff utility like wdiff as you mentioned.
Maverick Woo
CC BY-SA 2.5
2010-11-14T11:28:08.703Z
@Andras My point was that the VC system only needs to be able to reconstruct the two revisions on the client side, and not surprisingly all VC systems can do that. What you then need is a word-level three-way merge utility, but I don't know of any. (For example, TortoiseMerge and kdiff3 are both line-based.) Once you have such a utility, then any VC system that allows you to specify an external merging utility will suffice. (That includes svn, bzr, git, hg...)
Maverick Woo
CC BY-SA 2.5
2010-11-14T11:56:02.393Z
One source of confusion here is that there is a built-in binary diff algorithm (that operates on the level of individual bytes) that is used by SVN in the communication between the server and client, and also internally by the server to keep the repository compact. This is merely an optimisation; it is not visible to the user and the same binary diff algorithm can be applied to any kind of file. All user-visible things (human-readable diffs, merging, conflict resolution...) happen on the client side.
Jukka Suomela
<soft-question><research-practice><software><writing>
Version control for collaboration (with word-level diffs)?
András Salamon
# Version control for collaboration (with word-level diffs)?

(Asked by: username_0 on 2010-11-12)

Most papers are now written collaboratively, and collaborators are often located in different places. I have always used version control systems for my documents and code, and have also found version control critical for collaborative software projects, but it seems many researchers in theory avoid their use for writing joint papers. To convince my collaborators that version control (revision control) is a good idea for working together, there seem to be some prerequisites. *It is not possible to force everyone to worry about a specific set of conventions for line breaks and paragraphs, or to avoid tab/space conversions.*

> Does someone offer free hosting of small shared document repositories, with text-document-friendly version control that can handle word-level diffs (***not*** line-based)?

If not, then I would welcome other suggestions that are based on experience (let's avoid speculation, please).

I was thinking of Git, Subversion, Mercurial, darcs, or Bazaar, set up to handle word-level differences with wdiff, together with a simple way of setting up access secured by public keys (for instance via ssh). However, none of the version control providers that I looked at seem to offer anything like this. For scientific collaboration the "enterprise" features stressed by many of these companies are not very important (lots of branches, integration with trac, auditing by third parties, hierarchical project teams). But word-level diffs seem critical yet unsupported. In my experience, with line-level diffs for text files, everyone has to avoid reformatting paragraphs and editors that change tabs to spaces or vice versa cause problems; there also seem to be many spurious edit conflicts. I have used wdiff and latexdiff quite successfully to help with manual merging of changes previously, so I am hoping a word-level diff would reduce such problems.

See related question at MO about [tools for collaboration](https://mathoverflow.net/questions/3044/tools-for-collaborative-paper-writing), and related questions over at TeX.SE, about [version control for LaTeX documents](https://tex.stackexchange.com/questions/1118/what-are-the-advantages-of-using-version-control-git-cvs-etc-in-latex-document) and [LaTeX packages for version control](https://tex.stackexchange.com/questions/161/latex-packages-for-use-with-revision-control). See also the [SVN Hosting Comparison Review Chart](http://www.svnhostingcomparison.com/) for a large list of hosting providers, for just one of the main version control systems.

---

*Edit:* Jukka Suomela's answer to the TeX.SE question "[Best LaTeX-aware diff and merge tools for subversion](https://tex.stackexchange.com/questions/4182/best-latex-aware-diff-and-merge-tools-for-subversion)" seems to be the best suggestion so far, covering how to interpret the deltas on a word level. Moreover, Jukka has explained how the differences between successive versions on the repository end are separate from the user-level differences used for conflict detection and merging of changes. Jukka's answer at TeX.SE explicitly excludes simultaneous edits and merging, relying instead on the traditional atomic edit token to avoid edit conflicts. Clarifying (and modifying) my original question, is there a way to ensure that edit conflicts can be resolved on a word difference basis, rather than on a line difference basis? In other words, can `wdiff` or similar tools be integrated into the *conflict detection* part of the version control tools, similar to the way end-of-line differences and differences in whitespace can be ignored?

**Tags:** soft-question, research-practice, software, writing
> **Comments:**
> **username_2**: Why wouldn't using bitbucket set-up with wdiff work? The diffs shown on the site wouldn't use wdiff, but locally it should "look right".  
> **username_3**: why do you care about word-level diff ?  
> **username_4**: I don't quite understand the question. For example, in SVN, diffs displayed to a user are generated by the client, and it depends on your SVN client (and its configuration) whether you get word-based diffs or line-based diffs. The company that hosts your SVN repository doesn't affect this at all.  
> **username_4**: More related discussion: http://tex.stackexchange.com/questions/4182/best-latex-aware-diff-and-merge-tools-for-subversion  
> **username_2**: @suresh If you're editing (written) text documents, it's often a pain to have to scan a whole line in a diff to see that someone changed one comma. The correct behavior usually is to show the minimal unit of change. Or, consider the behavior if someone doesn't use line breaks. Then changing a single word will cause the whole paragraph to show up in the diff for you to find the tiny change.  
> **username_5**: I do not think that word-based diffs are necessary to compare versions of a LaTeX source file if you write the source file in a way suitable for line-based diffs (that is, keep source lines reasonably short and do not move line breaks just to fill 72 columns).  This is kind of workaround and may not be the optimal solution, but at least it works sufficiently well in my case.  (But I have never used version control for collaboration.)  
> **username_4**: I don't use hard line breaks to wrap lines. In my Latex source code, a physical line of text is usually a full paragraph of text. The editor can word-wrap it for display, depending on the current window width. It simplifies things a lot; there is never need to worry about things like should I re-word-wrap a paragraph, or to agree on the "right" line width with your co-authors. However, you will need a word-level diff tool to see the changes quickly.  
> **username_0**: Thanks to everyone for the comments.  I thought the server side had to be aware of word-level diffs, since deltas are the basic unit of revision control as I understand it.  Has this basic principle changed?  
> **username_6**: @Andras As Jukka said in 3, the diff algorithm is ran on the client side. The client first reconstructs the two revisions to be compared, usually storing them in temp files. Then it passes the two files to the internal diff algorithm, or an external diff utility of your own choosing, which can be a word-level diff utility like wdiff as you mentioned.  
> **username_6**: @Andras My point was that the VC system only needs to be able to reconstruct the two revisions on the client side, and not surprisingly all VC systems can do that. What you then need is a word-level three-way merge utility, but I don't know of any. (For example, TortoiseMerge and kdiff3 are both line-based.) Once you have such a utility, then any VC system that allows you to specify an external merging utility will suffice. (That includes svn, bzr, git, hg...)  
> **username_4**: One source of confusion here is that there is a built-in binary diff algorithm (that operates on the level of individual bytes) that is used by SVN in the communication between the server and client, and also internally by the server to keep the repository compact. This is merely an optimisation; it is not visible to the user and the same binary diff algorithm can be applied to any kind of file. All user-visible things (human-readable diffs, merging, conflict resolution...) happen on the client side.  
> **username_1**: @Andras: As Jukka says, you can use any diff strategy you like locally. Personally, I recommend BeyondCompare; but the built-in svn diff is "acceptable", given that it is free. How SVN does the diffs between the server is irrelevant to your problem.  
> **username_0**: @Jukka: your comment seems the clearest, pointing out my misconceptions to do with computation and display of diffs, and outlining a better way to think about this.  Care to post it as an answer?  

---

## 4 answers

### Answer by username_7 on 2010-11-14. Score: 11

I've used git to collaborate on some documents written in latex. You'll have to adhere to some rules:

* Start each sentence on a new line, latex ignores these newlines as long as there is no blank line
* Use the same configuration for formatting (tab/spaces/max text width)
* For best results, create a .gitattributes file in your repository and add the line `*.tex diff=tex`. This makes diff aware of the tex syntax and leads to more meaningful output.

You can then use `git diff --color-words` and `gitk --color-words` to see word differences (also see this article [Word-by-word diffs in Git](http://idnotfound.wordpress.com/2009/05/09/word-by-word-diffs-in-git/) on how to configure git to always use word-diff algorithm for displaying the git diff/git log).

To reduce the manual merges, I can recommend using separate files for sections and subsections (depending on the size of your document).

> **Comments:**
> **username_0**: I'll consider doing this for my own documents, it seems to be an easy way to achieve most of my aims.  But not everyone is keen to work this way...  
> **username_7**: For people hesitant to work this way, you can use TortoiseGit if they don't like the git command line. If it is about the each sentence on a new line part, well as long as there is no maximum text width forced, this isn't that important. (I have worked on some projects without that rule)  
> **username_8**: On the whole, I agree that git is a good choice. But why can separate files for (sub)sections reduce the number of manual merges? I also wonder how starting each sentence on a new line helps (sometimes sentences mix in the process of editing).  
> **username_7**: regarding the separating files: at that time, I did not understand the exact details of git merging, so that is actually unneeded, but still advisable for other reasons. The sentence on a new line is very important, since most tools around git always show line changes, if you then use another strategy, say let the editor do linebreaks, every time someone changes 1 word in a paragraph, you will have to hunt were it happend, and in case of automatic merging: no way.  

---

### Answer by username_9 on 2010-11-13. Score: 4

I suggest taking a look at:

[LaTeX/Collaborative Writing of LaTeX Documents](http://en.wikibooks.org/wiki/LaTeX/Collaborative_Writing_of_LaTeX_Documents),

and the related paper:

[Tools for Collaborative Writing of Scientific LaTeX Documents](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.118.4587&rep=rep1&type=pdf).

> **Comments:**
> **username_0**: Unfortunately the "best practices" in these documents are precisely the kinds of things one cannot force on collaborators.  

---

### Answer by username_1 on 2011-01-30. Score: 4

I really want to echo others and suggest that you sit down and work out a nice SVN strategy. I use SVN to host my entire "research" structure:

* JabRef reference managing
* Downloaded PDFs
* Articles

It's great because it contains everything, and of course provides a history. The caveat being you need your own server. But if you have some existing Windows machine (or whatever you a comfortable with) you can install it simply through [VisualSVN Server](http://www.visualsvn.com/). You then create appropriate accounts for collaborators, and give them access to an appropriate area (i.e. perhaps read-access to your JabRef bibtex file, and read/write to a shared 'in-progress' article area).

[TortiseSVN](http://tortoisesvn.tigris.org/) can be used as the Windows client for interacting with SVN. You need to be careful about moving/deleting files and copying folders (SVN will store metadata inside hidden folders in each of your folders, so you must execute the delete command from within SVN to get rid of it, it takes a bit of getting used to, but is worth the investment).

Then, when working with a collaborator, they clearly must also use SVN. But, again, the investment in learning is not worthless. And via some thought, you can also have it so you have read-only access to their jabref file (perhaps via the 'external' facility in svn).

In this way, with a bit of thought and a little bit of effort, you can be in a situation where you are editing documents as per normal, commiting changes nightly, updating in the morning and resolving all conflicts easily.

I really recommend it. The more people that set up their own SVNs the better, as it will only improve collaboration options in the future (though, of course, it would be beneficial if perhaps there was a 'standard' way of setting up a scientific repository).

-- Edit: Infact, I've written up such a proposal here: [Strategy for Scientific Collaboration with LaTeX and SVN](http://www.mirios.com.au:8081/index.php?title=Strategy_for_Scientific_Collaboration_with_LaTeX_and_SVN). It proposes to make use of the svn [externals](http://justaddwater.dk/2007/10/23/setting-up-subversion-externals-with-tortoisesvn/) feature to allow easy collaboration between people with a similar setup. Let me know if it needs changing or is simply not appropriate.


---

### Answer by username_10 on 2011-08-13. Score: 4

While reading your great post and looking around for a solution myself I stumbled into the option to colorize changes at word level in gitk. The gitk parameter seems to be a new and/or undocumented feature since the auto-completion does not offer it and the gitk man page does not list it.
Here are the options the I found:
gitk --word-diff=plain
gitk --word-diff=porcelain
gitk --word-diff=color

You can find several discussions on that topic searching for "diff --color-words" gitk.
Edit:
This is what is looks like ...


---

