codeowners

README

co: code owners command-line tool

A CLI for GitHub's CODEOWNERS file.

This repository is forked from https://github.com/hmarr/codeowners. This is the most correct implementation of Github's rules engine I've found. Other solutions (e.g., Gitlab) may have differences which may not be featured here.

Installation

Local Usage

You can download a binary from the releases page and put the co binary somewhere in your path.

Usage

co help

Usage:
  co [command]

Available Commands:
  diff        Print a unified diff of file ownership
  fmt         Normalize CODEOWNERS format
  help        Help about any command
  lint        Validate codeowners file
  stats       Display code ownership statistics
  version     Print code version
  who         List code owners for file(s)
  why         Identify which rule effects ownership for a single file.

Flags:
  -f, --file string   CODEOWNERS file path
  -h, --help          help for co

Use "co [command] --help" for more information about a command.

Documentation

Overview

Package codeowners needs documentation.

Index

• Constants
• func ConsolidateTree(tree *FileTree, mockableFsStat ...FsStat)
• func FindFileAtStandardLocation() string
• func LsFiles(ref string) ([]string, error)
• type FileTree
  • func NewFileTree(rules []Rule) *FileTree
  • func (f *FileTree) String() string
• type FilesPerOwner
• type FsStat
• type Owner
  • func (o Owner) String() string
• type OwnerStats
  • func CalculateOwnershipStats(files Owners) OwnerStats
• type Owners
  • func ListOwners(rules Ruleset, files []string, ownerFilters []string, showUnowned bool) (Owners, error)
  • func (x Owners) Len() int
  • func (x Owners) Less(a, b int) bool
  • func (x Owners) Swap(a, b int)
• type Rule
  • func LoadFile(path string) ([]Rule, error)
  • func LoadFileAtRef(ref, path string) ([]Rule, error)
  • func LoadFileFromStandardLocation() ([]Rule, error)
  • func LoadFileFromStandardLocationAtRef(ref string) ([]Rule, error)
  • func ParseFile(f io.Reader) ([]Rule, error)
  • func (r *Rule) Match(path string) (bool, error)
  • func (r *Rule) RawPattern() string
  • func (r *Rule) String() string
• type Ruleset
  • func (r Ruleset) Match(path string) (*Rule, error)

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

Functions

func ConsolidateTree

func ConsolidateTree(tree *FileTree, mockableFsStat ...FsStat)

func FindFileAtStandardLocation

func FindFileAtStandardLocation() string

FindFileAtStandardLocation loops through the standard locations for CODEOWNERS files (./, .github/, docs/), and returns the first place a CODEOWNERS file is found. If run from a git repository, all paths are relative to the repository root.

func LsFiles

func LsFiles(ref string) ([]string, error)

Types

type FileTree

type FileTree struct {
	// contains filtered or unexported fields
}

func NewFileTree

func NewFileTree(rules []Rule) *FileTree

func (*FileTree) String

func (f *FileTree) String() string

String will print all rules in lexicographical order.

type FilesPerOwner

type FilesPerOwner struct {
	Owner      string  `json:"owner"`
	Count      int     `json:"fileCount"`
	Percentage float64 `json:"percentage"`
}

type FsStat

type FsStat func(string) (os.FileInfo, error)

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.

func (Owner) String

func (o Owner) String() string

String returns a string representation of the owner. For email owners, it simply returns the email address. For user and team owners it prepends an '@' to the owner.

type OwnerStats

type OwnerStats struct {
	TotalFiles    int             `json:"totalFiles"`
	OwnedFiles    int             `json:"ownedFiles"`
	UnownedFiles  int             `json:"unownedFiles"`
	OwnerCount    int             `json:"ownerCount"`
	FilesPerOwner []FilesPerOwner `json:"filesPerOwner"`
}

func CalculateOwnershipStats

func CalculateOwnershipStats(files Owners) OwnerStats

type Owners

type Owners []*r

func ListOwners

func ListOwners(rules Ruleset, files []string, ownerFilters []string, showUnowned bool) (Owners, error)

ListOwners returns a list of structured output. Callers must format for printing.

func (Owners) Len

func (x Owners) Len() int

func (Owners) Less

func (x Owners) Less(a, b int) bool

func (Owners) Swap

func (x Owners) Swap(a, b int)

type Rule

type Rule struct {
	SourceLine int

	Owners []string
	// contains filtered or unexported fields
}

Rule is a CODEOWNERS rule that maps a gitignore-style path pattern to a set of owners.

func LoadFile

func LoadFile(path string) ([]Rule, error)

LoadFile loads and parses a CODEOWNERS file at the path specified.

func LoadFileAtRef

func LoadFileAtRef(ref, path string) ([]Rule, error)

LoadFileAtRef loads and parses a CODEOWNERS file from a historical commit. If ref is an empty string, file will be read from disk.

func LoadFileFromStandardLocation

func LoadFileFromStandardLocation() ([]Rule, error)

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 LoadFileFromStandardLocationAtRef

func LoadFileFromStandardLocationAtRef(ref string) ([]Rule, error)

func ParseFile

func ParseFile(f io.Reader) ([]Rule, error)

ParseFile parses a CODEOWNERS file, returning a set of rules.

func (*Rule) Match

func (r *Rule) Match(path string) (bool, error)

Match tests whether the provided matches the rule's pattern.

func (*Rule) RawPattern

func (r *Rule) RawPattern() string

RawPattern returns the rule's gitignore-style path pattern.

func (*Rule) String

func (r *Rule) String() string

type Ruleset

type Ruleset []Rule

Ruleset is a collection of CODEOWNERS rules.

func (Ruleset) Match

func (r Ruleset) Match(path string) (*Rule, error)

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.