Skip to content

Commit 59bf9ca

Browse files
committed
fix notes
1 parent dde4fa6 commit 59bf9ca

File tree

1 file changed

+51
-50
lines changed

1 file changed

+51
-50
lines changed

README.md

Lines changed: 51 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -435,37 +435,37 @@ share the previously loaded cache.
435435
is used as the starting point for absolute patterns that start
436436
with `/`, (but not drive letters or UNC paths on Windows).
437437

438-
> [!NOTE] This _doesn't_ necessarily limit the walk to the
439-
> `root` directory, and doesn't affect the cwd starting point
440-
> for non-absolute patterns. A pattern containing `..` will
441-
> still be able to traverse out of the root directory, if it
442-
> is not an actual root directory on the filesystem, and any
443-
> non-absolute patterns will be matched in the `cwd`. For
444-
> example, the pattern `/../*` with `{root:'/some/path'}`
445-
> will return all files in `/some`, not all files in
446-
> `/some/path`. The pattern `*` with `{root:'/some/path'}`
447-
> will return all the entries in the cwd, not the entries in
448-
> `/some/path`.
449-
450-
  To start absolute and non-absolute patterns in the same path,
451-
you can use `{root:''}`. However, be aware that on Windows
452-
systems, a pattern like `x:/*` or `//host/share/*` will
453-
_always_ start in the `x:/` or `//host/share` directory,
454-
regardless of the `root` setting.
438+
To start absolute and non-absolute patterns in the same path,
439+
you can use `{root:''}`. However, be aware that on Windows
440+
systems, a pattern like `x:/*` or `//host/share/*` will
441+
_always_ start in the `x:/` or `//host/share` directory,
442+
regardless of the `root` setting.
443+
444+
> [!NOTE] This _doesn't_ necessarily limit the walk to the
445+
> `root` directory, and doesn't affect the cwd starting point
446+
> for non-absolute patterns. A pattern containing `..` will
447+
> still be able to traverse out of the root directory, if it
448+
> is not an actual root directory on the filesystem, and any
449+
> non-absolute patterns will be matched in the `cwd`. For
450+
> example, the pattern `/../*` with `{root:'/some/path'}`
451+
> will return all files in `/some`, not all files in
452+
> `/some/path`. The pattern `*` with `{root:'/some/path'}`
453+
> will return all the entries in the cwd, not the entries in
454+
> `/some/path`.
455455
456456
- `windowsPathsNoEscape` Use `\\` as a path separator _only_, and
457457
_never_ as an escape character. If set, all `\\` characters are
458458
replaced with `/` in the pattern.
459459

460-
> [!NOTE]
461-
> This makes it **impossible** to match against paths
462-
> containing literal glob pattern characters, but allows matching
463-
> with patterns constructed using `path.join()` and
464-
> `path.resolve()` on Windows platforms, mimicking the (buggy!)
465-
> behavior of Glob v7 and before on Windows. Please use with
466-
> caution, and be mindful of [the caveat below about Windows
467-
> paths](#windows). (For legacy reasons, this is also set if
468-
> `allowWindowsEscape` is set to the exact value `false`.)
460+
> [!NOTE]
461+
> This makes it **impossible** to match against paths
462+
> containing literal glob pattern characters, but allows matching
463+
> with patterns constructed using `path.join()` and
464+
> `path.resolve()` on Windows platforms, mimicking the (buggy!)
465+
> behavior of Glob v7 and before on Windows. Please use with
466+
> caution, and be mindful of [the caveat below about Windows
467+
> paths](#windows). (For legacy reasons, this is also set if
468+
> `allowWindowsEscape` is set to the exact value `false`.)
469469
470470
- `dot` Include `.dot` files in normal matches and `globstar`
471471
matches. Note that an explicit dot in a portion of the pattern
@@ -500,12 +500,12 @@ regardless of the `root` setting.
500500
- `nocase` Perform a case-insensitive match. This defaults to
501501
`true` on macOS and Windows systems, and `false` on all others.
502502

