CodeOwnersFile Class

Represents a parsed CODEOWNERS file.

var file = CodeOwnersFile.Parse("* @user1\n*.js @js-owner", CodeOwnersDialect.GitHub);

Assert.Equal("*", file.Entries[0].Pattern);
Assert.Equal("@user1", file.Entries[0].Owners[0].ToString());

Assert.Equal("*.js", file.Entries[1].Pattern);
Assert.Equal("@js-owner", file.Entries[1].Owners[0].ToString());
public sealed class CodeOwnersFile

Remarks

An instance only exists for a valid file: CodeOwnersFile.Parse throws and CodeOwnersFile.TryParse returns false rather than returning a partially parsed file.

Properties

NameDescription
EntriesGets the entries of the file, in the order they appear in it.

Gets the entries of the file, in the order they appear in it.

public IReadOnlyList<CodeOwnersEntry> Entries { get; }

Property value

IReadOnlyList<CodeOwnersEntry>

Remarks

CODEOWNERS resolution is last-match-wins, so the last entry whose CodeOwnersEntry.Pattern matches a path owns it.

Methods

NameDescription
FindEntries(string)Finds the entries that own the path of a file, as the host of the dialect the file was parsed with does.
GetOwners(string)Gets the owners of the path of a file, as the host of the dialect the file was parsed with does.
Parse(ReadOnlySpan<char>, CodeOwnersDialect)Parses the content of a CODEOWNERS file.
Parse(string, CodeOwnersDialect)Parses the content of a CODEOWNERS file.
TryParse(ReadOnlySpan<char>, CodeOwnersDialect, CodeOwnersFile?)Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.
TryParse(ReadOnlySpan<char>, CodeOwnersDialect, CodeOwnersFile?, CodeOwnersParseError)Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.
TryParse(string, CodeOwnersDialect, CodeOwnersFile?)Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.
TryParse(string, CodeOwnersDialect, CodeOwnersFile?, CodeOwnersParseError)Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.

FindEntries(string)

CodeOwnersFile.cs

Finds the entries that own the path of a file, as the host of the dialect the file was parsed with does.

public IReadOnlyList<CodeOwnersEntry> FindEntries(string path)

Parameters

path string
The path of a file, relative to the root of the repository, with / as the separator. A leading / is ignored. The comparison is case-sensitive.

Returns

IReadOnlyList<CodeOwnersEntry> The entries that own path, in the order of the file, or an empty list when no entry matches it. With CodeOwnersDialect.GitHub, the last entry whose pattern matches the path. With CodeOwnersDialect.GitLab, the last matching entry of each section, except the sections where an exclusion matches the path.

Remarks

An entry without owners is returned too: it means that the path is explicitly left unowned. Use CodeOwnersFile.GetOwners to get the owners. GitLab merges the sections that have the same name, ignoring case: they count as one section.

Example

var file = CodeOwnersFile.Parse("""
    * @maintainers

    [Backend]
    *.cs @backend-team

    [Docs]
    *.md @docs-team
    /src/ @writers
    """, CodeOwnersDialect.GitLab);

// GitLab applies the last matching entry of each section
IReadOnlyList<CodeOwnersEntry> entries = file.FindEntries("src/Program.cs");
Assert.Equal(["*", "*.cs", "/src/"], entries.Select(entry => entry.Pattern));
Assert.Equal([null, "Backend", "Docs"], entries.Select(entry => entry.Section?.Name));

GetOwners(string)

CodeOwnersFile.cs

Gets the owners of the path of a file, as the host of the dialect the file was parsed with does.

public IReadOnlyList<CodeOwner> GetOwners(string path)

Parameters

path string
The path of a file, relative to the root of the repository, with / as the separator. A leading / is ignored. The comparison is case-sensitive.

Returns

IReadOnlyList<CodeOwner> The owners of the entries returned by CodeOwnersFile.FindEntries, without duplicates. Empty when no entry matches the path, or when the matching entries leave it unowned.

Example

var file = CodeOwnersFile.Parse("""
    * @maintainers
    *.md @docs-team
    /docs/internal/
    """, CodeOwnersDialect.GitHub);

Assert.Equal(["maintainers"], file.GetOwners("src/Program.cs").Select(owner => owner.Name));
Assert.Equal(["docs-team"], file.GetOwners("docs/README.md").Select(owner => owner.Name));

// The last matching entry has no owners: the path is unowned
Assert.Empty(file.GetOwners("docs/internal/notes.md"));

Parse overloads

