Dogcows Code - chaz/git-codeowners/blob - README.md

   1 # NAME
   2
   3 git-codeowners - A tool for managing CODEOWNERS files
   4
   5 # VERSION
   6
   7 version 0.49
   8
   9 # SYNOPSIS
  10
  11     git-codeowners [--version|--help|--manual]
  12
  13     git-codeowners [show] [--format FORMAT] [--owner OWNER]...
  14                    [--pattern PATTERN]... [--[no-]patterns]
  15                    [--project PROJECT]... [--[no-]projects] [PATH...]
  16
  17     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
  18
  19     git-codeowners patterns [--format FORMAT] [--owner OWNER]
  20
  21     git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
  22
  23     # enable bash shell completion
  24     eval "$(git-codeowners --shell-completion)"
  25
  26 # DESCRIPTION
  27
  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
  30 monolith).
  31
  32 **THIS IS EXPERIMENTAL!** The interface of this tool and its modules will probably change as I field
  33 test some things. Feedback welcome.
  34
  35 # INSTALL
  36
  37 There are several ways to install `git-codeowners` to your system.
  38
  39 ## from CPAN
  40
  41 You can install `git-codeowners` using [cpanm](https://metacpan.org/pod/cpanm):
  42
  43     cpanm App::Codeowners
  44
  45 ## from GitHub
  46
  47 You can also choose to download `git-codeowners` as a self-contained executable:
  48
  49     curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
  50     chmod +x git-codeowners
  51
  52 To hack on the code, clone the repo instead:
  53
  54     git clone https://github.com/chazmcgarvey/git-codeowners.git
  55     cd git-codeowners
  56     make bootstrap      # installs dependencies; requires cpanm
  57
  58 # OPTIONS
  59
  60 ## --version
  61
  62 Print the program name and version to `STDOUT`, and exit.
  63
  64 Alias: `-v`
  65
  66 ## --help
  67
  68 Print the synopsis to `STDOUT`, and exit.
  69
  70 Alias: `-h`
  71
  72 You can also use `--manual` to print the full documentation.
  73
  74 ## --color
  75
  76 Enable colorized output.
  77
  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:
  80
  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).
  83
  84 ## --format
  85
  86 Specify the output format to use. See ["FORMAT"](#format).
  87
  88 Alias: `-f`
  89
  90 ## --shell-completion
  91
  92     eval "$(git-codeowners --shell-completion)"
  93
  94 Print shell code to enable completion to `STDOUT`, and exit.
  95
  96 Does not yet support Zsh...
  97
  98 # COMMANDS
  99
 100 ## show
 101
 102     git-codeowners [show] [--format FORMAT] [--owner OWNER]...
 103                    [--pattern PATTERN]... [--[no-]patterns]
 104                    [--project PROJECT]... [--[no-]projects] [PATH...]
 105
 106 Show owners of one or more files in a repo.
 107
 108 If `--owner`, `--project`, `--pattern` are set, only show files with matching
 109 criteria. These can be repeated.
 110
 111 Use `--patterns` to also show the matching pattern associated with each file.
 112
 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.
 116
 117 ## owners
 118
 119     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
 120
 121 List all owners defined in the `CODEOWNERS` file.
 122
 123 ## patterns
 124
 125     git-codeowners patterns [--format FORMAT] [--owner OWNER]
 126
 127 List all patterns defined in the `CODEOWNERS` file.
 128
 129 ## create
 130
 131     git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 132
 133 Create a new `CODEOWNERS` file for a specified repo (or current directory).
 134
 135 ## update
 136
 137     git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 138
 139 Update the "unowned" list of an existing `CODEOWNERS` file for a specified
 140 repo (or current directory).
 141
 142 # FORMAT
 143
 144 The `--format` argument can be one of:
 145
 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)
 153
 154 ## Format string
 155
 156 You can specify a custom format using printf-like format sequences. These are the items that can be
 157 substituted:
 158
 159 - `%F` - Filename
 160 - `%O` - Owner or owners
 161 - `%P` - Project
 162 - `%T` - Pattern
 163 - `%n` - newline
 164 - `%t` - tab
 165 - `%%` - percent sign
 166
 167 The syntax also allows padding and some filters. Examples:
 168
 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...
 172
 173 Available filters:
 174
 175 - `quote` - Quote the replacement string.
 176 - `color:FFFFFF` - Colorize the replacement string (if color is ON).
 177 - `nocolor` - Do not colorize replacement string.
 178
 179 ## Format table
 180
 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:
 184
 185     PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
 186
 187 The list of available modules is at ["@BACKENDS" in Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny#BACKENDS).
 188
 189 # CAVEATS
 190
 191 - Some commands require `git` (at least version 1.8.5).
 192
 193 # BUGS
 194
 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)
 197
 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
 200 feature.
 201
 202 # AUTHOR
 203
 204 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 205
 206 # COPYRIGHT AND LICENSE
 207
 208 This software is copyright (c) 2019 by Charles McGarvey.
 209
 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.