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

   1 NAME
   2
   3     git-codeowners - A tool for managing CODEOWNERS files
   4
   5 VERSION
   6
   7     version 0.42
   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
  29     git repos. In particular, it can be used to quickly find out who owns a
  30     particular file in a monorepo (or monolith).
  31
  32     THIS IS EXPERIMENTAL! The interface of this tool and its modules will
  33     probably change as I field 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:
  42
  43         cpanm App::Codeowners
  44
  45  from GitHub
  46
  47     You can also choose to download git-codeowners as a self-contained
  48     executable:
  49
  50         curl -OL https://raw.githubusercontent.com/chazmcgarvey/git-codeowners/solo/git-codeowners
  51         chmod +x git-codeowners
  52
  53     To hack on the code, clone the repo instead:
  54
  55         git clone https://github.com/chazmcgarvey/git-codeowners.git
  56         cd git-codeowners
  57         make bootstrap      # installs dependencies; requires cpanm
  58
  59 OPTIONS
  60
  61  --version
  62
  63     Print the program name and version to STDOUT, and exit.
  64
  65     Alias: -v
  66
  67  --help
  68
  69     Print the synopsis to STDOUT, and exit.
  70
  71     Alias: -h
  72
  73     You can also use --manual to print the full documentation.
  74
  75  --color
  76
  77     Enable colorized output.
  78
  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:
  81
  82       * NO_COLOR - Set to disable color (same as --no-color).
  83
  84       * COLOR_DEPTH - Set the number of supportable colors (e.g. 0, 16,
  85       256, 16777216).
  86
  87  --format
  88
  89     Specify the output format to use. See "FORMAT".
  90
  91     Alias: -f
  92
  93  --shell-completion
  94
  95         eval "$(lintany --shell-completion)"
  96
  97     Print shell code to enable completion to STDOUT, and exit.
  98
  99     Does not yet support Zsh...
 100
 101 COMMANDS
 102
 103  show
 104
 105         git-codeowners [show] [--format FORMAT] [--owner OWNER]...
 106                        [--pattern PATTERN]... [--[no-]patterns]
 107                        [--project PROJECT]... [--[no-]projects] [PATH...]
 108
 109     Show owners of one or more files in a repo.
 110
 111     If --owner, --project, --pattern are set, only show files with matching
 112     criteria. These can be repeated.
 113
 114     Use --patterns to also show the matching pattern associated with each
 115     file.
 116
 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,
 120     respectively.
 121
 122  owners
 123
 124         git-codeowners owners [--format FORMAT] [--pattern PATTERN]
 125
 126     List all owners defined in the CODEOWNERS file.
 127
 128  patterns
 129
 130         git-codeowners patterns [--format FORMAT] [--owner OWNER]
 131
 132     List all patterns defined in the CODEOWNERS file.
 133
 134  create
 135
 136         git-codeowners create [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 137
 138     Create a new CODEOWNERS file for a specified repo (or current
 139     directory).
 140
 141  update
 142
 143         git-codeowners update [REPO_DIRPATH|CODEOWNERS_FILEPATH]
 144
 145     Update the "unowned" list of an existing CODEOWNERS file for a
 146     specified repo (or current directory).
 147
 148 FORMAT
 149
 150     The --format argument can be one of:
 151
 152       * csv - Comma-separated values (requires Text::CSV)
 153
 154       * json:pretty - Pretty JSON (requires JSON::MaybeXS)
 155
 156       * json - JSON (requires JSON::MaybeXS)
 157
 158       * table - Table (requires Text::Table::Any)
 159
 160       * tsv - Tab-separated values (requires Text::CSV)
 161
 162       * yaml - YAML (requires YAML)
 163
 164       * FORMAT - Custom format (see below)
 165
 166  Format string
 167
 168     You can specify a custom format using printf-like format sequences.
 169     These are the items that can be substituted:
 170
 171       * %F - Filename
 172
 173       * %O - Owner or owners
 174
 175       * %P - Project
 176
 177       * %T - Pattern
 178
 179       * %n - newline
 180
 181       * %t - tab
 182
 183       * %% - percent sign
 184
 185     The syntax also allows padding and some filters. Examples:
 186
 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...
 190
 191     Available filters:
 192
 193       * quote - Quote the replacement string.
 194
 195       * color:FFFFFF - Colorize the replacement string (if color is ON).
 196
 197       * nocolor - Do not colorize replacement string.
 198
 199  Format table
 200
 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:
 205
 206         PERL_TEXT_TABLE=Text::Table::HTML git-codeowners -f table
 207
 208     The list of available modules is at "@BACKENDS" in Text::Table::Any.
 209
 210 CAVEATS
 211
 212       * Some commands require git (at least version 1.8.5).
 213
 214 BUGS
 215
 216     Please report any bugs or feature requests on the bugtracker website
 217     https://github.com/chazmcgarvey/git-codeowners/issues
 218
 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.
 221
 222 AUTHOR
 223
 224     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 225
 226 COPYRIGHT AND LICENSE
 227
 228     This software is copyright (c) 2019 by Charles McGarvey.
 229
 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.
 232