From 669aca75dac17c55144ba82d8a4e276435ad6ae3 Mon Sep 17 00:00:00 2001 From: Vytautas Strimaitis Date: Sun, 24 Jul 2022 23:32:30 +0300 Subject: [PATCH] Update README --- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0da1ba2..f34c0d9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,45 @@ -# poetry-pre-commit-plugin -Poetry plugin for automatically installing pre-commit hook when it is added to a project +# Poetry pre-commit Plugin + +A [Poetry](https://python-poetry.org/) plugin for automatically installing git +pre-commit hooks whenever `pre-commit` is specified as a dependency of the +project. + +## Motivation + +Personally I find that running `pre-commit install` every time I start working +on a new repository is very easy to forget - there have been numerous occasions +where I'd forget this step, commit some changes only to be surprised later on +by failing CI checks :grinning: This plugin aims to solve this issue by doing +this small step for me automatically behind the scenes. + +## Installation + +The plugin requires Poetry version `1.2.0b1` or above. Since this is still a +pre-release version, you have to specify it explicitly when installing: + +``` +$ curl -sSL https://install.python-poetry.org | python3.9 - --version 1.2.0b3 +``` + +Once a valid version of Poetry is set up, you can install the plugin like so: + +``` +$ poetry self add poetry-pre-commit-plugin +``` + +For more in-depth information, please refer to +[Poetry's docs](https://python-poetry.org/docs/master/plugins/). + +## Usage + +There's no way to use this plugin explicitly - it will work behind the scenes +after you run either `poetry install` or `poetry add`. In either of those cases, +the plugin will check the following conditions: + +1. Is the project inside a git repository? +2. Is `pre-commit` listed as a dependency of the project (or, in the case of + `poetry add` - was it just added)? +3. Has the pre-commit hook **not** been activated yet (i.e. the file + `.git/hooks/pre-commit` does not exist)? + +If all conditions are met, the plugin will run `pre-commit install` for you.