use Text::Table::Any for table formatting

[chaz/git-codeowners] / bin / git-codeowners

diff --git a/bin/git-codeowners b/bin/git-codeowners
index e620ea8bb416d02cb08fbae884b35ffbb5647212..60e79b27bcd2a8d04b67ca38435c6f06fe718e68 100755 (executable)
--- a/bin/git-codeowners
+++ b/bin/git-codeowners
@@ -42,6 +42,17 @@ Alias: C<-h>
 
 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>.
@@ -93,12 +104,47 @@ The C<--format> argument can be one of:
 * 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 Custom
+
+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 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>.
 
 =cut