Add the deploy task and mdBook.
This commit is contained in:
parent
06899c42c7
commit
8fc2a1d059
|
@ -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"]
|
||||
|
|
|
@ -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]
|
|
@ -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/
|
|
@ -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)
|
|
@ -0,0 +1,5 @@
|
|||
# Changelog
|
||||
|
||||
## 0.1.0 (2022-11-03)
|
||||
|
||||
* First Hooked version!
|
|
@ -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/
|
|
@ -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}}
|
||||
```
|
|
@ -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
|
||||
```
|
|
@ -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.
|
|
@ -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
|
|
@ -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.
|
|
@ -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
|
|
@ -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
|
|
@ -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/
|
Loading…
Reference in New Issue