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/