whisky

Whisky Project Introduction

Overview

Whisky is a straightforward, framework-agnostic command-line interface (CLI) tool designed to help manage and enforce git hooks across team members working on PHP projects. Git hooks are useful for maintaining code quality by ensuring that the code that gets committed meets organizational standards. However, because the .git/hooks directory is not included in the git tree, it may be difficult to have all team members use the same checks. Whisky addresses this issue by providing a consistent way to apply git hooks throughout your team.

Installation

Whisky requires only php^8.1 to function. It can be installed via Composer with:

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

This method ensures that every developer accessing your project will have Whisky available. Additionally, Whisky can be installed globally, though this would also require each developer to install it globally on their own setup.

Usage

Once installed, Whisky creates a whisky.json file in the root directory of your project. This file defines the git hooks you wish to apply:

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

Users can update or modify the hooks by editing the whisky.json file. After changes, it's necessary to run ./vendor/bin/whisky update to implement updates in the .git/hooks directory.

Advanced Features

• Hook Arguments: Git hooks may need arguments, such as paths to commit messages. Whisky allows the optional use of $1 to capture such arguments.
• Automated Hook Updates: Including Whisky in Composer scripts (e.g., post-install-cmd) ensures all contributors use the same hooks.
• Skipping Hooks: To bypass hooks for specific commits, use git --no-verify or ./vendor/bin/whisky skip-once.
• Disabling Hooks: Hooks can be disabled by listing them in the disabled array of the whisky.json.

Advanced Usage

For complex workflows, the creation of a scripts directory is encouraged, allowing the execution of scripts in various languages. Ensure scripts are marked as executable using:

chmod +x ./scripts/*

Testing

For testing purposes, Whisky provides commands for running tests and examining hook performance without needing to commit changes:

# Run test suite
composer test

# Test hook without a dummy commit
git hook run pre-commit

Troubleshooting

If hooks run twice, it might be due to Whisky being installed both globally and locally. In such cases, uninstalling the hooks from either one might solve the problem:

whisky uninstall -n

Contributing and Security

Contributors to Whisky should avoid building the binary, as it is created when a release is tagged. For more details, consult the project's CONTRIBUTING guide. Security vulnerabilities should be reported in accordance with the provided security policy.

Acknowledgements

Special thanks to EXACTsports for supporting Whisky's development and to primary contributor Len Woodward alongside all other contributors.

License

Whisky is licensed under the MIT License. More information is available in the project's LICENSE file.