Why to exclude generated files?

Before going to the list of what and the explanation of how, let's see why should we exclude generated files.

One of the values a version control system provides is making it easy to locate the changes we made. If there are files that were generated by various tools, those just create noise that makes it harder to focus on the real changes.

Besides, some of these files might include a timestamp so even if you have not changed anything in the code, just ran perl Makefile.PL you might get these files updated. Adding these changes to the repository would create a lot of noise.

There are cases when opening a source file for reading will create a temporary file (e.g. vim will create a swap file). It would be very disturbing to see these files in the repository.

If you use a Mac, and use the Finder to browse the project directory, it might create a file called .DS_Store we certainly don't want those to litter the filesystem of other people.

Finally, some of the generated files will be different among operating systems or even architectures of the same operating system. They might even differ based on what other Perl modules you have installed.

Seeing all those changes in the history will just confuse everyone and will make it hard to focus on the real changes.

What to exclude

Now let's go over the files and directories that should NOT be under version control and have some explanation what is what. We can even try to categorize them as Neil Bowers suggested.

Files generated by various parts of the Perl/CPAN toolchain

The blib/ directory (which probably stands for build lib) is where the build process creates a directory structure that will be installed. In a simple perl modules this means copying the .pm files from the lib/ directory to the blib/ directory. In more complex cases modified versions of the .pm files are placed in the blib/ directory. I even recall modules that were creating .pm file on-the-fly during the perl Makefile.PL. Other distributions, especially ones that are partially based on XS or C code, will put compiled files in the blib/ directory.

Build and Build.bat are created by perl Build.PL and they aid in the release and installation process. The former is created on *nix systems. The latter on MS Windows. Neither of these need to be kept around, nor should they be distributed.

_build/ is also created by perl Build.PL and holds several files aiding the build process. No need to keep them or to distribute them.

/.build/

.last_cover_stats

Makefile is created by running perl Makefile.PL. It can be very specific to the current system so it should not be kept in version control or distributed.

Makefile.old and Makefile.bak are two "backup copies" of the Makefile. Usually none of them is needed. Certainly they should not be kept around in version control, nor should they be distributed.

pm_to_blib is an empty file created by the build process. It is used only to check if any of the source files are out of date and needs to be rebuilt.

The inc/ directory is created by Module::Install. The content of this directory should be included in the distribution, but should not be in the version control system. The directory is created when the developer runs perl Makefile.PL and it is used when the user installing the module runs perl Makefile.PL.

META.yml and META.json both contain computer readable meta-information about the distribution. They are based on the content of the Makefile.PL, Build.PL, dist.ini and on the content of the modules being distributed. There are two files for historical reasons. Originally it was just the yml file, now many people also include the json file. Theoretically the content should be identical, though as far as I know the json file usually contains more details. Some tools, e.g. MetaCPAN use the content of these files. They are generated during the release of the distribution, and they should be included in the distribution, but because they are generated files, they should NOT be under version control.

MYMETA.json and MYMETA.yml are similar to the META.json and META.yml files but they incorporate the local specialties of the system where the distribution is currently being installed. They are used during the installation process, but because they are site specific they should NOT be included in the distribution, and the should NOT be under version control.

If you use MANIFEST.SKIP then I'd add /MANIFEST to the .gitignore file.

Distribution-Name-* - If this is a repository of a distribution that will be released as Distribution-Name-1.02.tar.gz then the build process is going to create a directory called Distribution-Name-1.02/ and then a file called Distribution-Name-1.02.tar.gz. None of these should be kept in the repository where we keep the source code.

Files generated by various Perl tools

The cover_db/ directory is created by Devel::Cover module when you generated a test-coverage report.

nytprof.out is created by Devel::NYTProf, the profiler many people use. This generated file should not be kept in version control, nor should it be included in the distribution.

.tidyall.d/ is a directory created and maintained by Code::TidyAll. It is a cache to speed up the perltidy process.

Files from the OS

On Mac the Finder, the directory browser creates a file called .DS_Store in directories one visits. This is computer specific and should be excluded from the version control system

Files from text editors, compilers, etc

If you use vim for editing file I'd add *.swp to ignore the swap files.

How to exclude

It depends on the version control system you use. Git will look at a file called .gitignore in the root of the repository. Mercurial (HG) looks at a file called .hgignore in the root of the repository. Subversion uses the svn:ignore property on a directory to defined what items to ignore in that directory. The SVN Book describes how to ignore unversioned files in Subversion.

GitHub maintains a repository of gitignore files. They have language, project, operating system and editor specific gitignore files. A good gitignore file is for a perl project is probably a combination of several of these files.

.gitignore for Git users

As Git is currently the most widely used version control system for Perl-based project, let's see a useful .gitignore file with some explanation.

If you have a Git repository you can easily tell it which files to ignore. You create a file called .gitignore in the root directory of your repository and then follow the instructions on gitignore. If you'd like to understand more deeply, then you can also read the explanation about .gitignore.

In this repository there is a sample gitignore file for Perl developers I've repeated here:

/blib/
/.build/
_build/
cover_db/
inc/
Build
!Build/
Build.bat
.last_cover_stats
/Makefile
/Makefile.old
/MANIFEST.bak
/META.yml
/META.json
/MYMETA.*
nytprof.out
/pm_to_blib
*.o
*.bs

I'd probably add the following:

# If MANIFEST.SKIP is used:
/MANIFEST

# Mac Finder generated:
.DS_Store

# vim swap files:
*.swp

# random backup files:
*.bak

# Code::TidyAll Test::Code::TidyAll cache:
/.tidyall.d/

In addition there are some module specific things you might want to add to the .gitignore file:

# Dancer puts the session objects in the session directory and the logs in the logs/ directory
/session
/logs

If you have additions or more recommendation, you can fork the repository of this site and send me a pull-request. Look for the big green button at the top of the page.