From 5fde6d666f55944a370ecd393135aec586874aff Mon Sep 17 00:00:00 2001
From: jamiecobbett <jcobbett@gocardless.com>
Date: Thu, 30 Jan 2025 18:05:11 +0000
Subject: [PATCH] Document the unusual behaviour of ** in glob option

I had assumed that glob patterns work like they do with the *nix `ls` command,
or in tools like lint-staged.

It seems that ** is interpreted as a single asterisk for 1+ directories, rather than "0 or more directories deep" as in `ls`.

Whilst there is a link to the Go glob library used, and it mentions double
asterisks, I was mainly left confused by the line in the README:

> Syntax is inspired by [standard
> wildcards](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm),
> except that ** is aka super-asterisk, that do not sensitive for separators.

Whilst the glob library README could be improved, I think it's natural to use
`ls` to try and test what would be matched (or copy config from tools like
lint-staged or pre-commit), so it would be great to call out this difference in
the lefthook documentation.

It might be quite useful to provide a means of testing/listing what files would
be matched for different commands - I found it necessary to do the below.

Example
=======

Let's say you have a directory structure like:

```
- src
  - foo
    - bar
      - nestedTwice.js
    - nestedOnce.js
  - topLevel.js
```

If you run `ls -1`, you get all three files:
```
ls -1 src/**/*.js
src/foo/bar/nestedTwice.js
src/foo/nestedOnce.js
src/topLevel.js
```

Given this lefthook config

```yaml
pre-commit:
  commands:
    eslint:
      run: ls -1 {staged_files}
      glob: "src/**/*.js"
```

And you run:

```sh
git add src
lefthook run pre-commit
```

The output is missing `src/topLevel.js`:

```
src/foo/bar/nestedTwice.js
src/foo/nestedOnce.js
```
---
 docs/mdbook/configuration/glob.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/mdbook/configuration/glob.md b/docs/mdbook/configuration/glob.md
index e0f0da87..fce1a412 100644
--- a/docs/mdbook/configuration/glob.md
+++ b/docs/mdbook/configuration/glob.md
@@ -31,6 +31,23 @@ pre-commit:
 
 For patterns that you can use see [this](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm) reference. We use [glob](https://github.com/gobwas/glob) library.
 
+***Behaviour of `**`***
+
+Note that the behaviour of `**` is different from typical glob implementations, like `ls` or tools like `lint-staged` in that a double-asterisk matches 1+ directories deep, not zero or more directories.
+If you want to match *both* files at the top level and nested, then rather than:
+
+```yaml
+glob: "src/**/*.js"
+```
+
+You'll need:
+
+```yaml
+glob: "src/*.js"
+```
+
+***Using `glob` without a files template in`run`***
+
 If you've specified `glob` but don't have a files template in [`run`](./run.md) option, lefthook will check `{staged_files}` for `pre-commit` hook and `{push_files}` for `pre-push` hook and apply filtering. If no files left, the command will be skipped.
 
 ```yml