The git-cl README describes the git-cl command set. This document describes how code review and git work together in general, intended for people familiar with git but unfamiliar with the code review process supported by Rietveld and Gerrit.
A Rietveld review is for discussion of a single change or patch. You upload a proposed change, the reviewer comments on your change, and then you can upload a revised version of your change. Rietveld stores the history of uploaded patches as well as the comments, and can compute diffs in between these patches. The history of a patch is very much like a small branch in git, but since Rietveld is VCS-agnostic, the concepts don't map perfectly. The identifier for a single review thread including patches and comments in Rietveld is called an issue.
Rietveld provides a basic uploader that understands git. This program is used by git-cl, and is included in the git-cl repo as upload.py.
The fundamental problem you encounter when you try to mix git and code review is that with git it‘s nice to commit code locally, while during a code review you’re often requested to change something about your code. There are a few different ways you can handle this workflow with git:
git commit --amend, effectively erasing A and making a new commit A', so history is now O--A'. (Equivalently, you can use
git reset --softor
git rebase -i.)
The Rietveld patch uploader just takes arguments to
git diff, so either of the above workflows work fine. If all you want to do is upload a patch, you can use the upload.py provided by Rietveld with arguments like this:
upload.py --server server.com <args to "git diff">
The first time you upload, it creates a new issue; for follow-ups on the same issue, you need to provide the issue number:
upload.py --server server.com --issue 1234 <args to "git diff">
git-cl simplifies the above in the following ways:
git cl configputs a persistent --server setting in your .git/config.
git checkout --tracksense) another one (like origin/master), calls to
git cl uploadwill diff against that branch by default. (You can still pass arguments to
git diffon the command line, if necessary.)
In the common case, this means that calling simply
git cl upload will always upload the correct diff to the correct place.
The above is all you need to know for working on a single patch.
Things get much more complicated when you have a series of commits that you want to get reviewed. Say your history looks like O--A--B--C. If you want to upload that as a single review, everything works just as above.
But what if you upload each of A, B, and C as separate reviews? What if you then need to change A?
One option is rewriting history: write a new commit A', then use
git rebase -i to insert that diff in as O--A--A'--B--C as well as squash it. This is sometimes not possible if B and C have touched some lines affected by A'.
Another option, and the one espoused by software like topgit, is for you to have separate branches for A, B, and C, and after writing A' you merge it into each of those branches. (topgit automates this merging process.) This is also what is recommended by git-cl, which likes having different branch identifiers to hang the issue number off of. Your history ends up looking like:
O---A---B---C \ \ \ A'--B'--C'
Which is ugly, but it accurately tracks the real history of your work, can be thrown away at the end by committing A+A' as a single
In practice, this comes up pretty rarely. Suggestions for better workflows are welcome.
Ensure that your base git commands are autocompleted doc.
Add this to your .bashrc:
# The next line enables bash completion for git cl. if [ -f "$HOME/bin/depot_tools/git_cl_completion.sh" ]; then . "$HOME/bin/depot_tools/git_cl_completion.sh" fi