# What are the advantages of using version control (git, CVS etc) in LaTeX documents

Why would I need to use version control with my LaTeX documents? I know people who do it, and I've seen questions about it on here and on SO, but I haven't understood what value there is to doing it...

[Maybe this should be CW? Also, someone >150 rep add some more tags, e.g. version-control]

-
DO NOT use CVS. Ii is seriously outdated. –  Caramdir Aug 5 '10 at 11:55
@Caramdir: Ya think? I'm currently working in an environment that uses RCS - CVS' precessor... :P –  Tomas Lycken Aug 5 '10 at 12:41
Imagine working on a paper all night. The next day you get up and wonder which monkey abused your keyboard to type random words that do not make any sense. THEN source control will help you to return to the last consistent state of your document. –  h0b0 Aug 5 '10 at 15:45
Protip: write one sentence per line; then changing one sentence doesn't ruin the diff of a whole paragraph. –  Paul Biggar Nov 12 '10 at 0:24
@PaulBiggar no need if you're using git. Just do git diff --color-words and you'll see diffs at word level. –  Yawar May 23 '13 at 4:24

As a single user the main advantages are

• Automatic backups: If you accidentally delete some file (or part of a file) you can undelete it. If you change something and want to undo it, the VCS can do so.
• Sharing on multiple computers: VCSes are designed to help multiple people collaboratively edit text files. This makes sharing between multiple computers (say your desktop and laptop) particularly easy. You do not need to bother if you always copied the newest version; the VCS will do that for you. Even if you are offline and change files on both computers, the VCS will merge the changes intelligently once you are online.
• Version control and branching: Say you published some class notes as a pdf and want to fix some typos in them while simultaneously working on the notes for next year. No problem. And you only need to fix the typos once, the VCS will merge them to the other versions.
-
NB: I learned the importance of the first point the hard way, when I accidentally deleted several days of work. –  Caramdir Aug 5 '10 at 11:48
The second one was what swung it for me - working from several different computers is a breeze with version control. –  Loop Space Aug 5 '10 at 11:50
About learning things the hard way: a VCS doesn't replace conventional backups unless the repository is distant. When I switched from SVN to git, I forgot this point until I was hit... –  mpg Nov 11 '10 at 21:50
Can SVN do automatic backups? –  xport May 31 '11 at 5:39
@xport: yes/no. standard SVN requires a remote server, which kind of is a backup. For git, you don't need a remote server, but as mpg mentions, you should still consider that –  Tobias Kienzler Sep 21 '11 at 13:05

The same advantages you get of using version control for any other kind of documents.

Helps for many people to collaborate on a single document/project, keeps track of all the changes to the document as it evolves, you can revert and/or merge edits.

-

I'm also someone who uses version control as a single user. All of Caramdir's reasons are ones that I agree with, and I'll add the following:

• Tagging. When I send a paper off to a journal, I can "tag" that version and so even if I make my own improvements in the meantime, when I get the referee's report back then I can easily revert to the version that the comments are on. Plus it's easy to see when I sent a copy to which journal or to collaborators or to eprint repositories.
• Working with collaborators even if they don't have the VCS themselves. I can make a branch copy for my collaborator on my own system and simply copy in their corrections to that each time, then merge them into the main branch as if they'd been using the VCS all along. Keeps the advantages of using version control but without requiring all collaborators to use it.
• Maintaining different versions. Caramdir already said this, but I'd like to emphasise it as it happens a lot more than one might expect. When I write a paper, I write it first for myself. So I make life easy on myself by using lots of macros and the like to make it easy for me to type. But then I want to submit it to a journal, send it to the arXiv, send it to some other eprint servers, put a copy on my webpage, put an accessible copy on my webpage ... Each of these might require a slight change to the document, for example one eprint server I use doesn't have a decent set of fonts so I have to "downgrade" my papers before sending it there. But of course, I'm still working on the paper after sending a version to all these different places and so a VCS helps me keep all of them in step.

Incidentally, I switched to using a version control system around about the time I started taking online notes of everything that I did. So I wrote up some notes on the process here. I also found an article (also available as a wikibook) on the subject that was very helpful to me in deciding to switch to a version control system and on what to look for in one.

-
+1 for the idea of using branches to incorporate collaborator edits. I also use the tagging idea for different versions (submitted, final, journal, arxiv etc) –  Suresh Aug 5 '10 at 17:55
For maintaining different versions do you have different branches and keep merging between them, or do you use a different method? E.g. patch queues? –  Faheem Mitha Nov 3 '13 at 18:39
@FaheemMitha I usually have a main branch where I do the significant edits and then the other branches keep pulling these changes from the main branch. –  Loop Space Nov 4 '13 at 8:11

Version control systems are also very useful to view differences between versions of a document.

This functionality is only relevant for files in plain text format, but thanks god, you use *TeX :)

-
Binary files are at least partially supported i.e. you can still see the diff. –  Leo Liu Aug 5 '10 at 17:01
@Leo: Well, you can see the difference, sure, but you aren't going to get any kind of sensible udiff out of it... –  SamB Dec 19 '10 at 7:26

