git-codeowners - A tool for managing CODEOWNERS files
version 0.51
git-codeowners [--version|--help|--manual] git-codeowners [show] [--format FORMAT] [--owner OWNER]... [--pattern PATTERN]... [--[no-]patterns] [--project PROJECT]... [--[no-]projects] [PATH...] git-codeowners owners [--format FORMAT] [--pattern PATTERN] git-codeowners patterns [--format FORMAT] [--owner OWNER] git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH] # enable bash shell completion eval "$(git-codeowners --shell-completion)"
git-codeowners is yet another CLI tool for managing CODEOWNERS files in git repos. In particular, it can be used to quickly find out who owns a particular file in a monorepo (or monolith).
THIS IS EXPERIMENTAL! The interface of this tool and its modules will probably change as I field test some things. Feedback welcome.
There are several ways to install git-codeowners to your system.
You can install git-codeowners using cpanm:
cpanm App::Codeowners
You can also choose to download git-codeowners as a self-contained executable:
curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners chmod +x git-codeowners
To hack on the code, clone the repo instead:
git clone https://github.com/chazmcgarvey/git-codeowners.git cd git-codeowners make bootstrap # installs dependencies; requires cpanm
Print the program name and version to STDOUT, and exit.
STDOUT
Alias: -v
-v
Print the synopsis to STDOUT, and exit.
Alias: -h
-h
You can also use --manual to print the full documentation.
--manual
Enable colorized output.
Color is ON by default on terminals; use --no-color to disable. Some environment variables may also alter the behavior of colorizing output:
--no-color
NO_COLOR - Set to disable color (same as --no-color).
NO_COLOR
COLOR_DEPTH - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
COLOR_DEPTH
Specify the output format to use. See "FORMAT".
Alias: -f
-f
eval "$(git-codeowners --shell-completion)"
Print shell code to enable completion to STDOUT, and exit.
Does not yet support Zsh...
git-codeowners [show] [--format FORMAT] [--owner OWNER]... [--pattern PATTERN]... [--[no-]patterns] [--project PROJECT]... [--[no-]projects] [PATH...] [--[no-]expand-aliases]
Show owners of one or more files in a repo.
If --owner, --project, --pattern are set, only show files with matching criteria. These can be repeated.
--owner
--project
--pattern
Use --patterns to also show the matching pattern associated with each file.
--patterns
By default the output might show associated projects if the CODEOWNERS file defines them. You can control this by explicitly using --projects or --no-projects to always show or always hide defined projects, respectively.
CODEOWNERS
--projects
--no-projects
Use --expand-aliases to show owners that are group aliases defined in the CODEOWNERS file as their aliased owners.
--expand-aliases
git-codeowners owners [--format FORMAT] [--pattern PATTERN]
List all owners defined in the CODEOWNERS file.
git-codeowners patterns [--format FORMAT] [--owner OWNER]
List all patterns defined in the CODEOWNERS file.
git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
Create a new CODEOWNERS file for a specified repo (or current directory).
git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
Update the "unowned" list of an existing CODEOWNERS file for a specified repo (or current directory).
The --format argument can be one of:
--format
csv - Comma-separated values (requires Text::CSV)
csv
json:pretty - Pretty JSON (requires JSON::MaybeXS)
json:pretty
json - JSON (requires JSON::MaybeXS)
json
table - Table (requires Text::Table::Any)
table
tsv - Tab-separated values (requires Text::CSV)
tsv
yaml - YAML (requires YAML)
yaml
FORMAT - Custom format (see below)
FORMAT
You can specify a custom format using printf-like format sequences. These are the items that can be substituted:
%F - Filename
%F
%O - Owner or owners
%O
%P - Project
%P
%T - Pattern
%T
%n - newline
%n
%t - tab
%t
%% - percent sign
%%
The syntax also allows padding and some filters. Examples:
git-codeowners show -f ' * %-50F %O' # default for "show" git-codeowners show -f '%{quote}F,%{quote}O' # ad hoc CSV git-codeowners patterns -f '--> %{color:0c0}T' # whatever...
Available filters:
quote - Quote the replacement string.
quote
color:FFFFFF - Colorize the replacement string (if color is ON).
color:FFFFFF
nocolor - Do not colorize replacement string.
nocolor
Table formatting can be done by one of several different modules, each with its own features and bugs. The default module is Text::Table::Tiny, but this can be overridden using the PERL_TEXT_TABLE environment variable if desired, like this:
PERL_TEXT_TABLE
PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
The list of available modules is at "@BACKENDS" in Text::Table::Any.
If you set GIT_CODEOWNERS_ALIASES in the environment to a true value, the parser will parse group aliases which are supported by some applications.
GIT_CODEOWNERS_ALIASES
Some commands require git (at least version 1.8.5).
Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/git-codeowners/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Charles McGarvey <chazmcgarvey@brokenzipper.com>
This software is copyright (c) 2021 by Charles McGarvey.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install App::Codeowners, copy and paste the appropriate command in to your terminal.
cpanm
CPAN shell
perl -MCPAN -e shell install App::Codeowners
For more information on module installation, please visit the detailed CPAN module installation guide.