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 git repos. In
29 particular, it can be used to quickly find out who owns a particular file in a monorepo (or
32 **THIS IS EXPERIMENTAL!** The interface of this tool and its modules will probably change as I field
33 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](https://metacpan.org/pod/cpanm):
47 You can also choose to download `git-codeowners` as a self-contained executable:
49 curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
50 chmod +x git-codeowners
52 To hack on the code, clone the repo instead:
54 git clone https://github.com/chazmcgarvey/git-codeowners.git
56 make bootstrap # installs dependencies; requires cpanm
62 Print the program name and version to `STDOUT`, and exit.
68 Print the synopsis to `STDOUT`, and exit.
72 You can also use `--manual` to print the full documentation.
76 Enable colorized output.
78 Color is ON by default on terminals; use `--no-color` to disable. Some environment variables may
79 also alter the behavior of colorizing output:
81 - `NO_COLOR` - Set to disable color (same as `--no-color`).
82 - `COLOR_DEPTH` - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
86 Specify the output format to use. See ["FORMAT"](#format).
92 eval "$(git-codeowners --shell-completion)"
94 Print shell code to enable completion to `STDOUT`, and exit.
96 Does not yet support Zsh...
102 git-codeowners [show] [--format FORMAT] [--owner OWNER]...
103 [--pattern PATTERN]... [--[no-]patterns]
104 [--project PROJECT]... [--[no-]projects] [PATH...]
106 Show owners of one or more files in a repo.
108 If `--owner`, `--project`, `--pattern` are set, only show files with matching
109 criteria. These can be repeated.
111 Use `--patterns` to also show the matching pattern associated with each file.
113 By default the output might show associated projects if the `CODEOWNERS` file
114 defines them. You can control this by explicitly using `--projects` or
115 `--no-projects` to always show or always hide defined projects, respectively.
119 git-codeowners owners [--format FORMAT] [--pattern PATTERN]
121 List all owners defined in the `CODEOWNERS` file.
125 git-codeowners patterns [--format FORMAT] [--owner OWNER]
127 List all patterns defined in the `CODEOWNERS` file.
131 git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
133 Create a new `CODEOWNERS` file for a specified repo (or current directory).
137 git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
139 Update the "unowned" list of an existing `CODEOWNERS` file for a specified
140 repo (or current directory).
144 The `--format` argument can be one of:
146 - `csv` - Comma-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
147 - `json:pretty` - Pretty JSON (requires [JSON::MaybeXS](https://metacpan.org/pod/JSON%3A%3AMaybeXS))
148 - `json` - JSON (requires [JSON::MaybeXS](https://metacpan.org/pod/JSON%3A%3AMaybeXS))
149 - `table` - Table (requires [Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny))
150 - `tsv` - Tab-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
151 - `yaml` - YAML (requires [YAML](https://metacpan.org/pod/YAML))
152 - `FORMAT` - Custom format (see below)
156 You can specify a custom format using printf-like format sequences. These are the items that can be
160 - `%O` - Owner or owners
165 - `%%` - percent sign
167 The syntax also allows padding and some filters. Examples:
169 git-codeowners show -f ' * %-50F %O' # default for "show"
170 git-codeowners show -f '%{quote}F,%{quote}O' # ad hoc CSV
171 git-codeowners patterns -f '--> %{color:0c0}T' # whatever...
175 - `quote` - Quote the replacement string.
176 - `color:FFFFFF` - Colorize the replacement string (if color is ON).
177 - `nocolor` - Do not colorize replacement string.
181 Table formatting can be done by one of several different modules, each with its own features and
182 bugs. The default module is [Text::Table::Tiny](https://metacpan.org/pod/Text%3A%3ATable%3A%3ATiny), but this can be overridden using the
183 `PERL_TEXT_TABLE` environment variable if desired, like this:
185 PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
187 The list of available modules is at ["@BACKENDS" in Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny#BACKENDS).
191 - Some commands require `git` (at least version 1.8.5).
195 Please report any bugs or feature requests on the bugtracker website
196 [https://github.com/chazmcgarvey/git-codeowners/issues](https://github.com/chazmcgarvey/git-codeowners/issues)
198 When submitting a bug or request, please include a test-file or a
199 patch to an existing test-file that illustrates the bug or desired
204 Charles McGarvey <chazmcgarvey@brokenzipper.com>
206 # COPYRIGHT AND LICENSE
208 This software is copyright (c) 2019 by Charles McGarvey.
210 This is free software; you can redistribute it and/or modify it under
211 the same terms as the Perl 5 programming language system itself.