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.41
   8
   9 # SYNOPSIS
  10
  11     git-codeowners [--version|--help|--manual]
  12
  13     git-codeowners [show] [--format FORMAT] [--[no-]project] [PATH...]
  14
  15     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
  16
  17     git-codeowners patterns [--format FORMAT] [--owner OWNER]
  18
  19     git-codeowners create|update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
  20
  21     # enable bash shell completion
  22     eval "$(git-codeowners --shell-completion)"
  23
  24 # DESCRIPTION
  25
  26 `git-codeowners` is yet another CLI tool for managing `CODEOWNERS` files in git repos. In
  27 particular, it can be used to quickly find out who owns a particular file in a monorepo (or
  28 monolith).
  29
  30 **THIS IS EXPERIMENTAL!** The interface of this tool and its modules will probably change as I field
  31 test some things. Feedback welcome.
  32
  33 # INSTALL
  34
  35 There are several ways to install `git-codeowners` to your system.
  36
  37 ## from CPAN
  38
  39 You can install `git-codeowners` using [cpanm](https://metacpan.org/pod/cpanm):
  40
  41     cpanm App::Codeowners
  42
  43 ## from GitHub
  44
  45 You can also choose to download `git-codeowners` as a self-contained executable:
  46
  47     curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
  48     chmod +x git-codeowners
  49
  50 To hack on the code, clone the repo instead:
  51
  52     git clone https://github.com/chazmcgarvey/git-codeowners.git
  53     cd git-codeowners
  54     make bootstrap      # installs dependencies; requires cpanm
  55
  56 # OPTIONS
  57
  58 ## --version
  59
  60 Print the program name and version to `STDOUT`, and exit.
  61
  62 Alias: `-v`
  63
  64 ## --help
  65
  66 Print the synopsis to `STDOUT`, and exit.
  67
  68 Alias: `-h`
  69
  70 You can also use `--manual` to print the full documentation.
  71
  72 ## --color
  73
  74 Enable colorized output.
  75
  76 Color is ON by default on terminals; use `--no-color` to disable. Some environment variables may
  77 also alter the behavior of colorizing output:
  78
  79 - `NO_COLOR` - Set to disable color (same as `--no-color`).
  80 - `COLOR_DEPTH` - Set the number of supportable colors (e.g. 0, 16, 256, 16777216).
  81
  82 ## --format
  83
  84 Specify the output format to use. See ["FORMAT"](#format).
  85
  86 Alias: `-f`
  87
  88 ## --shell-completion
  89
  90     eval "$(lintany --shell-completion)"
  91
  92 Print shell code to enable completion to `STDOUT`, and exit.
  93
  94 Does not yet support Zsh...
  95
  96 # COMMANDS
  97
  98 ## show
  99
 100     git-codeowners [show] [--format FORMAT] [--[no-]project] [PATH...]
 101
 102 Show owners of one or more files in a repo.
 103
 104 ## owners
 105
 106     git-codeowners owners [--format FORMAT] [--pattern PATTERN]
 107
 108 ## patterns
 109
 110     git-codeowners patterns [--format FORMAT] [--owner OWNER]
 111
 112 ## create
 113
 114     git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 115
 116 Create a new `CODEOWNERS` file for a specified repo (or current directory).
 117
 118 ## update
 119
 120     git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 121
 122 Update the "unowned" list of an existing `CODEOWNERS` file for a specified
 123 repo (or current directory).
 124
 125 # FORMAT
 126
 127 The `--format` argument can be one of:
 128
 129 - `csv` - Comma-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
 130 - `json:pretty` - Pretty JSON (requires [JSON::MaybeXS](https://metacpan.org/pod/JSON%3A%3AMaybeXS))
 131 - `json` - JSON (requires [JSON::MaybeXS](https://metacpan.org/pod/JSON%3A%3AMaybeXS))
 132 - `table` - Table (requires [Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny))
 133 - `tsv` - Tab-separated values (requires [Text::CSV](https://metacpan.org/pod/Text%3A%3ACSV))
 134 - `yaml` - YAML (requires [YAML](https://metacpan.org/pod/YAML))
 135 - `FORMAT` - Custom format (see below)
 136
 137 ## Custom
 138
 139 You can specify a custom format using printf-like format sequences. These are the items that can be
 140 substituted:
 141
 142 - `%F` - Filename
 143 - `%O` - Owner or owners
 144 - `%P` - Project
 145 - `%T` - Pattern
 146 - `%n` - newline
 147 - `%t` - tab
 148 - `%%` - percent sign
 149
 150 The syntax also allows padding and some filters. Examples:
 151
 152     git-codeowners show -f ' * %-50F %O'                # default for "show"
 153     git-codeowners show -f '%{quote}F,%{quote}O'        # ad hoc CSV
 154     git-codeowners patterns -f '--> %{color:0c0}T'      # whatever...
 155
 156 Available filters:
 157
 158 - `quote` - Quote the replacement string.
 159 - `color:FFFFFF` - Colorize the replacement string (if color is ON).
 160 - `nocolor` - Do not colorize replacement string.
 161
 162 ## Table
 163
 164 Table formatting can be done by one of several different modules, each with its own features and
 165 bugs. The default module is [Text::Table::Tiny](https://metacpan.org/pod/Text%3A%3ATable%3A%3ATiny), but this can be overridden using the
 166 `PERL_TEXT_TABLE` environment variable if desired, like this:
 167
 168     PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
 169
 170 The list of available modules is at ["@BACKENDS" in Text::Table::Any](https://metacpan.org/pod/Text%3A%3ATable%3A%3AAny#BACKENDS).
 171
 172 # BUGS
 173
 174 Please report any bugs or feature requests on the bugtracker website
 175 [https://github.com/chazmcgarvey/git-codeowners/issues](https://github.com/chazmcgarvey/git-codeowners/issues)
 176
 177 When submitting a bug or request, please include a test-file or a
 178 patch to an existing test-file that illustrates the bug or desired
 179 feature.
 180
 181 # AUTHOR
 182
 183 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 184
 185 # COPYRIGHT AND LICENSE
 186
 187 This software is copyright (c) 2019 by Charles McGarvey.
 188
 189 This is free software; you can redistribute it and/or modify it under
 190 the same terms as the Perl 5 programming language system itself.