🎮CLI User Guide

The plz CLI is a tool for managing stacks of reviews. Basic usage for this tool is described in How to plz. This document digs into plz operations in more detail, including how they interact with the underlying Git repo. Understanding these concepts will help you get the most out of plz.

Git basics

Let’s start with a simple situation: you’ve cloned a repo and you have the main branch checked out locally. You can look at the history of the main branch using git log:

$ git log --oneline
  23170d4 (HEAD -> main, origin/main, origin/HEAD) Remove base branch check in outdated resolver (#532)
  53715f1 Prohibit syncing closed/merged reviews (#530)
...

Pictured below we have an up-to-date main branch, with the most recent commit being 23170d4:

Suppose now that you’ve made some local changes, but you haven’t committed those changes:

$ git status --short
  M README.md
  M hello.js

Ultimately we wish to create a PR from these changes so that we can merge them into the main branch. The first step is to create a local working branch and commit the change as follows:

$ git switch -c work
  Switched to a new branch 'work'
$ git commit -a -m 'Skip rebase when the old and new bases are the same'
  [work 0a2ea7b] Skip rebase when the old and new bases are the same
  2 files changed, 2 insertions(+)

The diagram above shows the outcome of these operations:

• A new commit 0a2ea7b has been created

• The work branch has been pointed at this new commit

These changes have only affected our local repository, the remote has not changed. The red parts of the diagram represent the local state that diverges from the remote, and the black parts represent state that’s identical locally and on the remote. See the Diagram legend for more details.

pageCreating reviews

pageStacking reviews

pageMerging reviews

pageAmending reviews

Diagram legend

The workflows described in this document make heavy use of diagrams to depict the state of the local and remote git repositories.