1# Upgrading from v3 to v4
 2
 3v4 is a complete rewrite with a focus on performance. Additionally,
 4[doublestar] has been updated to use the new [io/fs] package for filesystem
 5access. As a result, it is only supported by [golang] v1.16+.
 6
 7`Match()` and `PathMatch()` mostly did not change, besides big performance
 8improvements. 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
23its 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
33v4 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
35slice. You also get `fs.DirEntry` objects for each result, and can quit early
36if your callback returns an error.
37
38# Upgrading from v2 to v3
39
40v3 introduced using `!` to negate character classes, in addition to `^`. If any
41of 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
43exclamation mark. Note that, like the caret (`^`), it only negates the
44character class if it is the first character in the character class.
45
46# Upgrading from v1 to v2
47
48The change from v1 to v2 was fairly minor: the return type of the `Open` method
49on the `OS` interface was changed from `*os.File` to `File`, a new interface
50exported by doublestar. The new `File` interface only defines the functionality
51doublestar actually needs (`io.Closer` and `Readdir`), making it easier to use
52doublestar with [go-billy], [afero], or something similar. If you were using
53this functionality, updating should be as easy as updating `Open's` return
54type, since `os.File` already implements `doublestar.File`.
55
56If you weren't using this functionality, updating should be as easy as changing
57your 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/