Add the deploy task and mdBook.

This commit is contained in:
Bauke 2022-11-03 13:59:53 +01:00
parent 06899c42c7
commit 8fc2a1d059
Signed by: Bauke
GPG Key ID: C1C0F29952BCF558
14 changed files with 314 additions and 0 deletions

View File

@ -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"]

14
hooked-book/book.toml Normal file
View File

@ -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]

View File

@ -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/

View File

@ -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)

View File

@ -0,0 +1,5 @@
# Changelog
## 0.1.0 (2022-11-03)
* First Hooked version!

View File

@ -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/

View File

@ -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 <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}}
```

View File

@ -0,0 +1,18 @@
# Run
The `run` command manually runs configured hooks.
```
$ hooked run --help
Manually run hooks
Usage: hooked run [OPTIONS] <HOOK_TYPE>
Arguments:
<HOOK_TYPE> The hook type to run [possible values: pre-commit]
Options:
-c, --config <CONFIG> Path to a Hooked configuration [default: Hooked.toml]
-h, --help Print help information
-V, --version Print version information
```

View File

@ -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 <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.

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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/