gitignore

Documentation

Overview

Package gitignore implements matching file system paths to gitignore patterns that can be automatically read from a git repository tree in the order of definition priorities. It support all pattern formats as specified in the original gitignore documentation, copied below:

  Pattern format
  ==============

		- 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.

		- Trailing spaces are ignored unless they are quoted with backslash ("\").

		- An optional prefix "!" which negates the pattern; any matching file excluded
		  by a previous pattern will become included again. It is not possible to
		  re-include a file if a parent directory of that file is excluded.
		  Git doesn’t list excluded directories for performance reasons, so
		  any patterns on contained files have no effect, no matter where they are
		  defined. 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.

  Copyright and license
  =====================

		Copyright (c) Oleg Sklyar, Silvertern and source{d}

		The package code was donated to source{d} to include, modify and develop
		further as a part of the `go-git` project, release it on the license of
		the whole project or delete it from the project.

Index

• type MatchResult
• type Matcher
  • func NewMatcher(ps []Pattern) Matcher
• type Pattern
  • func LoadGlobalPatterns(fs billy.Filesystem) (ps []Pattern, err error)
  • func LoadSystemPatterns(fs billy.Filesystem) (ps []Pattern, err error)
  • func ParsePattern(p string, domain []string) Pattern
  • func ReadPatterns(fs billy.Filesystem, path []string) (ps []Pattern, err error)

Types

type MatchResult

type MatchResult int

MatchResult defines outcomes of a match, no match, exclusion or inclusion.

const (
	// NoMatch defines the no match outcome of a match check
	NoMatch MatchResult = iota
	// Exclude defines an exclusion of a file as a result of a match check
	Exclude
	// Include defines an explicit inclusion of a file as a result of a match check
	Include
)

type Matcher

type Matcher interface {
	// Match matches patterns in the order of priorities. As soon as an inclusion or
	// exclusion is found, not further matching is performed.
	Match(path []string, isDir bool) bool
}

Matcher defines a global multi-pattern matcher for gitignore patterns

func NewMatcher

func NewMatcher(ps []Pattern) Matcher

NewMatcher constructs a new global matcher. Patterns must be given in the order of increasing priority. That is most generic settings files first, then the content of the repo .gitignore, then content of .gitignore down the path or the repo and then the content command line arguments.

type Pattern

type Pattern interface {
	// Match matches the given path to the pattern.
	Match(path []string, isDir bool) MatchResult
}

Pattern defines a single gitignore pattern.

func LoadGlobalPatterns

func LoadGlobalPatterns(fs billy.Filesystem) (ps []Pattern, err error)

LoadGlobalPatterns loads gitignore patterns from from the gitignore file declared in a user's ~/.gitconfig file. If the ~/.gitconfig file does not exist the function will return nil. If the core.excludesfile property is not declared, the function will return nil. If the file pointed to by the core.excludesfile property does not exist, the function will return nil.

The function assumes fs is rooted at the root filesystem.

func LoadSystemPatterns

func LoadSystemPatterns(fs billy.Filesystem) (ps []Pattern, err error)

LoadSystemPatterns loads gitignore patterns from from the gitignore file declared in a system's /etc/gitconfig file. If the ~/.gitconfig file does not exist the function will return nil. If the core.excludesfile property is not declared, the function will return nil. If the file pointed to by the core.excludesfile property does not exist, the function will return nil.

The function assumes fs is rooted at the root filesystem.

func ParsePattern

func ParsePattern(p string, domain []string) Pattern

ParsePattern parses a gitignore pattern string into the Pattern structure.

func ReadPatterns

func ReadPatterns(fs billy.Filesystem, path []string) (ps []Pattern, err error)

ReadPatterns reads gitignore patterns recursively traversing through the directory structure. The result is in the ascending order of priority (last higher).