The Gerrit Playbook
A Guide for Git-savvy Developers
When it comes to version control systems, Git is a mainstay in the software development world. However, for team-based projects, developers often need more structured workflows and a higher level of oversight on changes to the codebase. Enter Gerrit: a free, web-based team code collaboration tool that complements Git’s functionality and promotes high-quality code through code reviews.
If you’re already familiar with Git and Git Flow, this playbook will help you to understand Gerrit and how to use it effectively in your workflow.
Setting Up Gerrit
First things first: You’ll need to install Gerrit. For detailed instructions on how to do this, refer to the Gerrit installation guide.
Once Gerrit is installed, you can clone a repository as you usually would in Git. Note that you’ll need to use the SSH protocol to clone your repository if you plan on pushing changes for review.
Making Changes
1. Creating a New Branch
When you’re ready to start working on a new feature or fix, it’s best to create a new branch. This is consistent with the feature-based workflow in Git Flow:
git checkout -b my_new_featureThis command will create a new branch called my_new_feature and switch to it.
2. Making and Staging Changes
You can now start making changes to the codebase. Edit the necessary files, write new ones, or delete those no longer needed.
When you’re done with your changes, stage them for commit. Staging changes lets you selectively add just the changes you want to be part of your next commit:
git add .The . tells Git to stage all changes in the current directory. If you only want to stage some changes, you can specify the individual files instead.
3. Committing Changes
Once your changes are staged, you can commit them:
git commit -m "Add new feature"Here, -m stands for message, and “Add new feature” is the message you’re leaving. Commit messages should be concise, yet descriptive, and explain what changes were made and why.
4. Pushing Changes to Gerrit
Now that your changes are committed, you can push them to Gerrit for review. Remember, Gerrit doesn’t automatically integrate the changes into the main codebase. Instead, it treats every commit as a distinct changeset for review:
git push origin HEAD:refs/for/masterThis command pushes your changes to Gerrit. HEAD refers to your latest commit, and refs/for/master tells Gerrit that you’re pushing a changeset for review on the master branch.
It’s worth mentioning that Gerrit will provide a unique URL for each changeset once it is pushed. This URL can be used to access the review page directly, making it easy to share and discuss the changeset with your team.
5. Revising Changes
If your changes are not approved in the review, you will need to revise them. To do so, simply make the necessary adjustments to your code and commit them again.
When committing revisions, use the — amend flag to avoid creating a new changeset:
git commit - amendThis will open your default text editor, allowing you to modify your commit message if needed. When you’re done, save and close the editor to finish amending the commit.
You can then push your changes to Gerrit as before. Gerrit will recognize that this is a revised changeset, and it will keep it linked with the original changeset during the review process.
Reviewing Changes
In Gerrit, every commit goes through a review process before it can be merged into the codebase. You can view pending changesets in Gerrit’s web interface. Each changeset will show the commit message, the author, the files that were changed, and the actual changes to those files.
To review a changeset, simply click on it and start reviewing the code. Gerrit uses a scoring system from -2 to +2 to express the reviewer’s opinion about the changeset.
If the changeset is perfect, give it a +2. If it needs minor changes, give it a +1. If the changeset should not be merged as it is, give it a -1. If the changeset should never be merged, give it a -2.
Remember: Code reviews are a great opportunity for team learning and to ensure the quality of the code. Be constructive and respectful in your feedback.
Updating Changes
Even after you’ve pushed a changeset to Gerrit, it’s likely you’ll need to update it. This can happen for several reasons:
1. The code review reveals issues that need to be addressed.
2. The underlying master branch has moved forward, and your changeset needs to be rebased.
3. You’ve thought of improvements to your changeset that you’d like to include.
Here are the steps to update a changeset:
1. Updating the Code
The first step in updating your changeset is to make the necessary changes in your code. This process is just like when you made the changes in the first place: edit the files, stage the changes, and then you’re ready to commit.
If the master branch has moved forward and you need to rebase your changeset, you can do this now:
git fetch origin
git rebase origin/masterThis will update your local copy of the master branch, then replay your changes on top of it. If there are any conflicts between your changes and the new commits on master, Git will pause and allow you to resolve them.
2. Amending the Commit
Rather than creating a new commit for your changes, you’ll want to amend the existing commit. This keeps the changeset intact and allows Gerrit to track the changes over time:
git commit - amendThis command will open your text editor with the existing commit message. You can edit the message to reflect the new changes, or leave it as is if the changes are minor.
3. Pushing the Update
Once you’ve amended your commit, you can push it to Gerrit just like before:
git push origin HEAD:refs/for/masterGerrit will recognize that this is an update to an existing changeset, and it will replace the old version of the changeset with the new one. All comments and scores from the previous version are preserved, so the history of the review is maintained.
That’s it! You’ve successfully updated your changeset.
Integrating Changes
Once a changeset has been approved, it’s time to merge it into the codebase. In Gerrit, this is done through the “Submit” button in the changeset’s review page.
Gerrit also offers a “Rebase and Merge” option, which will rebase the changeset onto the latest commit on the target branch before merging it. This is useful for keeping a clean commit history.
Collaborating on Changes
Gerrit is a highly collaborative tool, so there will be many instances when you will need to check out or continue work on changes that were initiated by others. Let’s dive into these scenarios:
1. Checking Out Changes
Suppose you need to test or review changes made by another developer, or you want to continue working on their change. First, you’ll need to check out the change locally. Gerrit provides an easy way to do this:
On Gerrit’s web interface, navigate to the page for the change you’re interested in. Here you’ll see a ‘Download’ dropdown at the top-right corner of the page. Clicking this will reveal several commands. These commands are pre-formatted to match the specific change you’re viewing.
The ‘Checkout’ command is what you need to check out this change:
git fetch <repository> refs/changes/<XX>/<YYYY>/<PatchSet#> && git checkout FETCH_HEADThis command might seem intimidating, but let’s break it down:
- git fetch <repository> refs/changes/<XX>/<YYYY>/<PatchSet#>: This fetches the specific changeset from the Gerrit server. <repository> is the name of your repository, <XX> is the last two digits of the changeset number, <YYYY> is the changeset number, and <PatchSet#> is the specific version of the changeset.
— git checkout FETCH_HEAD: This checks out the changeset you just fetched. FETCH_HEAD is a temporary reference to the latest fetch.
Copy the Checkout command, paste it into your terminal in the appropriate repository, and run it. This will update your working directory to the state of the changeset.
2. Continuing Work on Changes
If you need to make further changes to the changeset you just checked out, you can do so as if it were your own work.
Make your changes, then stage them using git add. Because you’re updating an existing changeset, you’ll want to amend the commit rather than creating a new one:
git commit - amendThis command opens your text editor with the existing commit message. You can modify the message to describe your changes, or leave it as is if the changes are minor.
Finally, push the updated changeset back to Gerrit:
git push origin HEAD:refs/for/masterGerrit will recognize this as an update to an existing changeset, and it will appear as a new patch set in the change.
Conclusion
Gerrit brings the benefits of peer review to your Git workflow, helping to maintain high code quality standards. Like any tool, it requires some getting used to, but once you’ve integrated it into your workflow, you might wonder how you ever managed without it. Remember: the key to successful use of Gerrit lies in understanding its concepts and workflows, so take the time to learn and adapt it to your needs.
Happy coding!
