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
   6 # FATPACK - Do not remove this line.
   7
   8 use warnings;
   9 use strict;
  10
  11 use App::Codeowners;
  12
  13 our $VERSION = '0.48'; # VERSION
  14
  15 App::Codeowners->main(@ARGV);
  16
  17 __END__
  18
  19 =pod
  20
  21 =encoding UTF-8
  22
  23 =head1 NAME
  24
  25 git-codeowners - A tool for managing CODEOWNERS files
  26
  27 =head1 VERSION
  28
  29 version 0.48
  30
  31 =head1 SYNOPSIS
  32
  33     git-codeowners [--version|--help|--manual]
  34
  35     git-codeowners [show] [--format FORMAT] [--owner OWNER]...
  36                    [--pattern PATTERN]... [--[no-]patterns]
  37                    [--project PROJECT]... [--[no-]projects] [PATH...]
  38
  39     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
  40
  41     git-codeowners patterns [--format FORMAT] [--owner OWNER]
  42
  43     git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
  44
  45     # enable bash shell completion
  46     eval "$(git-codeowners --shell-completion)"
  47
  48 =head1 DESCRIPTION
  49
  50 F<git-codeowners> is yet another CLI tool for managing F<CODEOWNERS> files in git repos. In
  51 particular, it can be used to quickly find out who owns a particular file in a monorepo (or
  52 monolith).
  53
  54 B<THIS IS EXPERIMENTAL!> The interface of this tool and its modules will probably change as I field
  55 test some things. Feedback welcome.
  56
  57 =head1 INSTALL
  58
  59 There are several ways to install F<git-codeowners> to your system.
  60
  61 =head2 from CPAN
  62
  63 You can install F<git-codeowners> using L<cpanm>:
  64
  65     cpanm App::Codeowners
  66
  67 =head2 from GitHub
  68
  69 You can also choose to download F<git-codeowners> as a self-contained executable:
  70
  71     curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
  72     chmod +x git-codeowners
  73
  74 To hack on the code, clone the repo instead:
  75
  76     git clone https://github.com/chazmcgarvey/git-codeowners.git
  77     cd git-codeowners
  78     make bootstrap      # installs dependencies; requires cpanm
  79
  80 =head1 OPTIONS
  81
  82 =head2 --version
  83
  84 Print the program name and version to C<STDOUT>, and exit.
  85
  86 Alias: C<-v>
  87
  88 =head2 --help
  89
  90 Print the synopsis to C<STDOUT>, and exit.
  91
  92 Alias: C<-h>
  93
  94 You can also use C<--manual> to print the full documentation.
  95
  96 =head2 --color
  97
  98 Enable colorized output.
  99
 100 Color is ON by default on terminals; use C<--no-color> to disable. Some environment variables may
 101 also alter the behavior of colorizing output:
 102
 103 =over 4
 104
 105 =item *
 106
 107 C<NO_COLOR> - Set to disable color (same as C<--no-color>).
 108
 109 =item *
 110
 111 C<COLOR_DEPTH> - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
 112
 113 =back
 114
 115 =head2 --format
 116
 117 Specify the output format to use. See L</FORMAT>.
 118
 119 Alias: C<-f>
 120
 121 =head2 --shell-completion
 122
 123     eval "$(git-codeowners --shell-completion)"
 124
 125 Print shell code to enable completion to C<STDOUT>, and exit.
 126
 127 Does not yet support Zsh...
 128
 129 =head1 COMMANDS
 130
 131 =head2 show
 132
 133     git-codeowners [show] [--format FORMAT] [--owner OWNER]...
 134                    [--pattern PATTERN]... [--[no-]patterns]
 135                    [--project PROJECT]... [--[no-]projects] [PATH...]
 136
 137 Show owners of one or more files in a repo.
 138
 139 If C<--owner>, C<--project>, C<--pattern> are set, only show files with matching
 140 criteria. These can be repeated.
 141
 142 Use C<--patterns> to also show the matching pattern associated with each file.
 143
 144 By default the output might show associated projects if the C<CODEOWNERS> file
 145 defines them. You can control this by explicitly using C<--projects> or
 146 C<--no-projects> to always show or always hide defined projects, respectively.
 147
 148 =head2 owners
 149
 150     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
 151
 152 List all owners defined in the F<CODEOWNERS> file.
 153
 154 =head2 patterns
 155
 156     git-codeowners patterns [--format FORMAT] [--owner OWNER]
 157
 158 List all patterns defined in the F<CODEOWNERS> file.
 159
 160 =head2 create
 161
 162     git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 163
 164 Create a new F<CODEOWNERS> file for a specified repo (or current directory).
 165
 166 =head2 update
 167
 168     git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 169
 170 Update the "unowned" list of an existing F<CODEOWNERS> file for a specified
 171 repo (or current directory).
 172
 173 =head1 FORMAT
 174
 175 The C<--format> argument can be one of:
 176
 177 =over 4
 178
 179 =item *
 180
 181 C<csv> - Comma-separated values (requires L<Text::CSV>)
 182
 183 =item *
 184
 185 C<json:pretty> - Pretty JSON (requires L<JSON::MaybeXS>)
 186
 187 =item *
 188
 189 C<json> - JSON (requires L<JSON::MaybeXS>)
 190
 191 =item *
 192
 193 C<table> - Table (requires L<Text::Table::Any>)
 194
 195 =item *
 196
 197 C<tsv> - Tab-separated values (requires L<Text::CSV>)
 198
 199 =item *
 200
 201 C<yaml> - YAML (requires L<YAML>)
 202
 203 =item *
 204
 205 C<FORMAT> - Custom format (see below)
 206
 207 =back
 208
 209 =head2 Format string
 210
 211 You can specify a custom format using printf-like format sequences. These are the items that can be
 212 substituted:
 213
 214 =over 4
 215
 216 =item *
 217
 218 C<%F> - Filename
 219
 220 =item *
 221
 222 C<%O> - Owner or owners
 223
 224 =item *
 225
 226 C<%P> - Project
 227
 228 =item *
 229
 230 C<%T> - Pattern
 231
 232 =item *
 233
 234 C<%n> - newline
 235
 236 =item *
 237
 238 C<%t> - tab
 239
 240 =item *
 241
 242 C<%%> - percent sign
 243
 244 =back
 245
 246 The syntax also allows padding and some filters. Examples:
 247
 248     git-codeowners show -f ' * %-50F %O'                # default for "show"
 249     git-codeowners show -f '%{quote}F,%{quote}O'        # ad hoc CSV
 250     git-codeowners patterns -f '--> %{color:0c0}T'      # whatever...
 251
 252 Available filters:
 253
 254 =over 4
 255
 256 =item *
 257
 258 C<quote> - Quote the replacement string.
 259
 260 =item *
 261
 262 C<color:FFFFFF> - Colorize the replacement string (if color is ON).
 263
 264 =item *
 265
 266 C<nocolor> - Do not colorize replacement string.
 267
 268 =back
 269
 270 =head2 Format table
 271
 272 Table formatting can be done by one of several different modules, each with its own features and
 273 bugs. The default module is L<Text::Table::Tiny>, but this can be overridden using the
 274 C<PERL_TEXT_TABLE> environment variable if desired, like this:
 275
 276     PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
 277
 278 The list of available modules is at L<Text::Table::Any/@BACKENDS>.
 279
 280 =head1 CAVEATS
 281
 282 =over 4
 283
 284 =item *
 285
 286 Some commands require F<git> (at least version 1.8.5).
 287
 288 =back
 289
 290 =head1 BUGS
 291
 292 Please report any bugs or feature requests on the bugtracker website
 293 L<https://github.com/chazmcgarvey/git-codeowners/issues>
 294
 295 When submitting a bug or request, please include a test-file or a
 296 patch to an existing test-file that illustrates the bug or desired
 297 feature.
 298
 299 =head1 AUTHOR
 300
 301 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 302
 303 =head1 COPYRIGHT AND LICENSE
 304
 305 This software is copyright (c) 2019 by Charles McGarvey.
 306
 307 This is free software; you can redistribute it and/or modify it under
 308 the same terms as the Perl 5 programming language system itself.
 309
 310 =cut