---
-### 📦 Install
-
-There are several methods for downloading and installing the `pizza` CLI:
+# 📦 Install
#### Homebrew
@@ -62,27 +38,72 @@ brew install open-sauced/tap/pizza
npm i -g pizza
```
-#### Direct script install
+You can also use `npx` to run one-off commands without installing anything:
```sh
-curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh | sh
+npx pizza@latest generate codeowners .
+```
+
+# 🍕 Pizza Action
+
+Use [the Pizza GitHub Action](https://github.com/open-sauced/pizza-action) for running `pizza` operations in GitHub CI/CD,
+like automated `CODEOWNERS` updating and pruning:
+
+```yaml
+jobs:
+ pizza-action:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Pizza Action
+ uses: open-sauced/pizza-action@v2
+ with:
+ # Optional: Whether to commit and create a PR for "CODEOWNER" changes
+ commit-and-pr: "true"
+ # Optional: Title of the PR for review by team
+ pr-title: "chore: update repository codeowners"
```
-This is a convenience script that can be downloaded from GitHub directly and
-piped into `sh` for conveniently downloading the latest GitHub release of the
-`pizza` CLI.
+# 📝 Docs
+
+- [Pizza.md](./docs/pizza.md): In depth docs on each command, option, and flag.
+- [OpenSauced.pizza/docs](https://opensauced.pizza/docs/tools/pizza-cli/): Learn
+ how to use the Pizza command line tool and how it works with the rest of the OpenSauced
+ ecosystem.
+
+# ✨ Usage
+
+## Codeowners generation
+
+Use the `codeowners` command to generate a GitHub style `CODEOWNERS` file or a more agnostic `OWNERS` file.
+This can be used to granularly define what experts and entities have the
+most context and knowledge on certain parts of a codebase.
-Once download is completed, you can move the binary to a convenient location in
-your system's `$PATH`.
+It's expected that there's a `.sauced.yaml` config file in the given path or in
+your home directory (as `~/.sauced.yaml`):
+
+```sh
+pizza generate codeowners /path/to/local/git/repo
+```
+
+Running this command will iterate the git ref-log to determine who to set as a code
+owner based on the number of lines changed for that file within the given time range.
+The first owner is the entity with the most lines changed. This command uses a `.sauced.yaml` configuration
+to attribute emails in commits with the given entities in the config (like GitHub usernames or teams).
+See [the section on the configuration schema for more details](#-configuration-schema)
### 🚀 New in v1.4.0: Generate Config
-The `pizza generate config` command has been added to help you create configuration files for your projects. This command allows you to generate configuration files with various options:
+The `pizza generate config` command has been added to help you create `.sauced.yaml` configuration files for your projects.
+This command allows you to generate configuration files with various options:
```sh
-pizza generate config [flags]
+pizza generate config /path/to/local/git/repo
```
+This command will iterate the git ref-log and inspect email signatures for commits
+and, in interactive mode, ask you to attribute those users with GitHub handles. Once finished, the resulting
+`.sauced.yaml` file can be used to attribute owners in a `CODEOWNERS` file during `pizza generate codeowners`.
+
#### Flags:
- `-i, --interactive`: Enter interactive mode to attribute each email manually
@@ -93,15 +114,74 @@ pizza generate config [flags]
1. Generate a config file in the current directory:
```sh
- pizza generate config
+ pizza generate config ./
```
2. Generate a config file interactively:
```sh
- pizza generate config -i
+ pizza generate config ./ -i
```
-3. Generate a config file in a specific directory:
+3. Generate a config file from the current directory and place resulting `.sauced.yaml` in a specific output directory:
```sh
- pizza generate config -o /path/to/directory
+ pizza generate config ./ -o /path/to/directory
```
+
+## OpenSauced Contributor Insight from `CODEOWNERS`
+
+You can create an [OpenSauced Contributor Insight](https://opensauced.pizza/docs/features/contributor-insights/)
+from a local `CODEOWNERS` file:
+
+```
+pizza generate insight /path/to/repo/with/CODEOWNERS/file
+```
+
+This will parse the `CODEOWNERS` file and create a Contributor Insight on the OpenSauced platform.
+This allows you to track insights and metrics for those codeowners, powered by OpenSauced.
+
+## Insights
+
+You can get metrics and insights on repositories, contributors, and more:
+
+```
+pizza insights [sub-command]
+```
+
+This powerful command lets you compose many metrics and insights together, all
+powered by OpenSauced's API. Use the `--output` flag to output the results as yaml, json, csv, etc.
+
+# 🎷 Configuration schema
+
+```yaml
+# Configuration for attributing commits with emails to individual entities.
+# Used during "pizza generate codeowners".
+attribution:
+
+ # Keys can be GitHub usernames.
+ jpmcb:
+
+ # List of emails associated with the given GitHub login.
+ # The commits associated with these emails will be attributed to
+ # this GitHub login in this yaml map. Any number of emails may be listed.
+ - john@opensauced.pizza
+ - hello@johncodes.com
+
+ # Keys may also be GitHub teams. This is useful for orchestrating multiple
+ # people to a sole GitHub team.
+ open-sauced/engineering:
+ - john@opensauced.pizza
+ - other-user@email.com
+ - other-user@no-reply.github.com
+
+ # Keys can also be agnostic names which will land as keys in "OWNERS" files
+ # when the "--owners-style-file" flag is set.
+ John McBride
+ - john@opensauced.pizza
+
+# Used during codeowners generation: if there are no code owners found
+# for a file within the time range, the list of fallback entities
+# will be used
+attribution-fallback:
+ - open-sauced/engineering
+ - some-other-github-login
+```
-
- 
-
-
- 
+
+ 
-
-
-```
-❯ pizza
-
-A command line utility for insights, metrics, and all things OpenSauced
-
-Usage:
- pizza 
+
+