Amending reviews

So far we’ve discussed the simple case where a review is created and merged, but is not edited. The purpose of having your code reviewed is to solicit suggestions on how it can be improved, so it’s very common to go through one or more rounds of feedback and edits. Let’s continue the example above and assume that after receiving feedback from your reviewer, you wish to make some more changes to review 57.

Amending the top commit

The simplest way to do this is to modify the files locally, and then run git commit --amend to “amend” your last commit:

$ git commit -a --amend --no-edit
  [work 70fd803] Support direction parameter for linkedRevisions
  Date: Sat Apr 23 10:14:50 2022 -0400
  1 file changed, 1 insertion(+)

At this point review 57 will be in a “modified” status, and running plz review will push the new code, creating a new revision, rev 3.

Amending a buried commit

Now you wish to continue building on top of review 57 while we wait for any further feedback. You create a new commit and run plz review to push everything to the remote, creating review 59:

$ git commit -a -m 'Fix exposed 0 in baseline check'
  [work 1ba2c3e] Fix exposed 0 in baseline check
  1 file changed, 1 insertion(+)
$ plz review
  9bd1906a Fix exposed 0 in baseline check                 created https://plz.review/review/59
  70fd8033 Support direction parameter for linkedRevisions updated https://plz.review/review/57
$ plz status
  9bd1906a Fix exposed 0 in baseline check                    (rev 1, current) https://plz.review/review/59
  70fd8033 Support direction parameter for linkedRevisions    (rev 3, current) https://plz.review/review/57
  365d6250 Skip rebase when the old and new bases are the ... (merged)         https://plz.review/review/55

A while later you receive one last round of feedback on review 57. This means that you need to amend commit 70fd803. This is a little more complicated than the previous example because that commit is not at the top of the stack. To amend commit 70fd803 we need to “descend” into the stack, amend the commit, and then “ascend” back to the top of the stack, resolving any conflicts that arise along the way.

There are a number of ways to approach this problem, but for simple changes, the easiest approach is to use git rebase -i to rebase “interactively”. Rebasing is a rich technique with many variations described elsewhere, but in essence it involves transplanting commits from one base commit onto a different base commit, and optionally resolving conflicts, or otherwise editing the commits sequentially, one at a time.

In this case we wish to edit 70fd803, and transplant 9bd1906 on top of the result. Running git rebase -i main shows the following file in an interactive editor:

Editor context during rebase: git opens vim by default. If you’re not familiar with file editing in vim, check out this tutorial to cover the basics.

pick 70fd803 Support direction parameter for linkedRevisions
pick 9bd1906 Fix exposed 0 in baseline check

# Rebase 365d625..9bd1906 onto 365d625 (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
...

The first two lines contain the sequence of operations that will operate on the branch specified in the rebase command, in this case main. The final lines of this file contain explanatory comments. Saving the file and quitting will “pick” commits 70fd803 and 9bd1906 in that order as-is. In other words it will have no effect.

In our case, we wish to “edit” 70fd803 so replace “pick” on that line with “edit” (or “e” for short), then save and quit to kick off the rebase process. This will output the following:

Stopped at 70fd803...  Support direction parameter for linkedRevisions

You can amend the commit now, with

$ git commit --amend

Once you are satisfied with your changes, run

$ git rebase --continue

You’ve essentially reverted the state of your local repo to 70fd803 and you can now modify files, run code, etc. Once you’ve addressed the review comments you amend that commit and continue the rebase:

$ git commit -a --amend --no-edit
  [detached HEAD f8bd022] Support direction parameter for linkedRevisions
  Date: Sat Apr 23 10:14:50 2022 -0400
  1 file changed, 1 insertion(+)
$ git rebase --continue
  Successfully rebased and updated refs/heads/work.
$ plz status
  ef534a4a Fix xposed 0 in baseline check                    (modified) https://plz.review/review/59
  f8bd0228 Support direction parameter for linkedRevisions    (modified) https://plz.review/review/57
  365d6250 Skip rebase when the old and new bases are the ... (merged)   https://plz.review/review/55

Note that the top commit is now also “modified” because it is based on different code. You can now push new revisions to review 57 and 59 by running plz review and continue the review process.