Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

I'm about to start version controlling my LaTeX documents with Git but I haven't used either very much. I would like to version only the files needed to compile the document but I use different OS's (OSX, Windows and different distros of Linux). I did a search for a .gitignore file for LaTeX and came up with 3 different ones:

Here's a comparison of each in alphabetical order in tabular format:

*.acn               *.acn               
*.acr               *.acr               
*.alg               *.alg               
*.aux               *.aux               .aux
*.bbl               *.bbl               *.bbl
*.blg               *.blg               *.blg
*.dvi               *.dvi               *.dvi
                                        *.fdb_latexmk
*.glg               *.glg               *.glg
*.glo               *.glo               *.glo
*.gls               *.gls               *.gls
*.idx               *.idx               *.idx
*.ilg               *.ilg               *.ilg
*.ind               *.ind               *.ind
*.ist               *.ist               *.ist
*.lof               *.lof               *.lof
*.log               *.log               *.log
*.lot               *.lot               *.lot
*.maf               *.maf               
                    *.mp                
*.mtc               *.mtc               
*.mtc1              *.mtc1              
                                        *.nav
                                        *.nlo
*.out               *.out               *.out
                    *.pdf               
                                        *.pdfsync
                                        *.snm
*.synctex.gz        *.synctex.gz        *.synctex.gz
                    *.tmp               
*.toc               *.toc               *.toc
                    *.top               
                    *.tui               
                                        *.vrb

                    # Mac IDE files             
                    *.swp               
                    *~              
                    *(Autosaved).rtfd/              
                    Backup[ ]of[ ]*.pages/              
                    Backup[ ]of[ ]*.key/                
                    Backup[ ]of[ ]*.numbers/                

                    # Mac finder files and hidden folders               
                    .DS_Store

Can anyone suggest why some might be missing from others and if it's okay just to include them all in one .gitignore file for use on all OS's?

share|improve this question
12  
Don't ignore PDF if you have PDF images :) –  topskip May 10 '11 at 9:21
8  
For most documents, only very few of those will be generated. I just add files to .gitignore when something I didn't create myself (i.e., something other than .tex, or images or whatever) is shown by git as untracked. I guess there could be value in a universal .gitignore list, but false positives also mean files could go untracked. –  ShreevatsaR May 10 '11 at 9:21
6  
Hi, welcome to TeX.SX. This is a great question! I myself use version control software for LaTeX to a great extend and started to collect such lists. Because this also affects other VC software I took the liberty to make the title and tags more general. Also, the house style around here is to not have an opening or closing on posts. Your name automatically appears in the lower right corner of your post. –  Martin Scharrer May 10 '11 at 9:21
1  
Hi guys, thank you very much for your comments. Extremely helpful! It's difficult to choose a single answer to mark as correct so I've chosen the one with the most votes (please don't be offended if it wasn't yours). @Martin: Thanks for editing the tags/title for me. Right, off to create my repo :) –  Jack May 10 '11 at 19:28
1  
+1 for a really nice comparison of each in alphabetical order in tabular format ! –  nutty about natty Mar 31 '13 at 11:16
show 4 more comments

4 Answers 4

up vote 35 down vote accepted

The reason for an ignore file list is the following. When your VCS spots a file in the directory that it isn't versioning, it tells you about it (politely). For example, in one of my directories then running bzr status, I get the following message:

tex.SE% bzr status
unknown:
  Project/
  braids.sty@
  bzr_test/
  lessonplan.cls@
  lessonplan.sty@
  listings.sty
  mylectures.sty@
  refs.bib
  tqft.sty@
  unicode-math-chg.sty
  unicode_beamer_test.txt
  xepstricks.xdv

That's a useful feature to have since it tells me if there are files that I haven't yet put under the control of the VCS. In particular, if I spot anything with the suffix .tex there, then I know that there's something I forgot to do before committing my changes.

The point of the ignore file (.bzrignore in my case) is to remove stuff automatically from this list. If I get rid of that file in this directory then I get a list of 833 files! That's rather a long list to go through to see if I've missed a .tex file or not.

