#! perl
# ABSTRACT: A tool for managing CODEOWNERS files
# PODNAME: git-codeowners

=head1 SYNOPSIS

    git-codeowners [--version|--help|--manual]

    git-codeowners [show] [--format FORMAT] [--[no-]project] [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)"

=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).

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

=head2 --version

Print the program name and version to C<STDOUT>, and exit.

Alias: C<-v>

=head2 --help

Print the synopsis to C<STDOUT>, and exit.

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>.

Alias: C<-f>

=head2 --shell-completion

    eval "$(lintany --shell-completion)"

Print shell code to enable completion to C<STDOUT>, and exit.

Does not yet support Zsh...

=head1 COMMANDS

=head2 show

    git-codeowners [show] [--format FORMAT] [--[no-]project] [PATH...]

Show owners of one or more files in a repo.

=head2 owners

    git-codeowners owners [--format FORMAT] [--pattern PATTERN]

=head2 patterns

    git-codeowners patterns [--format FORMAT] [--owner OWNER]

=head2 create

    git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]

Create a new F<CODEOWNERS> file for a specified repo (or current directory).

=head2 update

    git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]

Update the "unowned" list of an existing F<CODEOWNERS> file for a specified
repo (or current directory).

=head1 FORMAT

The C<--format> argument can be one of:

=for :list
* 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::Any>)
* C<tsv> - Tab-separated values (requires L<Text::CSV>)
* C<yaml> - YAML (requires L<YAML>)
* C<FORMAT> - Custom format (see below)

=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>.

=head1 CAVEATS

=for :list
* Some commands require F<git> (at least version 1.8.5).

=cut

# FATPACK - Do not remove this line.

use warnings;
use strict;

use App::Codeowners;

our $VERSION = '9999.999'; # VERSION

App::Codeowners->main(@ARGV);