README
¶
codeowners
A CLI and Go library for GitHub's CODEOWNERS file.
Command line usage
By default, the command line tool will walk the directory tree, printing the code owners of any files that are found.
$ codeowners --help
usage: codeowners <path>...
-f, --file string CODEOWNERS file path
-h, --help show this help message
-o, --owner strings filter results by owner
$ ls
CODEOWNERS DOCUMENTATION.md README.md example.go example_test.go
$ cat CODEOWNERS
*.go @example/go-engineers
*.md @example/docs-writers
README.md product-manager@example.com
$ codeowners
CODEOWNERS (unowned)
README.md product-manager@example.com
example_test.go @example/go-engineers
example.go @example/go-engineers
DOCUMENTATION.md @example/docs-writers
To limit the files the tool looks at, provide one or more paths as arguments.
$ codeowners *.md
README.md product-manager@example.com
DOCUMENTATION.md @example/docs-writers
Pass the --owner flag to filter results by a specific owner.
$ codeowners -o @example/go-engineers
example_test.go @example/go-engineers
example.go @example/go-engineers
Go library usage
package main
import (
"fmt"
"log"
"os"
"github.com/hmarr/codeowners"
)
func main() {
file, err := os.Open("CODEOWNERS")
if err != nil {
log.Fatal(err)
}
ruleset, err := codeowners.ParseFile(file)
if err != nil {
log.Fatal(err)
}
rule, err := ruleset.Match("path/to/file")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Owners: %v\n", rule.Owners)
}
Documentation
¶
Overview ¶
Package codeowners is a library for working with CODEOWNERS files.
CODEOWNERS files map gitignore-style path patterns to sets of owners, which may be GitHub users, GitHub teams, or email addresses. This library parses the CODEOWNERS file format into rulesets, which may then be used to determine the ownership of files.
Usage ¶
To find the owner of a given file, parse a CODEOWNERS file and call Match() on the resulting ruleset.
ruleset, err := codeowners.ParseFile(file)
if err != nil {
log.Fatal(err)
}
rule, err := ruleset.Match("path/to/file")
if err != nil {
log.Fatal(err)
}
Command line interface ¶
A command line interface is also available in the cmd/codeowners package. When run, it will walk the directory tree showing the code owners for each file encountered. The help flag lists available options.
$ codeowners --help
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/hmarr/codeowners"
)
func main() {
f := bytes.NewBufferString("src/**/*.c @acme/c-developers")
ruleset, err := codeowners.ParseFile(f)
if err != nil {
panic(err)
}
match, err := ruleset.Match("src/foo.c")
fmt.Println(match.Owners)
match, err = ruleset.Match("src/foo.rs")
fmt.Println(match)
}
Output: [@acme/c-developers] <nil>
Index ¶
Examples ¶
Constants ¶
const ( // EmailOwner is the owner type for email addresses. EmailOwner string = "email" // TeamOwner is the owner type for GitHub teams. TeamOwner string = "team" // UsernameOwner is the owner type for GitHub usernames. UsernameOwner string = "username" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Owner ¶
type Owner struct {
// Value is the name of the owner: the email addres, team name, or username.
Value string
// Type will be one of 'email', 'team', or 'username'.
Type string
}
Owner represents an owner found in a rule.
type Rule ¶
type Rule struct {
Owners []Owner
Comment string
LineNumber int
// contains filtered or unexported fields
}
Rule is a CODEOWNERS rule that maps a gitignore-style path pattern to a set of owners.
func (Rule) RawPattern ¶
RawPattern returns the rule's gitignore-style path pattern.
type Ruleset ¶
type Ruleset []Rule
Ruleset is a collection of CODEOWNERS rules.
func LoadFileFromStandardLocation ¶ added in v0.2.0
LoadFileFromStandardLocation loads and parses a CODEOWNERS file at one of the standard locations for CODEOWNERS files (./, .github/, docs/). If run from a git repository, all paths are relative to the repository root.
func ParseFile ¶
ParseFile parses a CODEOWNERS file, returning a set of rules.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/hmarr/codeowners"
)
func main() {
f := bytes.NewBufferString("src/**/*.[hc] @acme/c-developers # C headers and source")
ruleset, err := codeowners.ParseFile(f)
if err != nil {
panic(err)
}
fmt.Println(len(ruleset))
fmt.Println(ruleset[0].RawPattern())
fmt.Println(ruleset[0].Owners[0].String())
fmt.Println(ruleset[0].Comment)
}
Output: 1 src/**/*.[hc] @acme/c-developers C headers and source
func (Ruleset) Match ¶
Match finds the last rule in the ruleset that matches the path provided. When determining the ownership of a file using CODEOWNERS, order matters, and the last matching rule takes precedence.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/hmarr/codeowners"
)
func main() {
f := bytes.NewBufferString("src/**/*.[hc] @acme/c-developers # C headers and source")
ruleset, _ := codeowners.ParseFile(f)
match, _ := ruleset.Match("src")
fmt.Println("src", match != nil)
match, _ = ruleset.Match("src/foo.c")
fmt.Println("src/foo.c", match != nil)
match, _ = ruleset.Match("src/foo/bar.h")
fmt.Println("src/foo/bar.h", match != nil)
match, _ = ruleset.Match("src/foo.rs")
fmt.Println("src/foo.rs", match != nil)
}
Output: src false src/foo.c true src/foo/bar.h true src/foo.rs false
Source Files
Directories