github.com/AndrewDeryabin/doublestar/v4@v4.0.0-20230123132908-d9476b7d41be/UPGRADING.md (about)

     1  # Upgrading from v3 to v4
     2  
     3  v4 is a complete rewrite with a focus on performance. Additionally,
     4  [doublestar] has been updated to use the new [io/fs] package for filesystem
     5  access. As a result, it is only supported by [golang] v1.16+.
     6  
     7  `Match()` and `PathMatch()` mostly did not change, besides big performance
     8  improvements. Their API is the same. However, note the following corner cases:
     9  
    10  * In previous versions of [doublestar], `PathMatch()` could accept patterns
    11    that used either platform-specific path separators, or `/`. This was
    12    undocumented and didn't match `filepath.Match()`. In v4, both `pattern` and
    13    `name` must be using appropriate path separators for the platform. You can
    14    use `filepath.FromSlash()` to change `/` to platform-specific separators if
    15    you aren't sure.
    16  * In previous versions of [doublestar], a pattern such as `path/to/a/**` would
    17    _not_ match `path/to/a`. In v4, this pattern _will_ match because if `a` was
    18    a directory, `Glob()` would return it. In other words, the following returns
    19    true: `Match("path/to/a/**", "path/to/a")`
    20  
    21  `Glob()` changed from using a [doublestar]-specific filesystem abstraction (the
    22  `OS` interface) to the [io/fs] package. As a result, it now takes a `fs.FS` as
    23  its first argument. This change has a couple ramifications:
    24  
    25  * Like `io/fs.Glob`, `pattern` must use a `/` as path separator, even on
    26    platforms that use something else. You can use `filepath.ToSlash()` on your
    27    patterns if you aren't sure.
    28  * Patterns that contain `/./` or `/../` are invalid. The [io/fs] package
    29    rejects them, returning an IO error. Since `Glob()` ignores IO errors, it'll
    30    end up being silently rejected. You can run `path.Clean()` to ensure they are
    31    removed from the pattern.
    32  
    33  v4 also added a `GlobWalk()` function that is slightly more performant than
    34  `Glob()` if you just need to iterate over the results and don't need a string
    35  slice. You also get `fs.DirEntry` objects for each result, and can quit early
    36  if your callback returns an error.
    37  
    38  # Upgrading from v2 to v3
    39  
    40  v3 introduced using `!` to negate character classes, in addition to `^`. If any
    41  of your patterns include a character class that starts with an exclamation mark
    42  (ie, `[!...]`), you'll need to update the pattern to escape or move the
    43  exclamation mark. Note that, like the caret (`^`), it only negates the
    44  character class if it is the first character in the character class.
    45  
    46  # Upgrading from v1 to v2
    47  
    48  The change from v1 to v2 was fairly minor: the return type of the `Open` method
    49  on the `OS` interface was changed from `*os.File` to `File`, a new interface
    50  exported by doublestar. The new `File` interface only defines the functionality
    51  doublestar actually needs (`io.Closer` and `Readdir`), making it easier to use
    52  doublestar with [go-billy], [afero], or something similar. If you were using
    53  this functionality, updating should be as easy as updating `Open's` return
    54  type, since `os.File` already implements `doublestar.File`.
    55  
    56  If you weren't using this functionality, updating should be as easy as changing
    57  your dependencies to point to v2.
    58  
    59  [afero]: https://github.com/spf13/afero
    60  [doublestar]: https://github.com/bmatcuk/doublestar
    61  [go-billy]: https://github.com/src-d/go-billy
    62  [golang]: http://golang.org/
    63  [io/fs]: https://golang.org/pkg/io/fs/