[Tex/LaTex] Which auxiliary LaTeX files should be ignored by Version Control Software

auxiliary-filescross platformgitrevision control

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?

Best Answer

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.

Related Question