From b73a6e120122d1fe28e52c2b9b13eeed95f20a51 Mon Sep 17 00:00:00 2001
From: Corey Oordt <coreyoordt@gmail.com>
Date: Sun, 18 Aug 2024 16:08:48 -0500
Subject: [PATCH] Added hook suite documentation

---
 docs/reference/hooks.md | 95 ++++++++++++++++++++++++++++++-----------
 1 file changed, 69 insertions(+), 26 deletions(-)

diff --git a/docs/reference/hooks.md b/docs/reference/hooks.md
index d47943a7..d18a245c 100644
--- a/docs/reference/hooks.md
+++ b/docs/reference/hooks.md
@@ -7,20 +7,29 @@ comments: true
 ---
 # Hooks
 
-- Each global configuration of `setup_hooks`, `pre_commit_hooks`, and `post_commit_hooks` is a list of commands run in a shell
-- Explanation of the context passed into the environment
-- Run in sequentially
+## Hook Suites
 
-Order of operations
+A _hook suite_ is a list of _hooks_ to run sequentially. A _hook_ is either an individual shell command or an executable script.
 
-- Run setup hooks
-- Increment version
-- Change files
-- Run pre-commit hooks
-- commit and tag
-- Run post-commit hooks
+There are three hook suites: _setup, pre-commit,_ and _post-commit._ During the version increment process this is the order of operations:
 
-## Setup Hooks
+1. Run _setup_ hooks
+2. Increment version
+3. Change files
+4. Run _pre-commit_ hooks
+5. Commit and tag
+6. Run _post-commit_ hooks
+
+!!! Note
+
+    Don't confuse the _pre-commit_ and _post-commit_ hook suites with Git pre- and post-commit hooks. Those hook suites are named for their adjacency to the commit and tag operation.
+
+
+## Configuration
+
+Configure each hook suite with the `setup_hooks`, `pre_commit_hooks`, or `post_commit_hooks` keys.
+
+Each suite takes a list of strings. The strings may be individual commands:
 
 ```toml title="Calling individual commands"
 [tool.bumpversion]
@@ -30,28 +39,35 @@ setup_hooks = [
     "git --version",
     "git config --list",
 ]
+pre_commit_hooks = ["cat CHANGELOG.md"]
+post_commit_hooks = ["echo Done"]
 ```
 
-or
+or the path to an executable script:
 
 ```toml title="Calling a shell script"
 [tool.bumpversion]
 setup_hooks = ["path/to/setup.sh"]
+pre_commit_hooks = ["path/to/pre-commit.sh"]
+post_commit_hooks = ["path/to/post-commit.sh"]
 ```
 
-```bash title="path/to/setup.sh"
-#!/usr/bin/env bash
+!!! Note
 
-git config --global user.email "bump-my-version@github.actions"
-git config --global user.name "Testing Git"
-git --version
-git config --list
-```
-### Environment
+    You can make a script executable using the following steps:
+
+    1. Add a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) line to the top like `#!/bin/bash`
+    2. Run `chmod u+x path/to/script.sh` to set the executable bit
+
+## Hook Environments
 
-- The existing OS environment is available
+Each hook has these environment variables set when executed.
 
-#### Date and time fields
+### Inherited environment
+
+All environment variables set before bump-my-version was run are available.
+
+### Date and time fields
 
 ::: field-list
 
@@ -61,9 +77,11 @@ git config --list
     `BVHOOK_UTCNOW`
     : The ISO-8601-formatted current local time in the UTC time zone.
 
-#### Source code management fields
+### Source code management fields
+
+!!! Note
 
-These fields will only have values if the code is in a Git or Mercurial repository.
+    These fields will only have values if the code is in a Git or Mercurial repository.
 
 ::: field-list
 
@@ -83,7 +101,7 @@ These fields will only have values if the code is in a Git or Mercurial reposito
     : The current branch name, converted to lowercase, with non-alphanumeric characters removed and truncated to 20 characters. For example, `feature/MY-long_branch-name` would become `featuremylongbranchn`.
 
 
-#### Version fields
+### Current version fields
 
 ::: field-list
     `BVHOOK_CURRENT_VERSION`
@@ -93,4 +111,29 @@ These fields will only have values if the code is in a Git or Mercurial reposito
     : The current tag
     
     `BVHOOK_CURRENT_<version component>`
-    : Each version component defined by the [version configuration parsing regular expression](configuration/global.md#parse). The default configuration would have `current_major`, `current_minor`, and `current_patch` available.
+    : Each version component defined by the [version configuration parsing regular expression](configuration/global.md#parse). The default configuration would have `BVHOOK_CURRENT_MAJOR`, `BVHOOK_CURRENT_MINOR`, and `BVHOOK_CURRENT_PATCH` available.
+
+
+### New version fields
+
+!!! Note
+
+    These are not available in the _setup_ hook suite.
+
+::: field-list
+    `BVHOOK_NEW_VERSION`
+    : The new version serialized as a string
+
+    `BVHOOK_NEW_TAG`
+    : The new tag
+    
+    `BVHOOK_NEW_<version component>`
+    : Each version component defined by the [version configuration parsing regular expression](configuration/global.md#parse). The default configuration would have `BVHOOK_NEW_MAJOR`, `BVHOOK_NEW_MINOR`, and `BVHOOK_NEW_PATCH` available.
+
+## Outputs
+
+The `stdout` and `stderr` streams are echoed to the console if you pass the `-vv` option.
+
+## Dry-runs
+
+Bump my version does not execute any hooks during a dry run. With the verbose output option it will state which hooks it would have run.