Dogcows Code - chaz/git-codeowners/blob - bin/git-codeowners

   1 #! perl
   2 # ABSTRACT: A tool for managing CODEOWNERS files
   3 # PODNAME: git-codeowners
   4
   5 =head1 SYNOPSIS
   6
   7     git-codeowners [--version|--help|--manual]
   8
   9     git-codeowners [show] [--format FORMAT] [--owner OWNER]...
  10                    [--pattern PATTERN]... [--[no-]patterns]
  11                    [--project PROJECT]... [--[no-]projects] [PATH...]
  12
  13     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
  14
  15     git-codeowners patterns [--format FORMAT] [--owner OWNER]
  16
  17     git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
  18
  19     # enable bash shell completion
  20     eval "$(git-codeowners --shell-completion)"
  21
  22 =head1 DESCRIPTION
  23
  24 F<git-codeowners> is yet another CLI tool for managing F<CODEOWNERS> files in git repos. In
  25 particular, it can be used to quickly find out who owns a particular file in a monorepo (or
  26 monolith).
  27
  28 B<THIS IS EXPERIMENTAL!> The interface of this tool and its modules will probably change as I field
  29 test some things. Feedback welcome.
  30
  31 =head1 INSTALL
  32
  33 There are several ways to install F<git-codeowners> to your system.
  34
  35 =head2 from CPAN
  36
  37 You can install F<git-codeowners> using L<cpanm>:
  38
  39     cpanm App::Codeowners
  40
  41 =head2 from GitHub
  42
  43 You can also choose to download F<git-codeowners> as a self-contained executable:
  44
  45     curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
  46     chmod +x git-codeowners
  47
  48 To hack on the code, clone the repo instead:
  49
  50     git clone https://github.com/chazmcgarvey/git-codeowners.git
  51     cd git-codeowners
  52     make bootstrap      # installs dependencies; requires cpanm
  53
  54 =head1 OPTIONS
  55
  56 =head2 --version
  57
  58 Print the program name and version to C<STDOUT>, and exit.
  59
  60 Alias: C<-v>
  61
  62 =head2 --help
  63
  64 Print the synopsis to C<STDOUT>, and exit.
  65
  66 Alias: C<-h>
  67
  68 You can also use C<--manual> to print the full documentation.
  69
  70 =head2 --color
  71
  72 Enable colorized output.
  73
  74 Color is ON by default on terminals; use C<--no-color> to disable. Some environment variables may
  75 also alter the behavior of colorizing output:
  76
  77 =for :list
  78 * C<NO_COLOR> - Set to disable color (same as C<--no-color>).
  79 * C<COLOR_DEPTH> - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
  80
  81 =head2 --format
  82
  83 Specify the output format to use. See L</FORMAT>.
  84
  85 Alias: C<-f>
  86
  87 =head2 --shell-completion
  88
  89     eval "$(lintany --shell-completion)"
  90
  91 Print shell code to enable completion to C<STDOUT>, and exit.
  92
  93 Does not yet support Zsh...
  94
  95 =head1 COMMANDS
  96
  97 =head2 show
  98
  99     git-codeowners [show] [--format FORMAT] [--owner OWNER]...
 100                    [--pattern PATTERN]... [--[no-]patterns]
 101                    [--project PROJECT]... [--[no-]projects] [PATH...]
 102
 103 Show owners of one or more files in a repo.
 104
 105 If C<--owner>, C<--project>, C<--pattern> are set, only show files with matching
 106 criteria. These can be repeated.
 107
 108 Use C<--patterns> to also show the matching pattern associated with each file.
 109
 110 By default the output might show associated projects if the C<CODEOWNERS> file
 111 defines them. You can control this by explicitly using C<--projects> or
 112 C<--no-projects> to always show or always hide defined projects, respectively.
 113
 114 =head2 owners
 115
 116     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
 117
 118 List all owners defined in the F<CODEOWNERS> file.
 119
 120 =head2 patterns
 121
 122     git-codeowners patterns [--format FORMAT] [--owner OWNER]
 123
 124 List all patterns defined in the F<CODEOWNERS> file.
 125
 126 =head2 create
 127
 128     git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 129
 130 Create a new F<CODEOWNERS> file for a specified repo (or current directory).
 131
 132 =head2 update
 133
 134     git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 135
 136 Update the "unowned" list of an existing F<CODEOWNERS> file for a specified
 137 repo (or current directory).
 138
 139 =head1 FORMAT
 140
 141 The C<--format> argument can be one of:
 142
 143 =for :list
 144 * C<csv> - Comma-separated values (requires L<Text::CSV>)
 145 * C<json:pretty> - Pretty JSON (requires L<JSON::MaybeXS>)
 146 * C<json> - JSON (requires L<JSON::MaybeXS>)
 147 * C<table> - Table (requires L<Text::Table::Any>)
 148 * C<tsv> - Tab-separated values (requires L<Text::CSV>)
 149 * C<yaml> - YAML (requires L<YAML>)
 150 * C<FORMAT> - Custom format (see below)
 151
 152 =head2 Format string
 153
 154 You can specify a custom format using printf-like format sequences. These are the items that can be
 155 substituted:
 156
 157 =for :list
 158 * C<%F> - Filename
 159 * C<%O> - Owner or owners
 160 * C<%P> - Project
 161 * C<%T> - Pattern
 162 * C<%n> - newline
 163 * C<%t> - tab
 164 * C<%%> - percent sign
 165
 166 The syntax also allows padding and some filters. Examples:
 167
 168     git-codeowners show -f ' * %-50F %O'                # default for "show"
 169     git-codeowners show -f '%{quote}F,%{quote}O'        # ad hoc CSV
 170     git-codeowners patterns -f '--> %{color:0c0}T'      # whatever...
 171
 172 Available filters:
 173
 174 =for :list
 175 * C<quote> - Quote the replacement string.
 176 * C<color:FFFFFF> - Colorize the replacement string (if color is ON).
 177 * C<nocolor> - Do not colorize replacement string.
 178
 179 =head2 Format table
 180
 181 Table formatting can be done by one of several different modules, each with its own features and
 182 bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
 183 C<PERL_TEXT_TABLE> environment variable if desired, like this:
 184
 185     PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
 186
 187 The list of available modules is at L<Text::Table::Any/@BACKENDS>.
 188
 189 =head1 CAVEATS
 190
 191 =for :list
 192 * Some commands require F<git> (at least version 1.8.5).
 193
 194 =cut
 195
 196 # FATPACK - Do not remove this line.
 197
 198 use warnings;
 199 use strict;
 200
 201 use App::Codeowners;
 202
 203 our $VERSION = '9999.999'; # VERSION
 204
 205 App::Codeowners->main(@ARGV);