Skip to content

Commit

Permalink
Document the unusual behaviour of ** in glob option
Browse files Browse the repository at this point in the history
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
```
  • Loading branch information
jamiecobbett committed Feb 3, 2025
1 parent 2f59812 commit 5fde6d6
Showing 1 changed file with 17 additions and 0 deletions.
17 changes: 17 additions & 0 deletions docs/mdbook/configuration/glob.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 5fde6d6

Please sign in to comment.