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