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