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