hmarr / codeowners

🔒 Command line tool and Go library for CODEOWNERS files

codeowners

A CLI and Go library for GitHub's CODEOWNERS file.

Command line tool

The codeowners CLI identifies the owners for files in a local repository or directory.

Installation

If you're on macOS, you can install the CLI from the homebrew tap.

$ brew tap hmarr/tap
$ brew install codeowners

Otherwise, grab a binary from the releases page or install from source with go install:

$ go install github.com/hmarr/codeowners/cmd/codeowners@latest

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
  -u, --unowned         only show unowned files (can be combined with -o)

$ ls
CODEOWNERS       DOCUMENTATION.md README.md        example.go       example_test.go

$ cat CODEOWNERS
*.go       @example/go-engineers
*.md       @example/docs-writers
README.md  [e-mail]

$ codeowners
CODEOWNERS                           (unowned)
README.md                            [e-mail]
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                            [e-mail]
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

Pass the --unowned flag to only show unowned files.

$ codeowners -u
CODEOWNERS                           (unowned)

Go library

A package for parsing CODEOWNERS files and matching files to owners.

Installation

$ go get github.com/hmarr/codeowners

Usage

Full documentation is available at pkg.go.dev.

Here's a quick example to get you started:

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)
}