Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(README): add #anchor and improve notes #591

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(README): add #anchor and improve notes #591

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 34 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
Match files using the patterns the shell uses.

The most correct and second fastest glob implementation in
JavaScript. (See **Comparison to Other JavaScript Glob
Implementations** at the bottom of this readme.)
JavaScript. (See [**Comparison to Other JavaScript Glob
Implementations**](#comparisons-to-other-fnmatchglob-implementations) at the bottom of this readme.)

![a fun cartoon logo made of glob characters](https://github.com/isaacs/node-glob/raw/main/logo/glob.png)

Expand All @@ -16,7 +16,8 @@ Install with npm
npm i glob
```

**Note** the npm package name is _not_ `node-glob` that's a
> [!NOTE]
> The npm package name is _not_ `node-glob` that's a
different thing that was abandoned years ago. Just `glob`.

```js
Expand Down Expand Up @@ -135,7 +136,8 @@ const newFiles = await glob('**', {
})
```

**Note** Glob patterns should always use `/` as a path separator,
> [!NOTE]
> Glob patterns should always use `/` as a path separator,
even on Windows systems, as `\` is used to escape glob
characters. If you wish to use `\` as a path separator _instead
of_ using it as an escape character on Windows platforms, you may
Expand Down Expand Up @@ -362,7 +364,8 @@ Options object is required.

See full options descriptions below.

Note that a previous `Glob` object can be passed as the
> [!NOTE]
> A previous `Glob` object can be passed as the
`GlobOptions` to another `Glob` instantiation to re-use settings
and caches with a new pattern.

Expand Down Expand Up @@ -429,7 +432,8 @@ share the previously loaded cache.
is used as the starting point for absolute patterns that start
with `/`, (but not drive letters or UNC paths on Windows).

Note that this _doesn't_ necessarily limit the walk to the
> [!NOTE]
> This _doesn't_ necessarily limit the walk to the
`root` directory, and doesn't affect the cwd starting point for
non-absolute patterns. A pattern containing `..` will still be
able to traverse out of the root directory, if it is not an
Expand All @@ -440,17 +444,17 @@ share the previously loaded cache.
`*` with `{root:'/some/path'}` will return all the entries in
the cwd, not the entries in `/some/path`.

To start absolute and non-absolute patterns in the same
path, you can use `{root:''}`. However, be aware that on
Windows systems, a pattern like `x:/*` or `//host/share/*` will
_always_ start in the `x:/` or `//host/share` directory,
regardless of the `root` setting.
    To start absolute and non-absolute patterns in the same path,
you can use `{root:''}`. However, be aware that on Windows systems,
    a pattern like `x:/*` or `//host/share/*` will _always_ start in the
`x:/` or `//host/share` directory, regardless of the `root` setting.

- `windowsPathsNoEscape` Use `\\` as a path separator _only_, and
_never_ as an escape character. If set, all `\\` characters are
replaced with `/` in the pattern.

Note that this makes it **impossible** to match against paths
> [!NOTE]
> This makes it **impossible** to match against paths
containing literal glob pattern characters, but allows matching
with patterns constructed using `path.join()` and
`path.resolve()` on Windows platforms, mimicking the (buggy!)
Expand Down Expand Up @@ -492,7 +496,8 @@ share the previously loaded cache.
- `nocase` Perform a case-insensitive match. This defaults to
`true` on macOS and Windows systems, and `false` on all others.

**Note** `nocase` should only be explicitly set when it is
> [!NOTE]
> `nocase` should only be explicitly set when it is
known that the filesystem's case sensitivity differs from the
platform default. If set `true` on case-sensitive file
systems, or `false` on case-insensitive file systems, then the
Expand All @@ -509,7 +514,8 @@ share the previously loaded cache.
- `nodir` Do not match directories, only files. (Note: to match
_only_ directories, put a `/` at the end of the pattern.)

Note: when `follow` and `nodir` are both set, then symbolic
> [!NOTE]
> When `follow` and `nodir` are both set, then symbolic
links to directories are also omitted.

- `stat` Call `lstat()` on all entries, whether required or not
Expand All @@ -526,13 +532,14 @@ share the previously loaded cache.
To ignore all children within a directory, as well as the entry
itself, append `'/**'` to the ignore pattern.

**Note** `ignore` patterns are _always_ in `dot:true` mode,
> [!NOTE]
> `ignore` patterns are _always_ in `dot:true` mode,
regardless of any other settings.

If an object is provided that has `ignored(path)` and/or
`childrenIgnored(path)` methods, then these methods will be
called to determine whether any Path is a match or if its
children should be traversed, respectively.
    If an object is provided that has `ignored(path)` and/or
`childrenIgnored(path)` methods, then these methods will be called to
    determine whether any Path is a match or if its children should
be traversed, respectively.

- `follow` Follow symlinked directories when expanding `**`
patterns. This can result in a lot of duplicate references in
Expand All @@ -542,7 +549,8 @@ share the previously loaded cache.
it is not the first item in the pattern, or none if it is the
first item in the pattern, following the same behavior as Bash.

Note: when `follow` and `nodir` are both set, then symbolic
> [!NOTE]
> When `follow` and `nodir` are both set, then symbolic
links to directories are also omitted.

- `realpath` Set to true to call `fs.realpath` on all of the
Expand Down Expand Up @@ -606,7 +614,8 @@ share the previously loaded cache.
`false`, and a custom `Ignore` is provided that does not have
an `add()` method, then it will throw an error.

**Caveat** It _only_ ignores matches that would be a descendant
> [!NOTE]
> It _only_ ignores matches that would be a descendant
of a previous match, and only if that descendant is matched
_after_ the ancestor is encountered. Since the file system walk
happens in indeterminate order, it's possible that a match will
Expand Down Expand Up @@ -737,7 +746,8 @@ bsdglob and bash 5, where `**` only has special significance if
it is the only thing in a path part. That is, `a/**/b` will match
`a/x/y/b`, but `a/**b` will not.

Note that symlinked directories are not traversed as part of a
> [!NOTE]
> Symlinked directories are not traversed as part of a
`**`, though their contents may match against subsequent portions
of the pattern. This prevents infinite loops and duplicates and
the like. You can force glob to traverse symlinks with `**` by
Expand Down Expand Up @@ -955,7 +965,8 @@ performing a glob pattern expansion as faithfully as possible to
the behavior of Bash and other sh-like shells, with as much speed
as possible.

Note that prior versions of `node-glob` are _not_ on this list.
> [!NOTE]
> Prior versions of `node-glob` are _not_ on this list.
Former versions of this module are far too slow for any cases
where performance matters at all, and were designed with APIs
that are extremely dated by current JavaScript standards.
Expand Down