whisky: A PHP repository from ProjektGopher

Introduction

Whisky is the simplest, framework agnostic, CLI tool for managing and enforcing a php project's git hooks across an entire team.

Git hooks are a fantastic tool to ensure that code hitting version control satisfies your org's code quality standards. However, .git/hooks is not included in your git tree. This makes it impractical to have all contributors to a repository use the same checks with the same settings.

Installation

Whisky's only dependency is php^8.1.

You can install the package via composer:

composer require --dev projektgopher/whisky
./vendor/bin/whisky install

This is the recommended method, as every developer on your project will have access to the tool.

Global Installation

Whisky can be installed globally, however this means that any developer on your project will also need it installed globally if they want to use it.

composer global require projektgopher/whisky
whisky install

If Whisky is installed both globally, and locally, on a project the version that's run will depend on how the command is invoked.

Usage

The install command will create a whisky.json file in your project root:

// whisky.json
{
  "disabled": [],
  "hooks": {
    "pre-commit": [
      "./vendor/bin/pint --dirty"
    ],
    "pre-push": [
      "php artisan test"
    ]
  }
}

For a complete list of supported git hooks, see the Git Documentation.

Caution

all hooks are evaluated as-is in the terminal. Keep this in mind when committing anything involving changes to your whisky.json.

Adding or removing any hooks (not individual commands) to your whisky.json file should be followed by ./vendor/bin/whisky update to ensure that these changes are reflected in your .git/hooks directory.

Working With Hook Arguments

Some hooks in git are passed arguments.

The commit-msg hook is a perfect example. It's passed the path to git's temporary file containing the commit message, which can then be used by scripts like npm's commitlint to allow or prevent commit messages that might not conform to your project's standards.

To use this argument that git passes, you can optionally include $1 in your array of commands. (You should wrap it in escaped double quotes to prevent odd behavior due to whitespace)

// whisky.json
// ...
  "commit-msg": [
    "npx --no -- commitlint --edit \"$1\""
  ]
// ...

Important

For commitlint specifically, you'll need to follow the instructions in their documentation, as it will require extra packages and setup to run in your project.

Automating Hook Updates

While we suggest leaving Whisky as an 'opt-in' tool, by adding a couple of Composer scripts we can ensure consistent git hooks for all project contributors. This will force everyone on the project to use Whisky:

// composer.json
// ...  
  "scripts": {
    "post-install-cmd": [
      "whisky update"
    ],
    "post-update-cmd": [
      "whisky update"
    ]
  }
// ...

Skipping Hooks

Sometimes you need to commit or push changes without running your git hooks, like when handing off work to another computer. This can usually be done using git's native --no-verify flag.

git commit -m "wip" --no-verify

However, some git actions don't support this flag, like git merge --continue. In this case, running the following command will have the exact same effect.

./vendor/bin/whisky skip-once

Tip

by adding alias whisky=./vendor/bin/whisky to your bash.rc file, you can shorten the length of this command.

Disabling Hooks

Adding a hook's name to the disabled array in your whisky.json will disable the hook from running. This can be useful when building out a workflow that isn't ready for the rest of the team yet.

Advanced Usage

For anything more complicated than simple terminal commands it's recommended to create a scripts directory in your project root. This comes with the added benefit of allowing you to run scripts written in any language.

// whisky.json
// ...
  "pre-push": [
    "composer lint",
    "rustc ./scripts/complicated_thing.rs"
  ]
// ...

Note

When doing this, make sure any scripts referenced are executable:

chmod +x ./scripts/*

Testing

# Run test suite
composer test

# Test hook without having to make a dummy commit
git hook run pre-commit

Troubleshooting

If you've installed Whisky both locally and globally, and your hooks are being run twice, try uninstalling whisky from your hooks for one of those installations.

# Remove global Whisky hooks, leaving the local ones,
# while keeping `whisky.json` in the project root.
whisky uninstall -n

Contributing

Note

Don't build the binary when contributing. The binary will be built when a release is tagged.

Please see CONTRIBUTING for more details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

A big "Thank You" to EXACTsports for supporting the development of this package.

License

The MIT License (MIT). Please see License File for more information.

ProjektGopher/whisky