github-codeowners

A CLI tool for working with GitHub CODEOWNERS.

Things it does:

• Calculate ownership stats
• Find out who owns each and every file (ignoring files listed in .gitignore)
• Find out who owns a single file
• Find out who owns your staged files
• Outputs in a bunch of script friendly handy formats for integrations (CSV and JSONL)
• Validates that your CODEOWNERS file is valid

Installation

Install via npm globally then run

1$ npm i -g github-codeowners
2$ github-codeowners --help 
3Usage: github-codeowners [options] [command]

Commands

Audit

Compares every file in your current (or specified) directory against your CODEOWNERS rules and outputs the result of who owns each file.

1$ cd <your awesome project> 
2$ github-codeowners audit
3README.md
4package.json
5src/cli.ts      @jjmschofield
6...

Ownership stats:

1$ github-codeowners audit -s
2--- Counts ---
3Total: 24 files (1378 lines)
4Loved: 10 files (494 lines)
5Unloved: 14 files (884 lines)
6--- Owners ---
7@jjmschofield: 10 files (494 lines)

Only files in a specific directory:

1$ github-codeowners audit -r src/
2src/cli.ts      @jjmschofield
3src/commands/audit.ts   @jjmschofield
4...

Only unowned files:

1$ github-codeowners audit -u
2.github/CODEOWNERS
3.gitignore

Output in JSONL:

1$ github-codeowners audit -o jsonl
2{"path":"src/commands/audit.ts","owners":["@jjmschofield"],"lines":48}
3...

Output in CSV:

1$ github-codeowners audit -o csv
2src/commands/audit.ts,@jjmschofield

Full usage information:

1$ github-codeowners audit --help
2Usage: github-codeowners audit [options]
3
4list the owners for all files
5
6Options:
7  -d, --dir <dirPath>          path to VCS directory (default: "<current working directory>")
8  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
9  -o, --output <outputFormat>  how to output format eg: simple, jsonl, csv (default: "simple")
10  -u, --unloved                unowned files only (default: false)
11  -g, --only-git               consider only files tracked by git (default: false)
12  -s, --stats                  output stats (default: true)
13  -r, --root <rootPath>        the root path to filter files by (default: "")
14  -h, --help                   output usage information

Who

Tells you who owns a given file:

1$ cd <your awesome project> 
2$ github-codeowners who <file>
3<file> @some/team

Full usage:

1$ github-codeowners who --help                   
2Usage: github-codeowners who [options] <file>
3
4lists owners of a specific file
5
6Options:
7  -d, --dir <dirPath>          path to VCS directory (default: "/Users/jjmschofield/projects/github/snyk/registry")
8  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
9  -o, --output <outputFormat>  how to output format eg: simple, jsonl, csv (default: "simple")
10  -h, --help                   output usage information

Git

Provides a list of files with their owners between commits (against the current version of CODEOWNERS).

Ownership of all files staged for commit:

1$ cd <your awesome project>
2$ github-codeowners git

Ownership of files existing at a specific commit:

1$ github-codeowners git <commit sha>

Ownership of files changed between two commits:

1$ github-codeowners git <commit sha> <commit sha>

Output stats:

1$ github-codeowners git -s

Full usage:

1$ github-codeowners git --help                                                                                       
2Usage: github-codeowners git [options] [shaA] [shaB]
3
4lists owners of files changed between commits, a commit against head or staged against head.
5
6Options:
7  -d, --dir <dirPath>          path to VCS directory (default: "/Users/jjmschofield/projects/github/snyk/registry")
8  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
9  -o, --output <outputFormat>  how to output format eg: simple, jsonl, csv (default: "simple")
10  -s, --stats                  output stats, note line counts are not available for this command (default: false)
11  -h, --help                   output usage information

Validate

Validates your CODEOWNERS file to find common mistakes, will throw on errors (such as malformed owners).

1$ cd <your awesome project> 
2$ github-codeowners validate
3Found duplicate rules [ 'some/duplicate/rule @octocat' ]
4Found rules which did not match any files [ 'some/non-existent/path @octocat' ]
5...

Full usage information:

1$ github-codeowners validate --help
2Usage: github-codeowners validate [options]
3
4Validates a CODOWNER file and files in dir
5
6Options:
7  -d, --dir <dirPath>          path to VCS directory (default: "<current working directory>")
8  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
9  -r, --root <rootPath>        the root path to filter files by (default: "")
10  -h, --help                   output usage information

Output Formats

Check github-codeowners <command> --help for support for a given command, however generally the following outputs are supported:

• simple - tab delimited - terminal friendly output
• jsonl - line separated json - useful for streaming data to another command
• csv - csv delimited fields - useful to import into a spreadsheet tool of your choice

Limits and Things to Improve

• It requires node
• It is not optimized
• The output interface might change
• Command syntax might change

Shout outs

Inspired by codeowners but implemented in Typescript with extra bells and whistles.