export-ignore files an end-user doesn't need

[dangoodman]

It's a common practice to mark files which end-users don't need with export-ignore git attribute. It usually includes tests, docs, examples, etc; everything required for development but not needed for usage. For example, no users of a WordPress plugin with PUC seem to be interested in `composer.json' and '.gitignore' files.

Files marked with export-ignore won't appear in 'dist' packages such as ones on the releases github page or installed with composer --prefer-dist.

[YahnisElsts]

I would agree with removing .gitignore, other dotfiles, and tests (if there were any). However, I think that removing documentation, examples and the DebugBar panel would be more trouble than it's worth.

I think the main question is this: are releases and Composer packages intended for developers, or for end users and production systems? Personally, I think a release should include everything that you need to successfully get started with the library. This includes basic documentation and setup/configuration tools (I would categorize the DebugBar panel as one of these as it's very useful for diagnosing various configuration problems).

[YahnisElsts]

But why stop there? Let's see what other projects do!

Top 30 Packages on Packagist.org

• psr/log : No .gitattributes.
• symfony/polyfill-mbstring : No .gitattributes.
• paragonie/random_compat : Removes tests, dotfiles and docs.
• symfony/console : No .gitattributes.
• doctrine/instantiator : Removes tests and dotfiles, but not docs or license.
• monolog/monolog : Removes tests, dotfiles and advanced docs, but not README.md or other *.md files in the project root.
• psr/http-message : No .gitattributes.
• symfony/event-dispatcher : No .gitattributes.
• symfony/debug : No .gitattributes.
• guzzlehttp/guzzle : Removes tests, advanced docs, dotfiles, build scripts. Leaves the README.md, LICENSE and other *.md files in the project root.
• guzzlehttp/psr7 : Removes tests and dotfiles.
• symfony/finder : No .gitattributes.
• doctrine/inflector : Removes tests and dotfiles. Leaves *.md and /docs.
• symfony/process : No .gitattributes.
• phpunit/phpunit : Removes build scripts, leaves tests, *.md, dotfiles and a bunch of other stuff.
• phpdocumentor/reflection-docblock : Removes tests, examples, dotfiles.
• phpunit/php-code-coverage : Has a .gitattributes file but doesn't use export-ignore. Leaves tests, docs, etc.
• webmozart/assert : Removes tests and dotfiles.
• phpunit/php-file-iterator : Has a .gitattributes file but doesn't use export-ignore.
• sebastian/diff : No .gitattributes.
• phpunit/php-token-stream : Has a .gitattributes file but doesn't use export-ignore.
• guzzlehttp/promises : Removes tests and dotfiles. Leaves the README.md, LICENSE and other *.md files in the project root.
• sebastian/comparator : No .gitattributes.
• doctrine/lexer : No .gitattributes. Has /docs and /tests.
• phpunit/php-timer : Has a .gitattributes file but doesn't use export-ignore.
• swiftmailer/swiftmailer : Removes a /docs/notes subdirectory (probably internal documentation?) but leaves everything else including tests.
• phpspec/prophec : Removes tests, dotfiles, and CONTRIBUTING.md. Leaves other basic docs.
• sebastian/exporter : No .gitattributes.
• sebastian/version : Has a .gitattributes file but doesn't use export-ignore.
• sebastian/recursion-context : No .gitattributes.

A lot of the top packages have the same authors, so they probably don't count as fully independent projects. So let's look at the next 10 most popular packages that are not part of Symfony, Doctrine, PSR, or directly authored by @sebastianbergmann.

10 More Popular Packages

• myclabs/deep-copy : Removes tests and dotfiles. Leaves /docs and basic documentation.
• nikic/php-parser : No .gitattributes. Has tests, a /doc directory, etc.
• nesbot/carbon : Removes tests, dotfiles and build scripts.
• vlucas/phpdotenv : Removes tests, dotfiles and README.md. Leaves LICENSE.txt.
• ramsey/uuid : Removes tests, docs, dotfiles and binary utilities. Leaves *.md files and the license.
• league/flysystem : Removes tests, docs, dotfiles, build scripts and most *.md files. Leaves the license.
• fzaninotto/faker : No .giattributes.
• psy/psysh : No .gitattributes.
• twig/twig : No .gitattributes.
• jakub-onderka/php-console-highlighter : No .gitattributes.

Summary

• 57% (23 of 40) don't use export-ignore or have no .gitattributes file.
• 43% (17) use export-ignore.
  • 40% (16) remove tests.
  • 38% (15) remove dotfiles, e.g. .gitignore and .editorconfig.
  • 15% (6) remove a docs subdirectory or equivalent.
  • 8% (3) remove README.md and other basic documentation.
  • Note: The above numbers don't add up to 43% because some projects fall under more than one category.
• None remove the license from release archives.
• None remove composer.json, but some do remove composer.lock.

[YahnisElsts]

Additional discussion with lots of references to/from other projects: symfony/symfony#6605

[dangoodman]

Thank you for the research. It seems the question is not that simple as I thought.

I'd want to describe the problem I'm trying to solve. Maybe you or somebody else reading this have some tips on it.

Basically, a software library has the following stages/mindsets:

1. Development. When somebody wants to change the library he/she obviously needs all the files.
2. Usage. If one wants to use the library in another product and understand how it works, it would be useful to have docs and tests for sure. Other dev-only files such as dot-files maybe omitted.
3. Deployment/distribution. An end-user does only need a "core" product. In compiled languages that might be a .dll/.so or .exe/elf file, i.e. without any sources at all.

I'm trying to have a nice way to make out the 3rd stage. Removing dev files with a custom build script is possible but doesn't look good unless the script is included in the library itself. Nobody knows better than author of a product, what files aren't required to be run on an end-user machine.

While it seems a common practice is to use export-ignore for the 2nd stage. I personally don't care about it since don't see a real problem here. I'm ok with all those dot-files and internal docs while integrating a library with my product.

Anyway, I can just keep the proposed .gitattributes in my fork of PUC until I find a better solution to solve the problem.

[YahnisElsts]

During my research I noticed some relevant discussion in the Composer repository. It seems Composer's contributors are not interested in adding an option to remove dev files. As a result, someone created a Composer plugin that does that. Perhaps you'll find it useful?
https://github.com/octolab/Cleaner/

[dangoodman]

Thank you. Will check.