pathspec

README

go-pathspec

go-pathspec implements gitignore-style pattern matching for paths.

Alternatives

There are a few alternatives, that try to be gitignore compatible or even state gitignore compatibility:

https://github.com/go-git/go-git

go-git states it would be gitignore compatible, but actually they are missing a few special cases. This issue describes one of the not working patterns: https://github.com/go-git/go-git/issues/108

What does not work is global filename pattern matching. Consider the following .gitignore file:

# gitignore test file
parse.go

Then parse.go should match on all filenames called parse.go. You can test this via this shell script:

mkdir -p /tmp/test/internal/util
touch /tmp/test/internal/util/parse.go
cd /tmp/test/
git init
echo "parse.go" > .gitignore

With git parse.go will be excluded. The go-git implementation behaves different.

https://github.com/monochromegane/go-gitignore

monochromegane's go-gitignore does not support the use of **-operators. This is not consistent to real gitignore behavior, too.

Authors

Sander van Harmelen (sander@xanzy.io)
Christian Rebischke (chris@shibumi.dev)

Documentation

Overview

Package pathspec implements git compatible gitignore pattern matching. See the description below, if you are unfamiliar with it:

A blank line matches no files, so it can serve as a separator for readability.

A line starting with # serves as a comment. Put a backslash ("\") in front of the first hash for patterns that begin with a hash.

An optional prefix "!" which negates the pattern; any matching file excluded by a previous pattern will become included again. If a negated pattern matches, this will override lower precedence patterns sources. Put a backslash ("\") in front of the first "!" for patterns that begin with a literal "!", for example, "\!important!.txt".

If the pattern ends with a slash, it is removed for the purpose of the following description, but it would only find a match with a directory. In other words, foo/ will match a directory foo and paths underneath it, but will not match a regular file or a symbolic link foo (this is consistent with the way how pathspec works in general in Git).

If the pattern does not contain a slash /, Git treats it as a shell glob pattern and checks for a match against the pathname relative to the location of the .gitignore file (relative to the toplevel of the work tree if not from a .gitignore file).

Otherwise, Git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, "Documentation/*.html" matches "Documentation/git.html" but not "Documentation/ppc/ppc.html" or/ "tools/perf/Documentation/perf.html".

A leading slash matches the beginning of the pathname. For example, "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".

Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:

A leading "**" followed by a slash means match in all directories. For example, "**/foo" matches file or directory "foo" anywhere, the same as pattern "foo". "**/foo/bar" matches file or directory "bar" anywhere that is directly under directory "foo".

A trailing "/" matches everything inside. For example, "abc/" matches all files inside directory "abc", relative to the location of the .gitignore file, with infinite depth.

A slash followed by two consecutive asterisks then a slash matches zero or more directories. For example, "a/**/b" matches "a/b", "a/x/b", "a/x/y/b" and so on.

Other consecutive asterisks are considered invalid.

Index

• func GitIgnore(patterns []string, name string) (ignore bool, err error)
• func ReadGitIgnore(content io.Reader, name string) (ignore bool, err error)

Functions

func GitIgnore

func GitIgnore(patterns []string, name string) (ignore bool, err error)

GitIgnore uses a string slice of patterns for matching on a filepath string. On match it returns true, otherwise false. On error it passes the error through.

func ReadGitIgnore

func ReadGitIgnore(content io.Reader, name string) (ignore bool, err error)

ReadGitIgnore implements the io.Reader interface for reading a gitignore file line by line. It behaves exactly like the GitIgnore function. The only difference is that GitIgnore works on a string slice.

ReadGitIgnore returns a boolean value if we match or not and an error.