deprecate glob --not in favor of glob --exclude

[amtoine]

Description

looking at the Wax documentation about wax::Walk.not, especially

therefore does not read directory trees from the file system when a directory matches an exhaustive glob expression

Important
in the following of this PR description, i talk about pruning and a --prune option, but this has been changed to exclusion and --exclude after a discussion with @fdncred.

this looks like a pruning operation to me, right? 😮
i wanted to make the glob option --not clearer about that, because

-n, --not <List(String)> - Patterns to exclude from the results

from help glob is not very explicit about whether the search is pruned when entering a directory matching a pattern in --not or just removing it from the output 😕

changelog

this PR proposes to rename the glob --not option to glob --prune and make it's documentation more explicit 😋

benchmarking

to support the pruning behaviour put forward above, i've run a benchmark

1. define two closures to compare the behaviour between removing patterns manually or using --not

let where = {
    [.*/\.local/.*, .*/documents/.*, .*/\.config/.*]
        | reduce --fold (glob **) {|pat, acc| $acc | where $it !~ $pat}
        | length
}

let not = { glob ** --not [**/.local/**, **/documents/**, **/.config/**] | length }

2. run the two to make sure they give similar results

> do $where
33424

> do $not
33420

👌
3. measure the performance

use std bench

> bench --verbose --pretty --rounds 25 $not
44ms 52µs 285ns +/- 977µs 571ns

> bench --verbose --pretty --rounds 5 $where
1sec 250ms 187µs 99ns +/- 8ms 538µs 57ns

👉 we can see that the results are (almost) the same but --not is much faster, looks like pruning 😋

User-Facing Changes

• --not will give a warning message but still work
• --prune will work just as --not without warning and with a more explicit doc
• --prune and --not at the same time will give an error

Tests + Formatting

this PR fixes the examples of glob using the --not option.

After Submitting

prepare the removal PR and mention in release notes.

[fdncred]

I like --not better than --prune because not is more intuitive and we're not gardening :), plus that's the function's name in wax. I realize fd uses --prune but that doesn't mean we have to. To the novice, --prune may be a bizarre parameter name.

[amtoine]

I like --not better than --prune because not is more intuitive and we're not gardening :), plus that's the function's name in wax. I realize fd uses --prune but that doesn't mean we have to. To the novice, --prune may be a bizarre parameter name.

i do not use fd really, so this was not inspired directly by fd --prune 😉
but this still is a valid point, i agree 👍
to me, a filesystem is a tree, so it makes sense to say prune when a branch of the filesystem tree is removed.
but i do not want the non-computer-science folks to be confused about that 😌

i've talked to 3 dev persons and one non-dev to have some insight and here are four ideas

• use --prune
• use --exclude-from-search or --skip
• simply update the doc of --not
• leave glob as-is

i could live with option 3 but

• all four of them have voted for either --exclude-from-search or --skip, and my personal favorite is --exclude-from-search.
• all four of them have voted for not --not because it does not show that the matching patterns are removed from the search, so i wouldn't vote for the last option as well 😋

[fdncred]

I'd vote for --exclude probably. --exclude-from-search seems a bit too verbose.

[amtoine]

I'd vote for --exclude probably. --exclude-from-search seems a bit too verbose.

let's go with --exclude and the updated doc 🙏

[fdncred]

looks good

[amtoine]

let's go with this then, hopefully a bit clearer 😇