If you haven't used a version control tool before, I seriously recommend you start using one. Otherwise you will version control manually i.e. paper-v5, paper-v6 etc which may be sufficient for one-off, short-term projects.

You can see version control as recording a (discrete) history of your project allowing you to associate notes with the changes you make and to inspect at later stage why they were made. This might sound cumbersome but most good editors let you seamlessly integrate it into your workflow. In fact you will soon find version control tool indispensable.

-

Using revision control makes you unafraid to make radical changes to your document. As one of my friends, Peter Boothe, put it,

you can now freely throw away bits and pieces, secure in the knowledge that if you actually want them back, they are there in the revision control system. Interestingly, almost nobody actually uses this feature. Revision control systems are not there to save your old work. They are there to give you permission to throw that old work away.
-
I agree completely! Before switching to a VCS, the ends of my papers were full with junk that I'd "saved" by shifting it beyond the \end{document}. Now I no longer have to do that. –  Loop Space Aug 15 '10 at 16:28
That's a great quote. Very insightful. –  Will Robertson Oct 16 '10 at 10:29
Yeah, this has been my main reason for putting nearly everything I've written lately under some form of VCS, even just RCS: that way I can easily make a snapshot before making massive removals/revisions, so I can go back if I change my mind, no matter when I change my mind (although in practice I don't think I've ever done more than revert to the last committed version, and even then perhaps only partially). –  SamB Dec 19 '10 at 7:23
Thanks Chris! I egosurfed and found this here! I am glad you found it useful. –  Peter Boothe Jan 8 '11 at 3:44

For me, one of the main reasons for using a VCS is to avoid cluttering my working directory with lots of mainly useless files with cryptic filenames like:

mydocument20103001.tex

mydocument20103001aa.tex

mudocument20091221.tex

mydocument20091221jonsversion.tex

With such a system, it is hard to keep track of which changes occurred in which version. It gets worse if you have multiple authors collaborating on a document with different file naming conventions. It gets even worse if you are using a similar system for your bibtex and image files, as you have to keep remembering to update the references to the files in the main document. It gets even more worse if you are collaborating via sending email attachments and don't know for sure that you have saved every single version that was emailed into your working directory.

With a VCS you just have one copy of each file, so you have a much cleaner and easier to navigate working directory. The VCS should make it easy for you to find out where changes were made, so that you can easily find things when you want to restore something that you previously edited out. Since the VCS stores everything, you know that every version of the file is available in one place. It should also declutter your email inbox a little bit as you won't need the attachments and emails that just announce updates to the document are no longer needed.

-

I agree with the others, but the most "non technical" reason is to think about it as "unlimited undo" between the versions that was saved in the VCS.

You can always get a old version back regardless what you do.

This is the meaning of the "automatic backup" that is a little bit tricky to understand.

SubVersion is a simple to understand system, that works well for small teams.

Git on the other hand is is more technical advanced and scales better, but for small teams this is a academical question.

But the point is that any VCS is better than not using this type of systems at all.

-
When I was using svn I still used rcs for single file projects. But since moving to git, even for single file projects I can no longer use rcs. The most difficult tool hard to learn and use is actually rcs. I have encountered endless locking problems. –  Leo Liu Aug 15 '10 at 16:39
@Leo: I never had any real trouble, but then I always did it from within Emacs and just used "C-x v v" for almost everything, so... –  SamB Dec 19 '10 at 7:28

For why this is needed, look at the other (very good) answers. I would like to add that I use DropBox for my LyX documents. It does pretty much what you would get with a VCS (without branches/merges etc. - but as a single use for a document, you probably won't need it), but it does that automatically. It syncs your files between computers and it makes your documents available to you online.

-
How can it sync files reliably without branches/merges? –  SamB Dec 19 '10 at 7:24
In case of conflicts it just duplicates the file. That is, it is mainly useful for one user, or when the it is sure there will be no conflicts. –  Dror Jan 13 '11 at 14:54

Version control systems also let you work on several machines. For example, I git push before going home, and when I get there and want to finish my work, I start with git pull. This is a lot easier than transferring files to a USB key, or scping them, or using dropbox, etc.

-
Since Dropbox just works in the background, how is git push and git pull easier than doing nothing? –  Seamus Oct 25 '10 at 9:38
@Seamus: I probably use dropbox incorrectly. I want all my files to be local to the directories in which I work, so I copy to dropbox, which is a bit of work. I guess I should make links to my dropbox directory. Thanks. –  dank Oct 25 '10 at 10:41
I just have my local working directory inside dropbox, so I don't have to do anything. That said, I would prefer the extra control that using git to do this would give me. But I maintain that it isn't easier, just better. –  Seamus Oct 25 '10 at 12:24

It doesn't matter whether it's a document or computer program source code. The benefits of VCS are the same. For me the compelling reason is the ability to study and track change over time. It's just like having a time machine.

-

It's also handy to automatically include a version/revision number from your VCS into the output of your document. Then when you're look at the output or hardcopy you can tell if it's out of date or how to re-construct the exact input files.

-
Is there a way to automatically do this with LaTeX? –  Michael Schneider Nov 11 '10 at 23:10
I use \input to read a file that the Makefile created. –  bombcar Mar 13 '14 at 19:25