From 8fc2a1d059ee0b84b4666aeb816c3fadf15355bb Mon Sep 17 00:00:00 2001 From: Bauke Date: Thu, 3 Nov 2022 13:59:53 +0100 Subject: [PATCH] Add the deploy task and mdBook. --- Makefile.toml | 6 ++ hooked-book/book.toml | 14 ++++ hooked-book/source/README.md | 29 ++++++++ hooked-book/source/SUMMARY.md | 13 ++++ hooked-book/source/changelog/README.md | 5 ++ hooked-book/source/cli/README.md | 19 +++++ hooked-book/source/cli/install.md | 22 ++++++ hooked-book/source/cli/run.md | 18 +++++ hooked-book/source/cli/uninstall.md | 18 +++++ hooked-book/source/configuration/README.md | 47 ++++++++++++ hooked-book/source/getting-started/README.md | 7 ++ .../source/getting-started/creating-hooks.md | 74 +++++++++++++++++++ .../source/getting-started/installation.md | 18 +++++ .../getting-started/installing-hooks.md | 24 ++++++ 14 files changed, 314 insertions(+) create mode 100644 hooked-book/book.toml create mode 100644 hooked-book/source/README.md create mode 100644 hooked-book/source/SUMMARY.md create mode 100644 hooked-book/source/changelog/README.md create mode 100644 hooked-book/source/cli/README.md create mode 100644 hooked-book/source/cli/install.md create mode 100644 hooked-book/source/cli/run.md create mode 100644 hooked-book/source/cli/uninstall.md create mode 100644 hooked-book/source/configuration/README.md create mode 100644 hooked-book/source/getting-started/README.md create mode 100644 hooked-book/source/getting-started/creating-hooks.md create mode 100644 hooked-book/source/getting-started/installation.md create mode 100644 hooked-book/source/getting-started/installing-hooks.md diff --git a/Makefile.toml b/Makefile.toml index 19332cb..d133c40 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -59,3 +59,9 @@ args = ["build", "hooked-book"] extend = "book" dependencies = ["clean-book"] args = ["serve", "hooked-book"] + +[tasks.deploy-book] +workspace = false +dependencies = ["build-book"] +command = "netlify" +args = ["deploy", "-d", "hooked-book/book/html", "-p", "-s", "holllo-hooked"] diff --git a/hooked-book/book.toml b/hooked-book/book.toml new file mode 100644 index 0000000..f151838 --- /dev/null +++ b/hooked-book/book.toml @@ -0,0 +1,14 @@ +[book] +authors = ["Holllo"] +language = "en" +multilingual = false +src = "source" +title = "Hooked" + +[rust] +edition = "2021" + +[output.html] +git-repository-url = "https://git.bauke.xyz/Holllo/hooked" + +[output.linkcheck] diff --git a/hooked-book/source/README.md b/hooked-book/source/README.md new file mode 100644 index 0000000..6886b4a --- /dev/null +++ b/hooked-book/source/README.md @@ -0,0 +1,29 @@ +# Hooked 🪝 + +```toml +# Hooked.toml +[[pre_commit]] +name = "Cargo Check" +command = "cargo check" +``` + +```sh +# Install Hooked to ".git/hooks". +$ hooked install + +# Commit away! +$ git commit -m 'Start using Hooked!' +Hooked: Running 1 pre-commit hook. + ✓ Cargo Check +[main b386e59] Start using Hooked! + 1 file changed, 3 insertions(+) + create mode 100644 Hooked.toml +``` + +Hooked is a manager for [Git hooks][git-hooks]. It is language-agnostic (not built for any specific language or ecosystem), has a low barrier to entry (hooks can be one-liners in a configuration file) and is extensible (most of what Hooked does can be replaced through its configuration). + +If you've been convinced and would like to give it a shot, [Getting Started][getting-started] is the place to be. + +[getting-started]: ./getting-started/ +[git-hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks +[internals]: ./internals/ diff --git a/hooked-book/source/SUMMARY.md b/hooked-book/source/SUMMARY.md new file mode 100644 index 0000000..b2fbd43 --- /dev/null +++ b/hooked-book/source/SUMMARY.md @@ -0,0 +1,13 @@ +# Summary + +* [Hooked](./README.md) +* [Getting Started](./getting-started/README.md) + * [Installation](./getting-started/installation.md) + * [Creating hooks](./getting-started/creating-hooks.md) + * [The Git side of things](./getting-started/installing-hooks.md) +* [Configuration Reference](./configuration/README.md) +* [CLI Reference](./cli/README.md) + * [install](./cli/install.md) + * [run](./cli/run.md) + * [uninstall](./cli/uninstall.md) +* [Changelog](./changelog/README.md) diff --git a/hooked-book/source/changelog/README.md b/hooked-book/source/changelog/README.md new file mode 100644 index 0000000..b9429d8 --- /dev/null +++ b/hooked-book/source/changelog/README.md @@ -0,0 +1,5 @@ +# Changelog + +## 0.1.0 (2022-11-03) + +* First Hooked version! diff --git a/hooked-book/source/cli/README.md b/hooked-book/source/cli/README.md new file mode 100644 index 0000000..80f031e --- /dev/null +++ b/hooked-book/source/cli/README.md @@ -0,0 +1,19 @@ +# CLI Reference + +In the following chapters you will find the reference to all of Hooked's CLI subcommands. + +## Global Options + +These options can be used in all commands. + +| Option | Default | Description | +|--------|---------|-------------| +| `-c`, `--config` | Hooked.toml | Path to a Hooked configuration. | +| `-h`, `--help` | | Print help information. | +| `-V`, `--version` | | Print version information. | + +## Other + +Hooked checks for the [`NO_COLOR` environment variable][no-color] and will disable styling output if present. + +[no-color]: https://no-color.org/ diff --git a/hooked-book/source/cli/install.md b/hooked-book/source/cli/install.md new file mode 100644 index 0000000..14b723b --- /dev/null +++ b/hooked-book/source/cli/install.md @@ -0,0 +1,22 @@ +# Install + +The `install` command creates the scripts inside `.git/hooks`. + +```sh +$ hooked install --help +Install Hooked into ".git/hooks" + +Usage: hooked install [OPTIONS] + +Options: + --overwrite Overwrite existing files + -c, --config Path to a Hooked configuration [default: Hooked.toml] + -h, --help Print help information + -V, --version Print version information +``` + +Below is the default script template that Hooked uses, where `hook_type` is the type of hook to run (like `pre-commit`) and `config_path` is the `general.config` field from the parsed configuration. + +```sh +{{#include ../../../hooked-cli/source/templates/default.sh}} +``` diff --git a/hooked-book/source/cli/run.md b/hooked-book/source/cli/run.md new file mode 100644 index 0000000..f0272b4 --- /dev/null +++ b/hooked-book/source/cli/run.md @@ -0,0 +1,18 @@ +# Run + +The `run` command manually runs configured hooks. + +``` +$ hooked run --help +Manually run hooks + +Usage: hooked run [OPTIONS] + +Arguments: + The hook type to run [possible values: pre-commit] + +Options: + -c, --config Path to a Hooked configuration [default: Hooked.toml] + -h, --help Print help information + -V, --version Print version information +``` diff --git a/hooked-book/source/cli/uninstall.md b/hooked-book/source/cli/uninstall.md new file mode 100644 index 0000000..10d687f --- /dev/null +++ b/hooked-book/source/cli/uninstall.md @@ -0,0 +1,18 @@ +# Uninstall + +The `uninstall` command removes script files inside `.git/hooks`. + +```sh +hooked uninstall --help +Remove installed hooks + +Usage: hooked uninstall [OPTIONS] + +Options: + --all Remove hooks not installed by Hooked + -c, --config Path to a Hooked configuration [default: Hooked.toml] + -h, --help Print help information + -V, --version Print version information +``` + +By default Hooked will only remove scripts that have a `# Installed by Hooked.` line in them, using `--all` however will remove all script files. diff --git a/hooked-book/source/configuration/README.md b/hooked-book/source/configuration/README.md new file mode 100644 index 0000000..87bba2f --- /dev/null +++ b/hooked-book/source/configuration/README.md @@ -0,0 +1,47 @@ +# Configuration Reference + +Below you can find tables describing all the possible configuration you can do, as well as TOML examples below those tables showing what that configuration would look like. + +## General + +The `general` [table][toml-table] is for main Hooked configuration. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| config | String | Hooked.toml | The configuration file to use. If your configuration file isn't `Hooked.toml` you should set this accordingly. | +| directory | String | hooks | The directory Hooked looks in for anything related to files. For example: scripts, templates, etc. | + +```toml +[general] +config = "Hooked.toml" +directory = "hooks" +``` + +## Pre-commit + +Pre-commit hooks are defined using `pre_commit` [arrays of tables][toml-arrays-of-tables]. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| name | String | Unnamed Hook | The name of the hook, useful for figuring out which hook failed after it ran. | +| command[^command-and-script] | String | | A command to run when the hook is called. | +| script[^command-and-script] | String | | A script to run when the hook is called. This script should be executable and be located inside the configured general directory. | +| on_failure | String | stop | What to do when the hook task returns a non-zero status code. Can be either "continue" or "stop". | + +```toml +[[pre_commit]] +name = "Command Example" +command = "echo \"Hey, $USER!\"" + +[[pre_commit]] +name = "Script Example" +script = "example.sh" +on_failure = "continue" +``` + +## Footnotes + +[^command-and-script]: When both a command and script are defined in a hook, *only* the command will be run. + +[toml-table]: https://toml.io/en/v1.0.0#table +[toml-arrays-of-tables]: https://toml.io/en/v1.0.0#array-of-tables diff --git a/hooked-book/source/getting-started/README.md b/hooked-book/source/getting-started/README.md new file mode 100644 index 0000000..98c641d --- /dev/null +++ b/hooked-book/source/getting-started/README.md @@ -0,0 +1,7 @@ +# Getting Started + +To see the available ways to install Hooked, see the [Installation](./installation.md) chapter. + +The basics of making hooks is explained in [Creating Hooks](./creating-hooks.md). + +And if you already have a configuration set up, head to [the Git side of things](./installing-hooks.md) chapter. diff --git a/hooked-book/source/getting-started/creating-hooks.md b/hooked-book/source/getting-started/creating-hooks.md new file mode 100644 index 0000000..9129dec --- /dev/null +++ b/hooked-book/source/getting-started/creating-hooks.md @@ -0,0 +1,74 @@ +# Creating hooks + +All of Hooked's configuration is done inside the `Hooked.toml` file. It should be placed inside the same directory your `.git` directory is. + +``` +your-awesome-project +├── Hooked.toml <- ! +├── .git <- ! +│   └── ... +├── source +│ └── ... +└── ... +``` + +Inside `Hooked.toml`, hooks are defined as [arrays of tables][toml-arrays-of-tables] with a name (optional but highly encouraged) and either a command or script. + +A simple pre-commit hook is defined like the following: + +```toml +[[pre_commit]] +name = "Hook name, optional but highly encouraged" +command = "echo \"Hey, $USER!\"" +``` + +To test that this works, use the [run CLI command][cli-run] and you should see something like this. + +```sh +$ hooked run pre-commit +Hooked: Running 1 pre-commit hook. + ✓ Hook name, optional but highly encouraged +``` + +> To see what happens when a command fails, append `&& exit 1` to your configured command and run it again. + +If you want to run a script, create a `hooks` directory and place your script there. Then in your configuration file use the "script" field for your hook. Make sure that your script is executable! + +```diff +[[pre_commit]] +name = "Hook name, optional but highly encouraged" +command = "cargo test" ++ ++ [[pre_commit]] ++ name = "A script hook" ++ script = "run-tests.sh" +``` + +> Defining both a command and a script for a hook will make *only* the command run. + +The directory Hooked looks in can be configured via the `general.directory` field, should you wish to change it. + +```diff ++ [general] ++ # Use the same directory where Hooked.toml is. ++ directory = "." ++ +[[pre_commit]] +name = "Hook name, optional but highly encouraged" +command = "echo \"Hey, $USER!\"" + +[[pre_commit]] +name = "A script hook" +script = "run-tests.sh" +``` + +--- + +For a full list of everything you can configure in `Hooked.toml` see the [Configuration Reference][configuration]. And for the CLI there is the [CLI Reference][cli]. + +Those are the basics of creating hooks! Now to make Git use these hooks continue on to the next chapter. + +[cli]: ../cli/ +[cli-run]: ../cli/run.md +[configuration]: ../configuration/ +[toml-arrays-of-tables]: https://toml.io/en/v1.0.0#array-of-tables diff --git a/hooked-book/source/getting-started/installation.md b/hooked-book/source/getting-started/installation.md new file mode 100644 index 0000000..6e6f2c6 --- /dev/null +++ b/hooked-book/source/getting-started/installation.md @@ -0,0 +1,18 @@ +# Installation + +## Cargo + +With [Rust and Cargo][rustup-install] installed, Hooked can be installed from [Crates.io][crates-io]. + +``` +cargo install hooked-cli +``` + +[rustup-install]: https://www.rust-lang.org/learn/get-started +[crates-io]: https://crates.io/crates/hooked/cli + +## Binaries + +Precompiled `x86_64-unknown-linux-gnu` binaries are available on the [Releases page][releases]. + +[releases]: https://git.bauke.xyz/Holllo/hooked/releases diff --git a/hooked-book/source/getting-started/installing-hooks.md b/hooked-book/source/getting-started/installing-hooks.md new file mode 100644 index 0000000..499aa88 --- /dev/null +++ b/hooked-book/source/getting-started/installing-hooks.md @@ -0,0 +1,24 @@ +# The Git side of things + +In the previous chapter you manually tested hooks using the [CLI `run` command][cli-run]. Now to install those hooks and have Git use them, we'll use the [CLI `install` command][cli-install]. + +```sh +hooked install +``` + +What this command does is create the scripts inside the `.git/hooks` directory that Git will run whenever you do Git stuffs. By default, these scripts are a simple call to the [CLI `run` command][cli-run]. + +So unless you change anything in the hook templates, you only need to run this once, as it will read your current configuration any time those scripts get called. + +## Uninstalling hooks + +If at any point you want to remove the scripts from your `.git/hooks` directory, use the [CLI `uninstall` command][cli-uninstall]. + +```sh +hooked uninstall +``` + +[cli-install]: ../cli/install.md +[cli-run]: ../cli/run.md +[cli-uninstall]: ../cli/uninstall.md +[templating]: ../configuration/templating/