From a63170f87f0b94ee8aa73675ac4b165649692857 Mon Sep 17 00:00:00 2001 From: Daniel Bayley Date: Tue, 25 Jun 2024 01:25:27 +0100 Subject: [PATCH] docs(README): add #anchor and improve `note`s --- README.md | 57 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 023cd779..ed4193b2 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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 @@ -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 @@ -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. @@ -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 @@ -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!) @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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.