2 # ABSTRACT: A tool for managing CODEOWNERS files
3 # PODNAME: git-codeowners
6 # FATPACK - Do not remove this line.
13 our $VERSION = '0.43'; # VERSION
15 App::Codeowners->main(@ARGV);
25 git-codeowners - A tool for managing CODEOWNERS files
33 git-codeowners [--version|--help|--manual]
35 git-codeowners [show] [--format FORMAT] [--owner OWNER]...
36 [--pattern PATTERN]... [--[no-]patterns]
37 [--project PROJECT]... [--[no-]projects] [PATH...]
39 git-codeowners owners [--format FORMAT] [--pattern PATTERN]
41 git-codeowners patterns [--format FORMAT] [--owner OWNER]
43 git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
45 # enable bash shell completion
46 eval "$(git-codeowners --shell-completion)"
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
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.
59 There are several ways to install F<git-codeowners> to your system.
63 You can install F<git-codeowners> using L<cpanm>:
69 You can also choose to download F<git-codeowners> as a self-contained executable:
71 curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
72 chmod +x git-codeowners
74 To hack on the code, clone the repo instead:
76 git clone https://github.com/chazmcgarvey/git-codeowners.git
78 make bootstrap # installs dependencies; requires cpanm
84 Print the program name and version to C<STDOUT>, and exit.
90 Print the synopsis to C<STDOUT>, and exit.
94 You can also use C<--manual> to print the full documentation.
98 Enable colorized output.
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:
107 C<NO_COLOR> - Set to disable color (same as C<--no-color>).
111 C<COLOR_DEPTH> - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
117 Specify the output format to use. See L</FORMAT>.
121 =head2 --shell-completion
123 eval "$(lintany --shell-completion)"
125 Print shell code to enable completion to C<STDOUT>, and exit.
127 Does not yet support Zsh...
133 git-codeowners [show] [--format FORMAT] [--owner OWNER]...
134 [--pattern PATTERN]... [--[no-]patterns]
135 [--project PROJECT]... [--[no-]projects] [PATH...]
137 Show owners of one or more files in a repo.
139 If C<--owner>, C<--project>, C<--pattern> are set, only show files with matching
140 criteria. These can be repeated.
142 Use C<--patterns> to also show the matching pattern associated with each file.
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.
150 git-codeowners owners [--format FORMAT] [--pattern PATTERN]
152 List all owners defined in the F<CODEOWNERS> file.
156 git-codeowners patterns [--format FORMAT] [--owner OWNER]
158 List all patterns defined in the F<CODEOWNERS> file.
162 git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
164 Create a new F<CODEOWNERS> file for a specified repo (or current directory).
168 git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
170 Update the "unowned" list of an existing F<CODEOWNERS> file for a specified
171 repo (or current directory).
175 The C<--format> argument can be one of:
181 C<csv> - Comma-separated values (requires L<Text::CSV>)
185 C<json:pretty> - Pretty JSON (requires L<JSON::MaybeXS>)
189 C<json> - JSON (requires L<JSON::MaybeXS>)
193 C<table> - Table (requires L<Text::Table::Any>)
197 C<tsv> - Tab-separated values (requires L<Text::CSV>)
201 C<yaml> - YAML (requires L<YAML>)
205 C<FORMAT> - Custom format (see below)
211 You can specify a custom format using printf-like format sequences. These are the items that can be
222 C<%O> - Owner or owners
246 The syntax also allows padding and some filters. Examples:
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...
258 C<quote> - Quote the replacement string.
262 C<color:FFFFFF> - Colorize the replacement string (if color is ON).
266 C<nocolor> - Do not colorize replacement string.
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:
276 PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
278 The list of available modules is at L<Text::Table::Any/@BACKENDS>.
286 Some commands require F<git> (at least version 1.8.5).
292 Please report any bugs or feature requests on the bugtracker website
293 L<https://github.com/chazmcgarvey/git-codeowners/issues>
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
301 Charles McGarvey <chazmcgarvey@brokenzipper.com>
303 =head1 COPYRIGHT AND LICENSE
305 This software is copyright (c) 2019 by Charles McGarvey.
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.