From 70b8b0588bc48cc91daf985b36b73daf067d256f Mon Sep 17 00:00:00 2001
From: pelikhan <jhalleux@microsoft.com>
Date: Wed, 4 Sep 2024 09:45:07 -0700
Subject: [PATCH] add git hooks docs

---
 .vscode/extensions.json                       |  3 +-
 .../docs/guides/auto-git-commit-message.mdx   | 44 ++++++++++++++++---
 2 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 64ad4124a1..f318d21978 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -10,6 +10,7 @@
         "tldraw-org.tldraw-vscode",
         "bierner.emojisense",
         "github.vscode-pull-request-github",
-        "ms-toolsai.prompty"
+        "ms-toolsai.prompty",
+        "unifiedjs.vscode-mdx"
     ]
 }
diff --git a/docs/src/content/docs/guides/auto-git-commit-message.mdx b/docs/src/content/docs/guides/auto-git-commit-message.mdx
index e99cfd2f72..6cd0a30049 100644
--- a/docs/src/content/docs/guides/auto-git-commit-message.mdx
+++ b/docs/src/content/docs/guides/auto-git-commit-message.mdx
@@ -13,7 +13,7 @@ ensuring they are meaningful and save you time.
 The script acts as a regular node.js automation script and uses [runPrompt](/genaiscript/reference/scripts/inner-prompts)
 to issue calls to the LLM and ask the user to confirm the generated text.
 
-## 🔍 **Explaining the Script**
+## Explaining the Script
 
 First, we check if there are any staged changes in the Git repository:
 
@@ -24,7 +24,7 @@ let { stdout } = await host.exec("git", ["diff", "--cached"])
 If no changes are staged, we ask the user if they want to stage all changes. If the user confirms, we stage all changes. Otherwise, we bail out.
 
 ```ts
-const stage = await host.confirm("No staged changes. Stage all changes?", { 
+const stage = await host.confirm("No staged changes. Stage all changes?", {
     default: true,
 })
 if (stage) {
@@ -70,8 +70,7 @@ Options are given to edit or regenerate the message. If the user chooses to edit
 
 ```ts
 if (choice === "edit") {
-    message = await host.input("Edit commit message",
-        { required: true })
+    message = await host.input("Edit commit message", { required: true })
     choice = "commit"
 }
 ```
@@ -84,7 +83,7 @@ if (choice === "commit" && message) {
 }
 ```
 
-## 🚀 **Running the Script**
+## Running the Script
 
 You can run this script using the [CLI](/genaiscript/reference/cli).
 
@@ -96,8 +95,11 @@ You can wrap this command in a `gcm.sh` file or in your package `script` section
 
 ```json '"gcm": "genaiscript run gcm"'
 {
+    "devDependencies": {
+        "genaiscript": "*"
+    },
     "scripts": {
-        "gcm": "npx --yes genaiscript run gcm"
+        "gcm": "genaiscript run gcm"
     }
 }
 ```
@@ -108,7 +110,35 @@ Then you can run the script using:
 npm run gcm
 ```
 
+## Using git hooks
+
+You can also attach to the [commit-msg](https://git-scm.com/docs/githooks#_commit_msg) git hook to run the message generation on demand.
+Using the [huksy](https://typicode.github.io/husky/) framework, we can register the execution
+of genaiscript in the `.husky/commit-msg` file.
+
+The `commit-msg` hook receives a file location where the message is stored. We pass this parameter to the script
+so that it gets populated in the `env.files` variable.
+
+```bash title=".husky/commit-msg"
+npx --yes genaiscript run commit-msg "$1"
+```
+
+In the script, we check if the content of the file already has a user message, otherwize generate a new message.
+
+```js title="commit-msg.genai.mts"
+const msg = env.files[0] // file created by git to hold the message
+const msgContent = msg.content // check if the user added any message
+    ?.split(/\n/g)
+    .filter((l) => l && !/^#/.test(l)) // filter out comments
+    .join("\n")
+if (msgContent) cancel("commit message already exists")
+
+...
+
+await host.writeText(msg.filename, message)
+```
+
 ## Acknowledgements
 
-This script was inspired from Karpathy's 
+This script was inspired from Karpathy's
 [commit message generator](https://gist.github.com/karpathy/1dd0294ef9567971c1e4348a90d69285).