Development/GitReview

    From The Document Foundation Wiki

    We present here the git-review utility for command line interaction with https://gerrit.libreoffice.org.

    git-review is a program that is widely used for command line interaction with gerrit and was created by OpenStack project.

    Note that you can also use ./logerrit script as described in our gerrit wiki articles, although git-review eases interaction with your local repository and gerrit.

    Installation

    On most Linux distributions a git-review package should be available that can be installed with the usual package manager. For manual installation on other systems:

    Check your Installation

    Check if git-review is working

    $ git review --help
    
    usage: git review [upload] [OPTIONS] ... [BRANCH]
    
    [...]
    

    Check manual page

    man git-review

    or

    git review --help

    should display the manual page.

    Configuration

    If you still did not configure ssh host logerrit in ~/.ssh/config, please set it first up as described here.

    If you created logerrit remote manually, then you may want to remove it:

    git remote remove logerrit

    and let git-review recreate it:

    git review -s

    Attention !!! This command overwrites our own commit-msg hook and replaces it with the vanilla one from gerrit installation.

    Our commit hooks are maintained in .git-hooks/ in the core repo and ./g -z and other ./g calls make sure that the proper links are in place to use it. That is how we maintain our hooks and propagate changes to them.

    Run this command (after git review -s):

    ./g -z

    Test

    git review -l

    should produce something like this:

    git review in action

    Workflow

    Don't actually perform any commands that have direct effects. Print the results instead.

    Adding the --dry-run switch to unfamiliar but critical commands prevents you from having to solve puzzles you didn't want to ;-)

    git review --dry-run ...

    Submit first gerrit patch

    git add <the files you changed>
    git commit -m "a commit summary line"
    # or omit -m "..." which fires up your $VISUAL editor where you can enter a first line as commit summary,
    # optionally followed by one blank line and then more text for a detailed commit message to describe your commit.
    git review

    If the git review command tells you more than one commit would be sent to gerrit, it is probably unwanted. You might have forgotten about other changes you did on the same branch and already submitted to gerrit without then resetting your branch with git reset --hard HEAD^ to the previous state, removing the last change. Check carefully what you actually want to do in this case. See Work on a temporary brach for how to prevent that.

    Submit subsequent patch for the same change

    git add <the changed files>
    git commit --amend
    git review

    Supply a review topic

    git review -t foo-topic

    Submit a branch for review and then remove the local branch

    git review -f

    Beware, local branch is removed.

    Skip the automatic "git rebase -i" step

    git review -R

    Use this when submitting an amended subsequent patch for an already existing gerrit change.

    Download change 4711 from gerrit for review in a new local branch

    git review -d 4711

    Cherry pick a change to current branch

    git review -x 4711

    Work on a temporary branch

    To prevent several unrelated patches from piling up on your local master branch, get in the habit of working on a separate temporary branch, one per change to be submitted. Git-review also helps in that.

    A new branch for a new change

    # Create the branch in git:
    git checkout -b the_branch_name_you_like
    # Do your changes.
    git add <the changed files>
    git commit
    git review -f

    The -f option tells git-review to finish the branch, meaning to remove it after successfully submitting the commit to gerrit and then switch back to the master branch. (Where you can create a new branch for the next change ...)

    Amending a gerrit change

    Often it happens that a reviewer tells you to change something in your patch. To do so you'll have to download the current patch version of the change, amend it with the required changes and resubmit the result as a new patch set onto the same gerrit change without creating yet another new gerrit change. Basically this is done by amending the commit, leaving the Change-Id intact, and when submitting the change gerrit will recognize it as a new patch set for the change with the same Change-Id. Git-review also helps you in this.

    # Download change number 4711 from gerrit and create a new branch to work on:
    git review -d 4711
    # Do your changes.
    git add <the changed files>
    git commit --amend
    # Upload to gerrit:
    git review -R -f
    # where -R does not rebase, and -f finishes the created branch and puts you back where you were before.

    If git review -R -f presents you with a list of unrelated changes and asks you "Do you really want to submit the above commits?" then do not answer yes but instead just press enter and then run the command git review -f without the -R switch.

    The branch created by the git review -d 4711 command will have the committer ID (and optionally topic, if set, else the change number) in its name so it does not conflict with other local branches. If the branch already exists it will be updated with the latest patch set of this change. The branch is created from the starting point your current branch (e.g. master) is in. The -R switch in the final git review command omits the automatic rebase step, which comes handy in new patch sets for the same gerrit change because then in gerrit a reviewer can see the difference between two patch sets without all the other differences of other commits that happened in between, which would be the case without the -R switch. However, if you already did ./g pull -r (or git pull -r) to update your current branch (e.g. master) before downloading the change that may not be possible anymore. The -f switch again finishes the branch, by switching back to the starting point and removing the branch.

    Troubleshooting

    git-review ≤2.26 won't work with our gerrit version.

    $ git-review --version
    git-review version 1.25.0
    $ git review -f
    remote: error: branch refs/publish/master/NNNN:
    remote: You need 'Create' rights to create new references.
    remote: User: USERNAME
    remote: Contact an administrator to fix the permissions
    remote:
    remote: Processing changes: refs: 1
    remote: Processing changes: refs: 1, done
    To ssh://gerrit.libreoffice.org:29418/core
    ! [remote rejected]           HEAD -> refs/publish/master/NNNN (prohibited by Gerrit: not permitted: create)
    error: failed to push some refs to 'ssh://gerrit.libreoffice.org:29418/core'

    If you see that error, try to upgrade your git-review program or set the --compatible flag when calling the command.

    Further reading

    For actual development of git-review and adding new features to the tool, see Development/GitReview/Hacking.