Which auxiliary LaTeX files should be ignored by Version Control Software?

Question

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:

• https://gist.github.com/149016
• https://gist.github.com/871983 (a fork of the above but for Mac)
• https://github.com/github/gitignore/blob/master/LaTeX.gitignore (another for LaTeX in general)

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?

Answer 1

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.

Answer 2

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

Answer 3

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

Answer 4

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).