User:Mainframe98/Gerrit

A Gerrit/Git how-to for those moments our brains fail us with the lovely error message.
 * 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:
 * 3) Pull the latest changes from the repository with git pull origin master
 * 4) 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
 * 5) Make your changes
 * 6) Prepare to commit:
 * 7) Check if the commit meets the Pre-commit checklist
 * 8) Write the commit message, for the guidelines see Gerrit/Commit message guidelines
 * 9) Commit with git commit . Don't use the -m flag because it restricts you to only the commit summary
 * 10) Prepare for pushing:
 * 11) 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
 * 12) 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
 * 13) (Optional, but recommended) Add some reviewers. See Developers/Maintainers
 * 14) 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

Existing

 * Your current branch is not the one from the patchset but does exist locally
 * 1) Run git checkout 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
 * 3) * Use --all only when you want all changes, regardless if they have been staged, to be amended.
 * 4) 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  in the commit message) and should be reviewed and merged separately. 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).
 * 1) Make your changes
 * 2) Commit the first set of changes
 * 3) * If you don't have a commit hook that automatically adds a  line to the commit message, push for review first.
 * 4) Repeat until you've made all your changes
 * 5) Send the changes off for review. You'll be shown a message; something like:

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. If any conflicts turn up after this, restart at 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.
 * 3) * Use git rm for removing files.
 * 4) Continue the rebasing with git rebase --continue

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  in front of the reverting commit with   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).

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
 * 2) * 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

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