The LeanPackageValidator is an utility tool that validates a project/micro-package for its leanness. A project/micro-package is considered lean when its common repository artifacts won't be included in release assets.
The LeanPackageValidator CLI should be installed globally through Composer.
composer global require stolt/lean-package-validatorMake sure that the path to your global vendor binaries directory is in your $PATH. You can determine the location of your global vendor binaries directory via composer global config bin-dir --absolute. This way the lean-package-validator executable can be located.
Since the default name of the CLI is quite a mouthful, an alias which can be placed in ~/.aliases, ~/.zshrc or the like might come in handy. The alias shown next assumes that $COMPOSER_HOME is ~/.config/composer and not ~/.composer.
alias lpv='~/.config/composer/vendor/bin/lean-package-validator $@'The LeanPackageValidator also can be installed locally to a project which allows further utilisation via Composer scripts.
composer require --dev stolt/lean-package-validatorAs of release v1.9.0 it's also possible to install and use the LeanPackageValidator via a PHAR file.
Therefor download a released version i.e. v1.9.0 and move it to /usr/local/bin as shown next.
wget https://github.com/raphaelstolt/lean-package-validator/releases/download/v1.9.0/lean-package-validator.phar
mv lean-package-validator.phar /usr/local/bin/lean-package-validatorRun the LeanPackageValidator CLI within or against a project/micro-package directory and it will validate the export-ignore entries present in a .gitattributes file against a set of common repository artifacts. If no .gitattributes file is present it will suggest to create one.
lean-package-validator validate [<directory>]The --enforce-strict-order option will enforce a strict order comparison of export-ignores in the .gitattributes file and fail validation if the order differs. Per default the order comparison is done in a non strict fashion.
lean-package-validator validate [<directory>] --enforce-strict-orderThe --create|-c option creates an .gitattributes file if nonexistent.
lean-package-validator validate [<directory>] --createThe --overwrite|-o option overwrites an existing .gitattributes file when there are any export-ignore entries missing. Using this option on a directory with a nonexistent .gitattributes file implicates the --create option.
lean-package-validator validate [<directory>] --overwriteThe --glob-pattern option allows you to overwrite the default pattern used to match common repository artifacts. The amount of pattern in the grouping braces is expected to be >1. As shown next this utility could thereby also be used for projects (i.e. Python) outside of the PHP ecosystem.
lean-package-validator validate [<directory>] --glob-pattern '{.*,*.rst,*.py[cod],dist/}'The default pattern is {.*,*.lock,*.txt,*.rst,*.{md,MD},*.xml,*.yml,appveyor.yml,box.json,captainhook.json,*.dist.*,*.dist,{B,b}uild*,{D,d}oc*,{T,t}ool*,{T,t}est*,{S,s}pec*,{E,e}xample*,LICENSE,{{M,m}ake,{B,b}ox,{V,v}agrant,{P,p}hulp}file,RMT}*.
The --glob-pattern-file option allows you to load patterns, which should be used to match the common repository artifacts, from a given file. You can put a .lpv file in the repository which will be used per default and overwrite the default pattern. The structure of such a glob pattern file can be taken from the example directory or be created via lean-package-validator init.
lean-package-validator validate [<directory>] --glob-pattern-file /path/to/glob-pattern-fileThe --keep-license option will allow a license file in the release/dist archive file which is per default ommitted.
lean-package-validator validate [<directory>] --keep-licenseThe --align-export-ignores|-a option will align the created or overwritten export-ignores for a better readability.
lean-package-validator validate [<directory>] --align-export-ignores --createThe --enforce-alignment option will enforce a strict alignment of export-ignores in the .gitattributes file and fail validation if they aren't aligned. Per default no alignment is enforced.
The --validate-git-archive option will validate that no common repository artifacts slip into the release/dist archive file. It will do so by creating a temporary archive from the current Git HEAD and inspecting its content. With a set --keep-license option a license file becomes mandatory and will fail the archive validation if not present.
lean-package-validator validate [<directory>] --validate-git-archiveThe --diff option will show a visual diff betweeen the actual and expected .gitattributes content.
lean-package-validator validate --diff
The present .gitattributes file is considered invalid.
Would expect the following .gitattributes file content:
--- Original
+++ Expected
@@ -7,9 +7,8 @@
.github/ export-ignore
.gitignore export-ignore
.gitmessage export-ignore
.php-cs-fixer.php export-ignore
-.phpunit.result.cache export-ignore
+.idea/ export-ignore
bin/application-version export-ignore
bin/lean-package-validator.phar export-ignore
bin/release-version export-ignoreThe init command will create an initial .lpv file with the default patterns used to match common repository artifacts.
lean-package-validator init [<directory>]The --overwrite|-o option overwrites an existing .lpv file.
To avoid that changes coming from contributions or own modifications slip into release/dist archives it might be helpful to use a guarding Composer script, which will be available at everyone's fingertips.
By adding the following to the project/micro-package its composer.json the .gitattributes file can now be easily validated via composer validate-gitattributes.
{
"scripts": {
"validate-gitattributes": "lean-package-validator validate"
},
}For utilising a dedicated GitHub Action have a look at the documentation over here.
composer lpv:testThis library and its CLI are licensed under the MIT license. Please see LICENSE.md for more details.
Please see CHANGELOG.md for more details.
Please see CONTRIBUTING.md for more details.