-
Notifications
You must be signed in to change notification settings - Fork 3
Gerrit
Uploading a change to Gerrit is done by pushing a commit to Gerrit. The commit must be pushed to a ref in the refs/for/ namespace which defines the target branch: refs/for/<target-branch>. The magic refs/for/ prefix allows Gerrit to differentiate commits that are pushed for review from commits that are pushed directly into the repository, bypassing code review. For the target branch it is sufficient to specify the short name, e.g. master, but you can also specify the fully qualified branch name, e.g. refs/heads/master.
When a commit is pushed for review, Gerrit stores it in a staging area which is a branch in the special refs/changes/ namespace. A change ref has the format refs/changes/XX/YYYY/ZZ where YYYY is the numeric change number, ZZ is the patch set number and XX is the last two digits of the numeric change number, e.g. refs/changes/20/884120/1. Understanding the format of this ref is not required for working with Gerrit.
A change consists of a Change-Id, meta data (owner, project, target branch etc.), one or more patch sets, comments and votes. A patch set is a git commit. Each patch set in a change represents a new version of the change and replaces the previous patch set. Only the latest patch set is relevant. This means all failed iterations of a change will never be applied to the target branch, but only the last patch set that is approved is integrated.
The Change-Id is important for Gerrit to know whether a commit that is pushed for code review should create a new change or whether it should create a new patch set for an existing change.
Amending and rebasing a commit preserves the Change-Id so that the new commit automatically becomes a new patch set of the existing change, when it is pushed for review.
Change-Ids are unique for a branch of a project. E.g. commits that fix the same issue in different branches should have the same Change-Id, which happens automatically if a commit is cherry-picked to another branch. This way you can search by the Change-Id in the Gerrit web UI to find a fix in all branches.
Changes can be grouped by topics. This is useful because it allows you to easily find related changes by using the topic search operator. Also on the change screen changes with the same topic are displayed so that you can easily navigate between them.
Often changes that together implement a feature or a user story are group by a topic.
Assigning a topic to a change can be done in the change screen.
It is also possible to set a topic on push.
Access rights in Gerrit are assigned on references (aka refs). Refs in Git exist in different namespaces, e.g. all branches normally exist under refs/heads/ and all tags under refs/tags/. In addition there are a number of special refs and magic refs.
Access rights can be assigned on a concrete ref, e.g. refs/heads/master but also on ref patterns and regular expressions for ref names.
A ref pattern ends with /* and describes a complete ref name namespace, e.g. access rights assigned on refs/heads/* apply to all branches.
Regular expressions must start with ^, e.g. access rights assigned on ^refs/heads/rel-.* would apply to all rel-* branches.
The reference name connected to a Push Merge Commit entry must always be prefixed with refs/for/, for example refs/for/refs/heads/BRANCH. This applies even for an entry that complements a Push entry for refs/heads/BRANCH that allows direct pushes of non-merge commits, and the intention of the Push Merge Commit entry is to allow direct pushes of merge commits.