git-codeowners - A tool for managing CODEOWNERS files
version 0.51
git-codeowners [--version|--help|--manual]
git-codeowners [show] [--format FORMAT] [--owner OWNER]...
[--pattern PATTERN]... [--[no-]patterns]
[--project PROJECT]... [--[no-]projects] [PATH...]
git-codeowners owners [--format FORMAT] [--pattern PATTERN]
git-codeowners patterns [--format FORMAT] [--owner OWNER]
git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
# enable bash shell completion
eval "$(git-codeowners --shell-completion)"
git-codeowners
is yet another CLI tool for managing CODEOWNERS
files in git repos. In
particular, it can be used to quickly find out who owns a particular file in a monorepo (or
monolith).
THIS IS EXPERIMENTAL! The interface of this tool and its modules will probably change as I field test some things. Feedback welcome.
There are several ways to install git-codeowners
to your system.
You can install git-codeowners
using cpanm:
cpanm App::Codeowners
You can also choose to download git-codeowners
as a self-contained executable:
curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
chmod +x git-codeowners
To hack on the code, clone the repo instead:
git clone https://github.com/chazmcgarvey/git-codeowners.git
cd git-codeowners
make bootstrap # installs dependencies; requires cpanm
Print the program name and version to STDOUT
, and exit.
Alias: -v
Print the synopsis to STDOUT
, and exit.
Alias: -h
You can also use --manual
to print the full documentation.
Enable colorized output.
Color is ON by default on terminals; use --no-color
to disable. Some environment variables may
also alter the behavior of colorizing output:
NO_COLOR
- Set to disable color (same as--no-color
).COLOR_DEPTH
- Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
Specify the output format to use. See "FORMAT".
Alias: -f
eval "$(git-codeowners --shell-completion)"
Print shell code to enable completion to STDOUT
, and exit.
Does not yet support Zsh...
git-codeowners [show] [--format FORMAT] [--owner OWNER]...
[--pattern PATTERN]... [--[no-]patterns]
[--project PROJECT]... [--[no-]projects] [PATH...]
[--[no-]expand-aliases]
Show owners of one or more files in a repo.
If --owner
, --project
, --pattern
are set, only show files with matching
criteria. These can be repeated.
Use --patterns
to also show the matching pattern associated with each file.
By default the output might show associated projects if the CODEOWNERS
file
defines them. You can control this by explicitly using --projects
or
--no-projects
to always show or always hide defined projects, respectively.
Use --expand-aliases
to show owners that are group aliases defined in the
CODEOWNERS
file as their aliased owners.
git-codeowners owners [--format FORMAT] [--pattern PATTERN]
List all owners defined in the CODEOWNERS
file.
git-codeowners patterns [--format FORMAT] [--owner OWNER]
List all patterns defined in the CODEOWNERS
file.
git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
Create a new CODEOWNERS
file for a specified repo (or current directory).
git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
Update the "unowned" list of an existing CODEOWNERS
file for a specified
repo (or current directory).
The --format
argument can be one of:
csv
- Comma-separated values (requires Text::CSV)json:pretty
- Pretty JSON (requires JSON::MaybeXS)json
- JSON (requires JSON::MaybeXS)table
- Table (requires Text::Table::Any)tsv
- Tab-separated values (requires Text::CSV)yaml
- YAML (requires YAML)FORMAT
- Custom format (see below)
You can specify a custom format using printf-like format sequences. These are the items that can be substituted:
%F
- Filename%O
- Owner or owners%P
- Project%T
- Pattern%n
- newline%t
- tab%%
- percent sign
The syntax also allows padding and some filters. Examples:
git-codeowners show -f ' * %-50F %O' # default for "show"
git-codeowners show -f '%{quote}F,%{quote}O' # ad hoc CSV
git-codeowners patterns -f '--> %{color:0c0}T' # whatever...
Available filters:
quote
- Quote the replacement string.color:FFFFFF
- Colorize the replacement string (if color is ON).nocolor
- Do not colorize replacement string.
Table formatting can be done by one of several different modules, each with its own features and
bugs. The default module is Text::Table::Tiny, but this can be overridden using the
PERL_TEXT_TABLE
environment variable if desired, like this:
PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
The list of available modules is at "@BACKENDS" in Text::Table::Any.
If you set GIT_CODEOWNERS_ALIASES
in the environment to a true value, the parser will parse group
aliases which are supported by some applications.
- Some commands require
git
(at least version 1.8.5).
Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/git-codeowners/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Charles McGarvey chazmcgarvey@brokenzipper.com
This software is copyright (c) 2021 by Charles McGarvey.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.