3 git-codeowners - A tool for managing CODEOWNERS files
11 git-codeowners [--version|--help|--manual]
13 git-codeowners [show] [--format FORMAT] [--owner OWNER]...
14 [--pattern PATTERN]... [--[no-]patterns]
15 [--project PROJECT]... [--[no-]projects] [PATH...]
17 git-codeowners owners [--format FORMAT] [--pattern PATTERN]
19 git-codeowners patterns [--format FORMAT] [--owner OWNER]
21 git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
23 # enable bash shell completion
24 eval "$(git-codeowners --shell-completion)"
28 git-codeowners is yet another CLI tool for managing CODEOWNERS files in
29 git repos. In particular, it can be used to quickly find out who owns a
30 particular file in a monorepo (or monolith).
32 THIS IS EXPERIMENTAL! The interface of this tool and its modules will
33 probably change as I field test some things. Feedback welcome.
37 There are several ways to install git-codeowners to your system.
41 You can install git-codeowners using cpanm:
47 You can also choose to download git-codeowners as a self-contained
50 curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
51 chmod +x git-codeowners
53 To hack on the code, clone the repo instead:
55 git clone https://github.com/chazmcgarvey/git-codeowners.git
57 make bootstrap # installs dependencies; requires cpanm
63 Print the program name and version to STDOUT, and exit.
69 Print the synopsis to STDOUT, and exit.
73 You can also use --manual to print the full documentation.
77 Enable colorized output.
79 Color is ON by default on terminals; use --no-color to disable. Some
80 environment variables may also alter the behavior of colorizing output:
82 * NO_COLOR - Set to disable color (same as --no-color).
84 * COLOR_DEPTH - Set the number of supportable colors (e.g. 0, 16,
89 Specify the output format to use. See "FORMAT".
95 eval "$(git-codeowners --shell-completion)"
97 Print shell code to enable completion to STDOUT, and exit.
99 Does not yet support Zsh...
105 git-codeowners [show] [--format FORMAT] [--owner OWNER]...
106 [--pattern PATTERN]... [--[no-]patterns]
107 [--project PROJECT]... [--[no-]projects] [PATH...]
109 Show owners of one or more files in a repo.
111 If --owner, --project, --pattern are set, only show files with matching
112 criteria. These can be repeated.
114 Use --patterns to also show the matching pattern associated with each
117 By default the output might show associated projects if the CODEOWNERS
118 file defines them. You can control this by explicitly using --projects
119 or --no-projects to always show or always hide defined projects,
124 git-codeowners owners [--format FORMAT] [--pattern PATTERN]
126 List all owners defined in the CODEOWNERS file.
130 git-codeowners patterns [--format FORMAT] [--owner OWNER]
132 List all patterns defined in the CODEOWNERS file.
136 git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
138 Create a new CODEOWNERS file for a specified repo (or current
143 git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
145 Update the "unowned" list of an existing CODEOWNERS file for a
146 specified repo (or current directory).
150 The --format argument can be one of:
152 * csv - Comma-separated values (requires Text::CSV)
154 * json:pretty - Pretty JSON (requires JSON::MaybeXS)
156 * json - JSON (requires JSON::MaybeXS)
158 * table - Table (requires Text::Table::Any)
160 * tsv - Tab-separated values (requires Text::CSV)
162 * yaml - YAML (requires YAML)
164 * FORMAT - Custom format (see below)
168 You can specify a custom format using printf-like format sequences.
169 These are the items that can be substituted:
173 * %O - Owner or owners
185 The syntax also allows padding and some filters. Examples:
187 git-codeowners show -f ' * %-50F %O' # default for "show"
188 git-codeowners show -f '%{quote}F,%{quote}O' # ad hoc CSV
189 git-codeowners patterns -f '--> %{color:0c0}T' # whatever...
193 * quote - Quote the replacement string.
195 * color:FFFFFF - Colorize the replacement string (if color is ON).
197 * nocolor - Do not colorize replacement string.
201 Table formatting can be done by one of several different modules, each
202 with its own features and bugs. The default module is
203 Text::Table::Tiny, but this can be overridden using the PERL_TEXT_TABLE
204 environment variable if desired, like this:
206 PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
208 The list of available modules is at "@BACKENDS" in Text::Table::Any.
212 * Some commands require git (at least version 1.8.5).
216 Please report any bugs or feature requests on the bugtracker website
217 https://github.com/chazmcgarvey/git-codeowners/issues
219 When submitting a bug or request, please include a test-file or a patch
220 to an existing test-file that illustrates the bug or desired feature.
224 Charles McGarvey <chazmcgarvey@brokenzipper.com>
226 COPYRIGHT AND LICENSE
228 This software is copyright (c) 2019 by Charles McGarvey.
230 This is free software; you can redistribute it and/or modify it under
231 the same terms as the Perl 5 programming language system itself.