GitIgnoreMatcher Class

Determines which paths of a git working tree are ignored, as git status and git check-ignore do, and enumerates the files that are not ignored.

public sealed class GitIgnoreMatcher

Remarks

The patterns come from the .gitignore files of the working tree, the info/exclude file of the repository and the global excludes file, with the precedence git gives them: the .gitignore file of a directory takes precedence over the ones of its parent directories, which take precedence over info/exclude, which takes precedence over the global excludes file.

A .gitignore file is read the first time a path of its directory is evaluated, then cached for the lifetime of the instance. Create a new instance to read the files again. The instance can be used from several threads.

Only the ignore rules are evaluated: a file that is ignored but already tracked by git is still reported as ignored, and the .git entries are never returned by GitIgnoreMatcher.EnumerateFiles.

Example

using var rootDirectory = TemporaryDirectory.Create();
rootDirectory.CreateTextFile(".gitignore", "*.log\n");
rootDirectory.CreateTextFile("src/.gitignore", "bin/\n!important.log\n");
rootDirectory.CreateEmptyFile("src/Program.cs");
rootDirectory.CreateEmptyFile("src/bin/App.dll");
rootDirectory.CreateEmptyFile("src/trace.log");
rootDirectory.CreateEmptyFile("src/important.log");

var matcher = new GitIgnoreMatcher(rootDirectory.FullPath);

// The .gitignore file of a directory applies to its content, and takes precedence over the parent ones
Assert.True(matcher.IsIgnored("src/trace.log"));
Assert.False(matcher.IsIgnored("src/important.log"));

// Enumerate the files that are not ignored. The enumeration does not go into src/bin.
var files = matcher.EnumerateFiles()
    .Select(path => Path.GetRelativePath(rootDirectory.FullPath, path).Replace('\\', '/'))
    .Order(StringComparer.Ordinal)
    .ToList();

Assert.Equal([".gitignore", "src/.gitignore", "src/Program.cs", "src/important.log"], files);

Constructors

NameDescription
GitIgnoreMatcher(string, GitIgnoreMatcherOptions?)Initializes a new instance of the GitIgnoreMatcher class.

GitIgnoreMatcher(string, GitIgnoreMatcherOptions?)

GitIgnoreMatcher.cs

Initializes a new instance of the GitIgnoreMatcher class.

public GitIgnoreMatcher(string rootDirectory, GitIgnoreMatcherOptions? options = null)

Parameters

rootDirectory string
The root directory of the git working tree.
options GitIgnoreMatcherOptions?
The options, or null to use the default ones.

Properties

NameDescription
RootDirectoryGets the full path of the root directory of the git working tree.

RootDirectory

GitIgnoreMatcher.cs

Gets the full path of the root directory of the git working tree.

public string RootDirectory { get; }

Property value

string

Methods

NameDescription
EnumerateFiles(EnumerationOptions?)Enumerates the files of the working tree that are not ignored.
IsIgnored(ReadOnlySpan<char>, PathItemType)Determines whether a path of the working tree is ignored.
IsIgnored(string)Determines whether a path of the working tree is ignored.

EnumerateFiles(EnumerationOptions?)

GitIgnoreMatcher.cs

Enumerates the files of the working tree that are not ignored.

public IEnumerable<string> EnumerateFiles(EnumerationOptions? options = null)

Parameters

options EnumerationOptions?
Options for controlling the enumeration, or null to enumerate every subdirectory, including the hidden entries.

Returns

IEnumerable<string> The full paths of the files that git does not ignore.

Remarks

The enumeration does not go into the ignored directories, the .git directories, and the symbolic links to a directory, which are returned as files as git does. It returns the files that git lists with git ls-files --cached --others --exclude-standard, except the ignored files that are tracked.

IsIgnored overloads

IsIgnored(ReadOnlySpan<char>, PathItemType)

GitIgnoreMatcher.cs

Determines whether a path of the working tree is ignored.

public bool IsIgnored(ReadOnlySpan<char> path, PathItemType itemType)
Parameters
path ReadOnlySpan<char>
The path relative to GitIgnoreMatcher.RootDirectory.
itemType PathItemType
The type of the item.
Returns

bool true if git ignores the path, or one of its parent directories; otherwise, false.

IsIgnored(string)

GitIgnoreMatcher.cs

Determines whether a path of the working tree is ignored.

public bool IsIgnored(string path)
Parameters
path string
The path relative to GitIgnoreMatcher.RootDirectory. A path ending with a directory separator is a directory; otherwise, the file system tells whether the path is a directory.
Returns

bool true if git ignores the path; otherwise, false.