503-
> [!NOTE]
504-
> `nocase` should only be explicitly set when it is
505-
> known that the filesystem's case sensitivity differs from the
506-
> platform default. If set `true` on case-sensitive file
507-
> systems, or `false` on case-insensitive file systems, then the
508-
> walk may return more or less results than expected.
503+
> [!NOTE]
504+
> `nocase` should only be explicitly set when it is
505+
> known that the filesystem's case sensitivity differs from the
506+
> platform default. If set `true` on case-sensitive file
507+
> systems, or `false` on case-insensitive file systems, then the
508+
> walk may return more or less results than expected.
509509
510510
- `maxDepth` Specify a number to limit the depth of the directory
511511
traversal to this many levels below the `cwd`.
@@ -518,9 +518,9 @@ regardless of the `root` setting.
518518
- `nodir` Do not match directories, only files. (Note: to match
519519
_only_ directories, put a `/` at the end of the pattern.)
520520

521-
> [!NOTE]
522-
> When `follow` and `nodir` are both set, then symbolic
523-
> links to directories are also omitted.
521+
> [!NOTE]
522+
> When `follow` and `nodir` are both set, then symbolic
523+
> links to directories are also omitted.
524524
525525
- `stat` Call `lstat()` on all entries, whether required or not
526526
to determine whether it's a valid match. When used with
@@ -536,10 +536,6 @@ regardless of the `root` setting.
536536
matches. To ignore all children within a directory, as well
537537
as the entry itself, append `'/**'` to the ignore pattern.
538538

539-
> [!NOTE]
540-
> `ignore` patterns are _always_ in `dot:true` mode,
541-
> regardless of any other settings.
542-
543539
If an object is provided that has `ignored(path)` and/or
544540
`childrenIgnored(path)` methods, then these methods will be
545541
called to determine whether any Path is a match or if its
@@ -555,6 +551,10 @@ regardless of the `root` setting.
555551
[`.relative()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#relative),
556552
and more.
557553

554+
> [!NOTE]
555+
> `ignore` patterns are _always_ in `dot:true` mode,
556+
> regardless of any other settings.
557+
558558
- `follow` Follow symlinked directories when expanding `**`
559559
patterns. This can result in a lot of duplicate references in
560560
the presence of cyclic links, and make performance quite bad.
@@ -563,9 +563,9 @@ regardless of the `root` setting.
563563
it is not the first item in the pattern, or none if it is the
564564
first item in the pattern, following the same behavior as Bash.
565565

566-
> [!NOTE]
567-
> When `follow` and `nodir` are both set, then symbolic
568-
> links to directories are also omitted.
566+
> [!NOTE]
567+
> When `follow` and `nodir` are both set, then symbolic
568+
> links to directories are also omitted.
569569
570570
- `realpath` Set to true to call `fs.realpath` on all of the
571571
results. In the case of an entry that cannot be resolved, the
@@ -631,14 +631,6 @@ regardless of the `root` setting.
631631
`false`, and a custom `Ignore` is provided that does not have
632632
an `add()` method, then it will throw an error.
633633

634-
> [!NOTE]
635-
> It _only_ ignores matches that would be a descendant
636-
> of a previous match, and only if that descendant is matched
637-
> _after_ the ancestor is encountered. Since the file system walk
638-
> happens in indeterminate order, it's possible that a match will
639-
> already be added before its ancestor, if multiple or braced
640-
> patterns are used.
641-
642634
For example:
643635

644636
```js
@@ -664,6 +656,15 @@ regardless of the `root` setting.
664656
one another's file system descendants, or if the occasional
665657
included child entry will not cause problems.
666658

659+
> [!NOTE]
660+
> It _only_ ignores matches that would be a descendant
661+
> of a previous match, and only if that descendant is matched
662+
> _after_ the ancestor is encountered. Since the file system walk
663+
> happens in indeterminate order, it's possible that a match will
664+
> already be added before its ancestor, if multiple or braced
665+
> patterns are used.
666+
667+
667668
## Glob Primer
668669

669670
Much more information about glob pattern expansion can be found

0 commit comments

Comments
 (0)