Parse(ReadOnlySpan<char>, CodeOwnersDialect)

CodeOwnersFile.cs

Parses the content of a CODEOWNERS file.

public static CodeOwnersFile Parse(ReadOnlySpan<char> content, CodeOwnersDialect dialect)
Parameters
content ReadOnlySpan<char>
The content of the CODEOWNERS file.
dialect CodeOwnersDialect
The syntax content uses. Sections are only recognized by CodeOwnersDialect.GitLab.
Returns

CodeOwnersFile The parsed CodeOwnersFile.

Exceptions
CodeOwnersParseException
content is not a valid CODEOWNERS file. Parsing stops at the first error.
Remarks

The returned CodeOwnersFile does not reference content: every value it exposes is copied out of it.

Parse(string, CodeOwnersDialect)

CodeOwnersFile.cs

Parses the content of a CODEOWNERS file.

public static CodeOwnersFile Parse(string content, CodeOwnersDialect dialect)
Parameters
content string
The content of the CODEOWNERS file.
dialect CodeOwnersDialect
The syntax content uses. Sections are only recognized by CodeOwnersDialect.GitLab.
Returns

CodeOwnersFile The parsed CodeOwnersFile.

Exceptions
CodeOwnersParseException
content is not a valid CODEOWNERS file. Parsing stops at the first error.

TryParse overloads

TryParse(ReadOnlySpan<char>, CodeOwnersDialect, CodeOwnersFile?)

CodeOwnersFile.cs

Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.

public static bool TryParse(ReadOnlySpan<char> content, CodeOwnersDialect dialect, out CodeOwnersFile? file)
Parameters
content ReadOnlySpan<char>
The content of the CODEOWNERS file.
dialect CodeOwnersDialect
The syntax content uses. Sections are only recognized by CodeOwnersDialect.GitLab.
file CodeOwnersFile?
When this method returns true, contains the parsed CodeOwnersFile; otherwise, null.
Returns

bool true when content is a valid CODEOWNERS file; otherwise, false.

Remarks

Use the CodeOwnersFile.TryParse overload to know why the file is invalid.

TryParse(ReadOnlySpan<char>, CodeOwnersDialect, CodeOwnersFile?, CodeOwnersParseError)

CodeOwnersFile.cs

Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.

public static bool TryParse(ReadOnlySpan<char> content, CodeOwnersDialect dialect, out CodeOwnersFile? file, out CodeOwnersParseError error)
Parameters
content ReadOnlySpan<char>
The content of the CODEOWNERS file.
dialect CodeOwnersDialect
The syntax content uses. Sections are only recognized by CodeOwnersDialect.GitLab.
file CodeOwnersFile?
When this method returns true, contains the parsed CodeOwnersFile; otherwise, null.
error CodeOwnersParseError
When this method returns false, contains the first error found in content; otherwise, default.
Returns

bool true when content is a valid CODEOWNERS file; otherwise, false.

Remarks

The parsed CodeOwnersFile does not reference content: every value it exposes is copied out of it.

TryParse(string, CodeOwnersDialect, CodeOwnersFile?)

CodeOwnersFile.cs

Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.

public static bool TryParse(string content, CodeOwnersDialect dialect, out CodeOwnersFile? file)
Parameters
content string
The content of the CODEOWNERS file.
dialect CodeOwnersDialect
The syntax content uses. Sections are only recognized by CodeOwnersDialect.GitLab.
file CodeOwnersFile?
When this method returns true, contains the parsed CodeOwnersFile; otherwise, null.
Returns

bool true when content is a valid CODEOWNERS file; otherwise, false.

Remarks

Use the CodeOwnersFile.TryParse overload to know why the file is invalid.

TryParse(string, CodeOwnersDialect, CodeOwnersFile?, CodeOwnersParseError)

CodeOwnersFile.cs

Parses the content of a CODEOWNERS file and returns a value indicating whether it is valid.

public static bool TryParse(string content, CodeOwnersDialect dialect, out CodeOwnersFile? file, out CodeOwnersParseError error)
Parameters
content string
The content of the CODEOWNERS file.
dialect CodeOwnersDialect
The syntax content uses. Sections are only recognized by CodeOwnersDialect.GitLab.
file CodeOwnersFile?
When this method returns true, contains the parsed CodeOwnersFile; otherwise, null.
error CodeOwnersParseError
When this method returns false, contains the first error found in content; otherwise, default.
Returns

bool true when content is a valid CODEOWNERS file; otherwise, false.