docs: explain run details (#902)

* docs: explain run details * docs: add an example with a whole script in a run * docs: add a note about stale docs
evilmartians · Dec 21, 2024 · 0a15c5e · 0a15c5e
1 parent 36a39d2
commit 0a15c5e
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 0 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,5 +1,9 @@
 # Configure lefthook
 
+> [!IMPORTANT]
+>
+> This documentation is stale and will be removed soon. Please check the new: https://evilmartians.github.io/lefthook/configuration/
+
 Lefthook [supports](#config-file) YAML, JSON, and TOML configuration. In this document `lefthook.yml` is used for simplicity.
 
 ## Config file

diff --git a/docs/install.md b/docs/install.md
@@ -1,5 +1,9 @@
 # Install lefthook
 
+> [!IMPORTANT]
+>
+> This documentation is stale and will be removed soon. Please check the new: https://evilmartians.github.io/lefthook/installation/
+
 Choose your fighter:
 
 - [Ruby](#ruby)

diff --git a/docs/mdbook/configuration/run.md b/docs/mdbook/configuration/run.md
@@ -1,5 +1,12 @@
 ## `run`
 
+> **Note:** `run` command is treated differently on Unix-like systems (macOS, Linux) and Windows:
+>
+> - ***nix**: commands get wrapped with `sh -c '<run>'`
+> - **Windows**: commands execute natively
+>
+> So, when on *nix systems you can use pipes, builtins of a Bourne Shell, etc. For Windows the capabilities are limited by a single command.
+
 This is a mandatory option for a command. This is actually a command that is executed for the hook.
 
 You can use files templates that will be substituted with the appropriate files on execution:
@@ -12,6 +19,8 @@ You can use files templates that will be substituted with the appropriate files
 - `{0}` - shorthand for the single space-joint string of git hook arguments.
 - `{N}` - shorthand for the N-th git hook argument.
 
+> **Note:** Command line length has a limit on every system. If your list of files is quite long, lefthook splits your files list to fit in the limit and runs few commands sequentially.
+
 **Example**
 
 Run `yarn lint` on `pre-commit` hook.
@@ -159,3 +168,17 @@ pre-commit:
       # Will quote where needed with single quotes
       run: yarn test {staged_files} # will run `yarn eslint file1.js file2.js '[strange name].spec.js'`
 ```
+
+#### Scripts
+
+```yml
+# lefthook.yml
+
+pre-commit:
+  jobs:
+    - name: a whole script in a run
+      run: |
+        for file in $(ls .); do
+          yarn lint $file
+        done
+```
diff --git a/docs/usage.md b/docs/usage.md
@@ -1,5 +1,9 @@
 # Usage
 
+> [!IMPORTANT]
+>
+> This documentation is stale and will be removed soon. Please check the new: https://evilmartians.github.io/lefthook/usage/
+
 - [Commands](#commands)
   - [`lefthook install`](#lefthook-install)
   - [`lefthook uninstall`](#lefthook-uninstall)