The important things to remember with ignore files are thus:

  1. It is more important to focus on what is not there than what is there. The extensions that are not there are the types of files where you think, "It is more than likely that a file of this extension will be under the control of the VCS.".

  2. It is advisory. The ignore file simply tells the VCS which files you will usually put under its control. You are completely free to ignore its recommendations and not put under its control a file that it lists, and you are completely free to put under its control a file that it doesn't list.

  3. It can be changed. It's actually best to start with a minimal file (I'll give an example at the end) and only add extensions as you find that you need them. As I said, the main purpose of this file is as an early warning system to ensure that everything that should be ignored actually is. If you import an ignore file from some central repository and then start creating files yourself which happen to have those extensions (just because you wouldn't have thought they could be anything to do with TeX), then you might miss a file. So when you find the list of suggested files too long to see the important ones in, then add some more extensions to the list.

  4. It should be project-specific. The files you want to ignore in one project are not necessarily the same as in another. You should have a small main list that are safe to always ignore, and then add things to it on a per-project basis.

  5. It should be versioned. Goes without saying, really!

So what should be in it? The basic rule is that you should version those files that you directly create. So the things you don't version are those that are created for you (the exception to this is if you don't have a copy of the program that creates them on every machine, gnuplot data files are an example that springs to mind). So the initial list should be those files that your TeX process creates. As you say you're using LaTeX, the following is a fairly minimal list:

    *.aux
    *.pdf
    *.ps
    *.log
    *.dvi
    *.tex~

If you are using BibTeX, add .bbl and .blg to that list. If your system has a habit of creating extra files in the system, then add those. That's what things like .DS_Store are doing on those lists. That's Mac-specific. Linux doesn't do things like that (it's polite). I have no idea what Windows does. As you start using other programs, and more complicated packages, you'll find new files springing in to existence. If you generate web pages, you'll find yourself wanting to add a whole slew like .4ct and similar.

So, in summary, start small and remember that the computer is there to do what you tell it to do, not the other way around.

share|improve this answer
    
I'm only getting into git now, but this answer is very useful. Thanks! As pointed out by Martin in the comments, though, if you have pdf images, you should carefully consider whether to use the *.pdf rule or not. –  Jubobs Jan 6 at 19:03
    
@Jubobs That comes under Note 2. –  Loop Space Jan 6 at 19:33
add comment

I agree with ShreevatsaR's comment. For most projects, very few of these are actually generated - it depends what packages you decide to include. So I start off with an empty .gitignore and add only the ones that I actually see appearing when I compile my TeX files.

Also, sometimes it's not appropriate to add an extension to the .gitignore willy-nilly. For example, if you have PDF images, then you probably don't want to add *.pdf to your .gitignore, rather you want to add yourtexfile.pdf. Similarly if all of your *.eps images are automatically generated from something else in your makefile (for example, I use dia for most of my images, and the EPS versions are generated by asking dia to automatically convert the figures), then it's appropriate to add *.eps.

Lastly, you can add exceptions to the .gitignore by prepending a line with an !. For example, the following will ignore all automatically generated PDF files, while paying attention to figure.pdf which is a manually generated PDF image.

*.aux
*.dvi
*.pdf
!figure.pdf
share|improve this answer
3  
Useful to know about exclusions, and good point about the PDFs. –  Loop Space May 10 '11 at 16:52
add comment

LaTeX and its packages produce a variety of auxiliary files. There are also some external tools which create their own files. Then there is the set of output files generated by (La)TeX like DVI, PS and PDF files which you may or may not want to put under version control. Normally you don't.

The reason some extension are missing in some lists is because the number of extensions can depend a lot on the packages and tools used. New packages are created all the time and some might not be known or used by the authors of theses lists.


I think it would be good to have a list and maybe description of packages and the auxiliary files created by them. Here the ones I just had in my mind (and in my svn:ignore lists). A used a category for extensions I couldn't place to a specific package right away.

  • (La)TeX: *.log *.aux *.toc

  • Lists: *.lof *.lot

  • Index: *.idx *.ind *.ilg

  • Glossary: *.glo *.gls *.glg

  • Bib(La)TeX: *.bbl *.blg

  • hyperref: *.out

  • svn-multi: *.svn *.svt *.svx

  • standalone: *.sta *.stp

  • latexmk tool: *.fdb_latexmk

  • endfloat: *.fff

  • Other: *.run.xml

share|improve this answer
1  
http://www.ctan.org/pkg/thumbs creates *.tmb files. –  Stephen Sep 16 '11 at 17:50
add comment

Quite a few modules create their own auxiliary files.

For example, you might also clean:

  • *.lol (list of listings);
  • *.ps (if it's not your final format);
  • *.idv and *.lg;
  • *.4tc, *.4ct, *.xref if you use tex4ht;

In general, what I do is that I version all my source files. When I use new modules (or new renderers), after cleaning my code with make clean, I run a git status to check for auxiliary files that I don't know about, and I add them to my clean rule (or .gitignore if you prefer).

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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