git-codeowners [--version|--help|--manual]
- git-codeowners [show] [--format FORMAT] [--[no-]project] [PATH...]
+ git-codeowners [show] [--format FORMAT] [--owner OWNER]...
+ [--pattern PATTERN]... [--[no-]patterns]
+ [--project PROJECT]... [--[no-]projects] [PATH...]
git-codeowners owners [--format FORMAT] [--pattern PATTERN]
=head1 DESCRIPTION
-F<git-codeowners> is yet another CLI tool for managing F<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).
+F<git-codeowners> is yet another CLI tool for managing F<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).
-B<THIS IS EXPERIMENTAL!> The interface of this tool and its modules will
-probably change as I field test some things. Feedback welcome.
+B<THIS IS EXPERIMENTAL!> The interface of this tool and its modules will probably change as I field
+test some things. Feedback welcome.
+
+=head1 INSTALL
+
+There are several ways to install F<git-codeowners> to your system.
+
+=head2 from CPAN
+
+You can install F<git-codeowners> using L<cpanm>:
+
+ cpanm App::Codeowners
+
+=head2 from GitHub
+
+You can also choose to download F<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
=head1 OPTIONS
You can also use C<--manual> to print the full documentation.
+=head2 --color
+
+Enable colorized output.
+
+Color is ON by default on terminals; use C<--no-color> to disable. Some environment variables may
+also alter the behavior of colorizing output:
+
+=for :list
+* C<NO_COLOR> - Set to disable color (same as C<--no-color>).
+* C<COLOR_DEPTH> - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
+
=head2 --format
Specify the output format to use. See L</FORMAT>.
=head2 --shell-completion
- eval "$(lintany --shell-completion)"
+ eval "$(git-codeowners --shell-completion)"
Print shell code to enable completion to C<STDOUT>, and exit.
=head2 show
- git-codeowners [show] [--format FORMAT] [--[no-]project] [PATH...]
+ git-codeowners [show] [--format FORMAT] [--owner OWNER]...
+ [--pattern PATTERN]... [--[no-]patterns]
+ [--project PROJECT]... [--[no-]projects] [PATH...]
Show owners of one or more files in a repo.
+If C<--owner>, C<--project>, C<--pattern> are set, only show files with matching
+criteria. These can be repeated.
+
+Use C<--patterns> to also show the matching pattern associated with each file.
+
+By default the output might show associated projects if the C<CODEOWNERS> file
+defines them. You can control this by explicitly using C<--projects> or
+C<--no-projects> to always show or always hide defined projects, respectively.
+
=head2 owners
git-codeowners owners [--format FORMAT] [--pattern PATTERN]
+List all owners defined in the F<CODEOWNERS> file.
+
=head2 patterns
git-codeowners patterns [--format FORMAT] [--owner OWNER]
+List all patterns defined in the F<CODEOWNERS> file.
+
=head2 create
git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
* C<csv> - Comma-separated values (requires L<Text::CSV>)
* C<json:pretty> - Pretty JSON (requires L<JSON::MaybeXS>)
* C<json> - JSON (requires L<JSON::MaybeXS>)
-* C<table> - Table (requires L<Text::Table>)
+* C<table> - Table (requires L<Text::Table::Any>)
* C<tsv> - Tab-separated values (requires L<Text::CSV>)
* C<yaml> - YAML (requires L<YAML>)
* C<FORMAT> - Custom format (see below)
-You can specify a custom format using printf-like format sequences.
+=head2 Format string
+
+You can specify a custom format using printf-like format sequences. These are the items that can be
+substituted:
+
+=for :list
+* C<%F> - Filename
+* C<%O> - Owner or owners
+* C<%P> - Project
+* C<%T> - Pattern
+* C<%n> - newline
+* C<%t> - tab
+* C<%%> - 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:
+
+=for :list
+* C<quote> - Quote the replacement string.
+* C<color:FFFFFF> - Colorize the replacement string (if color is ON).
+* C<nocolor> - Do not colorize replacement string.
+
+=head2 Format table
+
+Table formatting can be done by one of several different modules, each with its own features and
+bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
+C<PERL_TEXT_TABLE> environment variable if desired, like this:
+
+ PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
+
+The list of available modules is at L<Text::Table::Any/@BACKENDS>.
+
+=head1 CAVEATS
+
+=for :list
+* Some commands require F<git> (at least version 1.8.5).
=cut