feat: add basic documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,30 @@
+name: Deploy Docs
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [ 
+
+
+    "!ENV scalar",
+    "!ENV sequence",
+    "!relative scalar",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+  ]
+}

docs/examples.md

@@ -0,0 +1,77 @@
+# Examples
+
+## `commitlint`
+
+*This guide will help you in the setup of a hook a hook for linting your commits with [commitlint](https://github.com/conventional-changelog/commitlint)*
+
+### Prerequisite for Commitlint
+
+- You have installed `Gookme`
+- You have installed and configured [commitlint](https://github.com/conventional-changelog/commitlint)
+- You have setup `Gookme` using `gookme init` (see [get started](getting-started.md) if needed)
+
+### Hook for Commitlint
+
+In the global hooks folder of your project `hooks/commit-msg.json` add the following configuration :
+
+```js title="hooks/commit-msg.json"
+{
+    "steps": [
+    // ...
+    // your other steps
+    {
+        "name": "commit lint",
+        "command": "cat {args} | ./node_modules/@commitlint/cli/cli.js"
+    }
+    // ...
+    // your other steps
+    ]
+}
+```
+
+## `eslint`
+
+*This guide will help you in the setup of a hook for linting your code with [eslint](https://eslint.org/)*
+
+### Prerequisite for Eslint
+
+- You have installed `mookme`
+- You have installed and configured [eslint](https://eslint.org/)
+- You have setup `mookme` using `npx mookme init` (see [getting started](getting-started.md) if needed)
+
+### Hook for Eslint
+
+- In the hooks folder of the package you want to lint with `eslint` `<project-root>/<package>/.hooks/commit-msg` add
+the following configuration :
+
+```js title="hooks/commit-msg.json"
+{
+    "steps": [
+    // ...
+    // your other steps
+    {
+        "name": "eslint",
+        "command": "./node_modules/eslint/bin/eslint.js ."
+    }
+    // ...
+    // your other steps
+    ]
+}
+```
+
+*Alternative: setup a `npm` script and directly invoke `eslint` in the command field :*
+
+```js title="hooks/commit-msg.json"
+{
+    "steps": [
+    // ...
+    // your other steps
+    {
+        "name": "eslint",
+        "command": "npm run lint"
+    }
+    // ...
+    // your other steps
+    ]
+}
+```

docs/features.md

@@ -0,0 +1,97 @@
+# Features
+
+## Reusable steps
+
+`Gookme` provides you with step-sharing features, allowing you to declare shared step example, and to use them in your steps.
+
+Given a project directory such as this:
+
+``` title="Project structure"
+project-root
+|--- hooks
+    |--- shared
+        |--- flake8.json
+|--- packages
+    |--- some-package
+        |--- hooks
+            |--- pre-commit.json
+```
+
+!!! tip
+    The `hooks/shared` folder is automatically generated with a `.gitkeep` file by `gookme init`.
+
+You can declare a step in `hooks/shared/flake8.json` ...
+
+```json title="hooks/shared/flake8.json"
+{
+  "name": "Ensure Style (flake8)",
+  "command": "flake8 $(python-module) --ignore E203,W503 --max-line-length 90",
+  "onlyOn": "**/*.py"
+}
+```
+
+... and then re-use it in `some-package/hooks/pre-commit.json` with the `from` keyword:
+
+```json title="some-package/hooks/pre-commit.json"
+{
+  "steps": [
+    {
+      "from": "flake8"
+    },
+    ... // some other steps
+  ]
+}
+```
+
+## Writing and using utils scripts
+
+It is possible to declare some scripts in the project root `Gookme` hooks folder, and then use them directly in the commands invoked by the steps.
+
+Given a project directory such as this:
+
+```sh title="Project structure"
+project-root
+|--- .mookme.json
+|--- hooks
+    |--- partials
+        |--- pylint-changed-files
+ |--- packages
+    |--- some-package
+        |--- .hooks
+            |--- pre-commit.json
+```
+
+*Here is how the `python-changed-files` script looks like*
+
+```bash title="project-root/hooks/partials/pylint-changed-files"
+#!/usr/bin/env bash
+git --no-pager diff --cached --name-only --diff-filter=AM --relative -- "***.py" | tr '\n' '\0' | xargs -0 "$@"
+```
+
+!!! tip
+    The `hooks/partials` is automatically generated with a `.gitkeep` file by `gookme init`.
+
+One can declare a script in flake8 (don't forget to `chmod+x`) and then re-use it in `some-package/hooks/pre-commit.json` by directly invoking the script's name:
+
+```json title="some-package/hooks/pre-commit.json"
+{
+  "steps": [
+    {
+      "name": "Run pylint but only on changed files",
+      "command": "python-changed-files pylint"
+    },
+    ... // some other steps
+  ]
+}
+```
+
+## Use a range of commits
+
+Using the Gookme CLI, it is possible to invoke a set of hooks and steps selected using the files changed between two git references.
+
+````bash
+gookme run -t pre-commit --from HEAD~1 --to f9ff43
+gookme run -t pre-commit --from HEAD~25 --to d58688dd611ef01079f61ebae36df0ce8c380ddb
+````
+
+You can find more details about these options on the [gookme run reference](reference.md#gookme-run) page.

docs/getting-started.md

@@ -0,0 +1,148 @@
+# Getting started
+
+## Installation
+
+=== "Linux"
+
+    ``` c
+    #include <stdio.h>
+
+    int main(void) {
+      printf("Hello world!\n");
+      return 0;
+    }
+    ```
+
+=== "MacOS"
+
+    ``` c++
+    #include <iostream>
+
+    int main(void) {
+      std::cout << "Hello world!" << std::endl;
+      return 0;
+    }
+    ```
+=== "Windows"
+
+    ``` c++
+    #include <iostream>
+
+    int main(void) {
+      std::cout << "Hello world!" << std::endl;
+      return 0;
+    }
+    ```
+
+## Configuration
+
+Gookme will automatically detect the `hooks` folder across your repository and trigger the command related to your current VCS state.
+
+Hence it only requires a very minimal configuration, as most of this is defined by where you place your `hooks` folders, and what you put in them.
+
+### Setup Git to run Gookme
+
+To setup Gookme, you need to create scripts in the `.git/hooks` folder, or add a few lines in the existing ones. **This is done automatically by running the `init` command**
+
+``` sh title="Initialize Gookme with all Git hooks"
+gookme init --all
+```
+
+### Selectively setup Gookme
+
+If you want to only setup the hooks for a specific hook type, you can use the `--type` option of the `gookme init` command.
+
+```bash title="Initialize Gookme with pre-commit and commit-msg hooks"
+gookme init --type pre-commit,commit-msg
+```
+
+### Removing Gookme from your Git hooks scripts
+
+If you want to remove Gookme from your Git hooks scripts, you can use the `clean` command.
+
+```bash title="Remove Gookme from your Git hooks scripts"
+gookme clean
+```
+
+This will remove all the lines added by Gookme in your Git hooks scripts.
+
+## Writing your hooks
+
+### Global structure of your project hooks
+
+`Gookme` is designed for monorepos, hence it assumes your project has a root folder where global hooks can be defined, and multiple packages where you can define per-package hook.
+
+!!! tip
+    Hooks are written in a folder `hooks` located at the root of your project and at the root of your packages' folders.
+
+
+    **When using `Gookme` in a monorepo, you will have a project structure following this :**
+
+    ```bash
+    <root> # where your .git is located
+    |- hooks # will always be executed when you commit
+    |  |- pre-commit.json # will be executed with the pre-commit git hook
+    |  |- commit-msg.json  # will be executed with the commit-msg git hook
+    |  |- prepare-commit-msg.json
+    |  |- post-commit.json
+    |- packages
+    |  |- package A
+    |  |  |- hooks # will be executed if you commit changes on package A
+    |  |  |  |- pre-commit.json
+    |  |  |  |- post-commit.json
+    |  |- package A
+    |  |  |- hooks # will be executed if you commit changes on package B
+    |  |  |  |- pre-commit.json
+    ```
+
+With `Gookme`, your hooks are stored in JSON files called `{hook-type}.json` where the hook type is one of the available git hooks, eg :
+
+- `pre-commit`
+- `prepare-commit-msg`
+- `commit-msg`
+- `post-commit`
+- `post-merge`
+- `post-rewrite`
+- `pre-rebase`
+- `post-checkout`
+- `pre-push`
+
+!!! warning
+    If the command executed by a hook fails, it will prevent the git command to be executed. We recommend you to use the pre-receive hooks carefully, with relatively safe commands, otherwise you might prevent your team for doign stuff like `git pull` or `git fetch`.
+
+
+### How will Gookme decide which hooks to run ?
+
+1. Gookme will pick up files concerned by an execution. The result of this step is a list of relative paths from the root of the repository.
+
+2. For each folder where a `hooks` folder is found, Gookme will assess if there are file paths in the previous list matching the relative path to this folder from the root of the repository.
+
+3. Other selections (`onlyOn` for instance) are applied on each step of each package, based on the list of paths attached to the package and it's steps.
+
+### Example of hook file
+
+Your hooks are defined in simple json files.
+
+- For complete reference, see the [JSON hooks reference](reference.md#hook-files)
+- For specific hook examples, see the [recipes](examples.md)
+
+A hook defines a list of `steps`, which are basically commands to run, with a name for proper display. A few configuration options are available, but the minimal requirement is `name` and `command`.
+
+Here is an example that will run your commit message using `commitlint`.
+
+``` js title="hooks/commit-msg.json"
+{
+    "steps": [{
+        "name": "Lint commit message",
+        "command": "commitlint lint --message $1"
+    }]
+}
+```
+
+!!! tip
+    When writing package-scoped hooks, the current working directory assumed by `Gookme` is the folder where this package's `hooks'` folder is located
+
+!!! warning
+    The token `$1` in the hook command is replaced with the hook arguments when the command is executed. See [the  Git documentation on hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
+
+**More examples to [get you started](examples.md)**!