https://github.com/open-sauced/pizza-cli
A CLI for all things OpenSauced
https://github.com/open-sauced/pizza-cli
Last synced: 6 months ago
JSON representation
A CLI for all things OpenSauced
- Host: GitHub
- URL: https://github.com/open-sauced/pizza-cli
- Owner: open-sauced
- License: mit
- Created: 2023-06-26T20:10:37.000Z (over 2 years ago)
- Default Branch: beta
- Last Pushed: 2025-03-30T00:30:20.000Z (6 months ago)
- Last Synced: 2025-03-31T05:02:52.921Z (6 months ago)
- Language: Go
- Size: 447 KB
- Stars: 45
- Watchers: 6
- Forks: 11
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
🍕 Pizza CLI 🍕
A Go command line interface for managing code ownership and project insights with OpenSauced!
Watch the overview video 👇
# 📦 [Install](#-install)
#### Homebrew
```sh
brew install open-sauced/tap/pizza
```
#### NPM
```sh
npm i -g pizza
```
You can also use `npx` to run one-off commands without installing anything:
```sh
npx pizza@latest generate codeowners .
```
#### Go install
Using the Go tool-chain, you can install the binary directly:
```sh
$ go install github.com/open-sauced/pizza-cli@latest
```
> [!WARNING]
> Warning! You should have the `GOBIN` env var setup to point to a persistent
> location in your `PATH`. After Go 1.16, this defaults to `GOPATH[0]/bin`.
#### Manual install
Download a pre-built artifact from [the GitHub releases](https://github.com/open-sauced/pizza-cli/releases):
```sh
# Make the binary executable
$ chmod +x ~/Downloads/pizza-linux-arm64
# Move the binary into a location in the PATH
# Warning: the location where you drop the binary may differ!
$ mv ~/Downloads/pizza-linux-arm64 /usr/local/share/bin/pizza
```
#### Script install
```sh
curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh | sh
```
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.
Once download is completed, you can move the binary to a convenient location in
your system's `$PATH`.
> [!WARNING]
> It's _probably_ not advisable to pipe scripts from GitHub directly into
> a command line interpreter! If you do not fully trust the source, first
> download the script, inspect it manually to ensure integrity, and then
> run it:
> ```sh
> curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh > install.sh
> vim install.sh
> ./install.sh
> ```
# 🐳 Docker
Use the container image of the CLI for use in CI/CD or automation:
```sh
$ docker run ghcr.io/open-sauced/pizza-cli:latest
```
For commands that require access to your file system (like `generate codeowners`), ensure
you pass a volume to the docker container:
```sh
$ docker run -v /local/path:/container/path ghcr.io/open-sauced/pizza-cli:latest \
generate codeowners /container/path
```
For example, to mount your entire home directory (which may include a `~/.sauced.yaml` file
alongside the project you want to generate a `CODEOWNERS` file for):
```sh
$ docker run -v ~/:/app ghcr.io/open-sauced/pizza-cli:latest \
codeowners /app/workspace/gopherlogs -c /app/.sauced.yaml
```
# 🍕 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"
```
# 📝 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.
# 🚀 Quickstart
Get up and running with the Pizza CLI in minutes using `npx`:
1. **Ensure you have Node.js installed**
Pizza CLI can be run using `npx`, which comes with Node.js. If you don't have Node.js installed, download it from [nodejs.org](https://nodejs.org/).
> NOTE
> For other installation methods, see the [Install](#-Install) section.
2. **Generate a configuration file**
Navigate to your project directory and run:
```sh
npx pizza@latest generate config ./ -i
```
This will create a `.sauced.yaml` file, interactively prompting you to attribute commit emails to GitHub handles.
3. **Generate CODEOWNERS file**
In your project directory, run:
```sh
npx pizza@latest generate codeowners ./
```
This will create a `CODEOWNERS` file based on your project's git history and the `.sauced.yaml` configuration.
4. **Create OpenSauced [Contributor Insight](https://opensauced.pizza/docs/features/contributor-insights/)**
After generating the CODEOWNERS file, you can create an OpenSauced Contributor Insight:
```sh
npx pizza@latest generate insight .
```
5. **Explore repository insights**
Get metrics and insights for your repository:
```sh
npx pizza@latest insights repositories your-username/your-repo
```
6. **Set up automated CODEOWNERS updates (Optional)**
Add the [Pizza GitHub Action](https://github.com/open-sauced/pizza-action) to your repository to automate CODEOWNERS updates:
```yaml
# In .github/workflows/pizza-action.yml
name: OpenSauced Pizza Action
on:
schedule:
# Run once a week on Sunday at 00:00 UTC
- cron: "0 0 * * 0"
workflow_dispatch: # Allow manual triggering
jobs:
pizza-action:
runs-on: ubuntu-latest
steps:
- name: Pizza Action
uses: open-sauced/pizza-action@v2.2.0
with:
# optional and default is "latest". Add this parameter if you want to use a specific version, e.g. v2.0.0
cli-version: "v2.2.0"
# optional and false by default. Set this to true if you want to have a pull request for the changes created automatically.
commit-and-pr: "true"
# optional
pr-title: "chore: update repository codeowners"
```
Now you're ready to leverage the Pizza CLI for managing code ownership and getting project insights with OpenSauced!
> Note
> Using `npx pizza@latest` ensures you're always running the most recent version of Pizza CLI. If you prefer to use a specific version, you can replace `@latest` with a version number, e.g., `npx pizza@2.0.0`.
# ✨ 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.
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 v2.0.0: Generate Config
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 /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
- `-o, --output-path string`: Set the directory for the output file
- `-h, --help`: Display help for the command
#### Examples:
1. Generate a config file in the current directory:
```sh
pizza generate config ./
```
2. Generate a config file interactively:
```sh
pizza generate config ./ -i
```
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
```
## 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
```
# 🚜 Development
### Requirements
There are a few things you'll need to get started:
- The [1.22 `go` programming language](https://go.dev/doc/install) toolchain and dev environment (for example, the [VScode Go plugin](https://code.visualstudio.com/docs/languages/go) is very good).
- The [`just` command runner](https://github.com/casey/just) for easy operations
### Building
Clone this repository. Then, using the Go tool-chain, you can build a binary:
```
go build -o build/pizza main.go
```
> [!WARNING]
> There may be unsupported features, breaking changes, or experimental
> patches on the tip of the repository. Go and build with caution!
There are a number of `just` convinence commands for building with injected buildtime variables
and targeting other architectures and operating systems.
```
just build
```
```
just build-all
```
### Dev operations
There are a number of useful `just` commands that should be used during development:
- `just lint` will us Golangci-lint to lint the Go code
- `just clean` removes build artifacts from `build/`
- `just test` runs the unit and e2e tests
- `just format` uses goimports to format code
- ... and many more!
Check `just help` to get a full list of utility dev commands!