User:Mainframe98/Gerrit

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 patchset

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 master

For REL1_42, for example.

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

Amending a change

Existing

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

Other

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 chains

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.

Rebasing

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

Manually

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 conflicts

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 set

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 reverted

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 change

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.

Dropping a commit that duplicated because a rebase introduced it

These show up when a change was introduced earlier (e.g. white-space that was removed in an earlier commit).

• Ensure you are on the correct branch (you should, as you just finished rebasing and checked the results using git log.
• Start an interactive rebase using git rebase -i HEAD~N, where N is the N-nth commit from HEAD.
• In the editor, you can view the N commits. Here you can modify the relevant commits. For simple issues, replace the pick with drop and save. Git rebase will do the rest.

Other tasks

Reverting a local (unpushed) commit

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 branch

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 branch

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 commit

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

Rebasing on a branch that was already rebased against master

Typically git rebase <BRANCH NAME works, but sometimes there are way more rebase conflicts than makes sense and all that is necessary is to replay one (or more) commits directly on top another branch and git is being difficult about it.

This scenario assumes you have a branch off master with several commits, that has been rebased against master. Let's call this branch derived. You also have a branch that branches off that branch, which has not yet been rebased. Let's call this branch derived'.

1. Identify how many commits the derived' branch has, compared against derived.
2. Run git rebase --onto derived HEAD~1. Replace the 1 with the amount of commits on derived'.

UI

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