User:Mainframe98/Gerrit

Gerrit icon.svg

A Gerrit/Git how-to for those moments our brains fail us with the lovely error message PC LOAD GIT REVIEW.

See also: Gerrit/Tutorial.

Creating a patchsetEdit

  1. Ensure the repository is set up with git review -s (remember: s for setup). Only required if there's not a .gitreview file in the repository
  2. Prepare the repository:
    1. Pull the latest changes from the repository with git pull origin master
    2. Create a branch for your changes with git checkout -b BRANCHNAME-GOES-HERE origin/master. Remember to name it appropriately, such as T2001/SHORT-DESCRIPTION
  3. Make your changes
  4. Prepare to commit:
    1. Check if the commit meets the Pre-commit checklist
    2. Write the commit message, for the guidelines see Gerrit/Commit message guidelines
    3. Commit with git commit. Don't use the -m flag because it restricts you to only the commit summary
  5. Prepare for pushing:
    1. Update your local repository with git pull --rebase origin master. It isn't strictly mandatory, but on repositories with a high update rate, it can prevent trouble
  6. Push your changes with git review -R. If you did not use the step above, omit -R as it tells git-review not to perform a rebase
    1. (Optional, but recommended) Add some reviewers. See Developers/Maintainers
  7. After the patch is merged or abandoned, switch back to master with git checkout master and remove the branch with git branch -d BRANCHNAME-GOES-HERE

For a branch other than masterEdit

For REL1_36, for example.

  1. Checkout the branch if you haven't already: git checkout -b REL1_36 origin/REL1_36
  2. Make your changes, like above, replacing master with the branch name
  3. Push the change with git review REL1_36

Amending a changeEdit

ExistingEdit

Your current branch is not the one from the patchset but does exist locally
  1. Run git checkout <branch name> and follow the steps below:
Your current branch is the one of the patchset.
  1. Make your changes (see above)
  2. Commit with git commit --amend
    • Use --all only when you want all changes, regardless if they have been staged, to be amended.
  3. Run git review -R to push the changes to Gerrit

OtherEdit

You don't have the patch yet.
  1. Get the patch with git review -d GERRIT-CHANGE-NUMBER-GOES-HERE. Beware that this does destroy your local changes, so stash or/and commit first.
  2. Follow the steps above.

Creating patch set chainsEdit

When you have changes that depend on each other (within the same repository, otherwise you'd tack a Depends-On: I... in the commit message) and should be reviewed and merged separately.

  1. Make your changes
  2. Commit the first set of changes
    • If you don't have a commit hook that automatically adds a Change-Id: I... line to the commit message, push for review first.
  3. Repeat until you've made all your changes
  4. Send the changes off for review. You'll be shown a message; something like:
You are about to submit multiple commits. This is expected if you are
submitting a commit that is dependent on one or more in-review
commits, or if you are submitting multiple self-contained but
dependent changes. Otherwise you should consider squashing your
changes into one commit before submitting (for indivisible changes) or
submitting from separate branches (for independent changes).

The outstanding commits are:

COMMIT 1 ...
COMMIT 2 ...
COMMIT 3 ...

Do you really want to submit the above commits?
Type 'yes' to confirm, other to cancel:
Input yes here, as you'll want each commit to be reviewed separately.

RebasingEdit

You can do this two ways: Either by using Gerrit's rebase option (only available to patch owners or those with +2) or manually.

ManuallyEdit

Using the rebase functionality of Gerrit does not always work. For those cases, follow the steps below:

  1. Pull the latest changes from the repository with git pull --rebase origin master
  2. Run git commit --amend. DON'T use the --all flag if you have uncommitted changes!
  3. Run git review -R to push the rebase to Gerrit

Resolving conflictsEdit

Sometimes patches have collected enough digi-dust that attempting to rebase them causes a merge conflict. In that case, using Gerrit's rebase option will not work. Instead, manually rebase, as mentioned above, but do the steps mentioned below after performing step 1.

  1. Open the file(s) with the conflict(s) in an editor and resolve these. The lines above the dashes are the current state of the repository, below the dashes are the content of the patch. Pick the correct lines (or combine them).
  2. Mark the conflict resolved using git add.
    • Use git rm for removing files.
  3. Continue the rebasing with git rebase --continue

If any conflicts turn up after this, restart at step 1.

Rebasing a patch setEdit

This works virtually identical to just rebasing a single commit, however, as you're working with multiple commits, you shouldn't run git commit --amend. Instead, resolve any conflicts, like mentioned above, then submit for review with git review -R.

Rebasing a change that depends on a (merged) commit that has been revertedEdit

Warning: Here be dragons rebase artifacts and merge conflicts!

  • Rebase the change with git pull --rebase origin master
  • Resolve merge conflicts, then continue rebasing with git rebase --continue
  • Create a revert of the reverting commit with git revert COMMIT_HASH_GOES_HERE
  • Resolve merge conflicts, then continue with git commit once finished
  • Merge both commits using git rebase -i, and replace pick in front of the reverting commit with fixup to discard the commit message of the merge commit.
Note that during rebasing you'll need to discard the HEAD contents (anything above the dashes), and during reverting, you'll need to pick the HEAD contents (anything above the dashes).

Rebasing a change on top of another changeEdit

See also: Gerrit/Advanced usage#Create a dependency.
  • Checkout both changes (using git review -d XXXXXX)
  • Checkout the branch with the change to rebase on top of the other change
  • Run git rebase BRANCH-TO-REBASE-ON-TOP-OF
  • Run git log to check the order is correct.
  • Run git review -R to upload the changes. When prompted about submitting multiple commits, input yes.

Other tasksEdit

Reverting a local (unpushed) commitEdit

For that moment when you've used git commit -a instead of git commit.

  1. Run git reset HEAD~1
    • If you have multiple commits you'd like to revert, replace 1 with the number of commits you need to revert.

Creating a new branchEdit

So far, I only know of one way to do this, using Gerrit's web interface:

  1. Find your project's Gerrit page and append ,branches: https://gerrit.wikimedia.org/r/#/admin/projects/PROJECTNAME/SUBPROJECTNAME,branches
  2. Create a new branch by specifying its name and the initial revision

Moving a commit from master to a separate branchEdit

Use case: You accidentally committed against origin/master, but wanted to commit to a branch.

  1. Run git fetch origin to ensure origin/master is up to date with Gerrit
  2. Run git rebase origin/master to move the commit to the tip of the master branch
  3. Create the branch with the requested name by running git branch BRANCH-NAME-GOES-HERE
  4. Run git status to check you are still on the master branch, if not, switch back with git checkout origin master
  5. Finally run git reset --hard origin/master to reset the master branch back to the original state before you committed

Setting the master branch to a specific commitEdit

Obviously, you lose any unstashed/uncommitted changes with the commands below.

  1. Switch to the master branch with git checkout master
  2. Run git reset --hard COMMIT-HASH-GOES-HERE

UIEdit

See https://review.gerrithub.io/Documentation/user-review-ui.html for an extensive guide that covers each part of the review interface.