| :linkattrs: |
| = User Guide |
| |
| This is a Gerrit guide that is dedicated to Gerrit end-users. It |
| explains the standard Gerrit workflows and how a user can adapt Gerrit |
| to personal preferences. |
| |
| It is expected that readers know about link:http://git-scm.com/[Git,role=external,window=_blank] |
| and that they are familiar with basic git commands and workflows. |
| |
| [[gerrit]] |
| == What is Gerrit? |
| |
| Gerrit is a Git server that provides link:access-control.html[access |
| control] for the hosted Git repositories and a web front-end for doing |
| link:#code-review[code review]. Code review is a core functionality of |
| Gerrit, but still it is optional and teams can decide to |
| link:#no-code-review[work without code review]. |
| |
| [[tools]] |
| == Tools |
| |
| Gerrit uses the git protocol. This means in order to work with Gerrit |
| you do *not* need to install any Gerrit client, but having a regular |
| git client, such as the link:http://git-scm.com/[git command line,role=external,window=_blank] or |
| link:http://eclipse.org/egit/[EGit,role=external,window=_blank] in Eclipse, is sufficient. |
| |
| Still there are some client-side tools for Gerrit, which can be used |
| optionally: |
| |
| * link:http://eclipse.org/mylyn/[Mylyn Gerrit Connector,role=external,window=_blank]: Gerrit |
| integration with Mylyn |
| * link:https://github.com/uwolfer/gerrit-intellij-plugin[Gerrit |
| IntelliJ Plugin,role=external,window=_blank]: Gerrit integration with the |
| link:http://www.jetbrains.com/idea/[IntelliJ Platform,role=external,window=_blank] |
| * link:https://play.google.com/store/apps/details?id=com.jbirdvegas.mgerrit[ |
| mGerrit,role=external,window=_blank]: Android client for Gerrit |
| * link:https://github.com/stackforge/gertty[Gertty,role=external,window=_blank]: Console-based |
| interface for Gerrit |
| |
| [[clone]] |
| == Clone Gerrit Project |
| |
| Cloning a Gerrit project is done the same way as cloning any other git |
| repository by using the `git clone` command. |
| |
| .Clone Gerrit Project |
| ---- |
| $ git clone ssh://gerrithost:29418/RecipeBook.git RecipeBook |
| Cloning into RecipeBook... |
| ---- |
| |
| The URL for cloning the project can be found in the Gerrit web UI |
| under `Projects` > `List` > <project-name> > `General`. |
| |
| For git operations Gerrit supports the link:user-upload.html#ssh[SSH] |
| and the link:user-upload.html#http[HTTP/HTTPS] protocols. |
| |
| [NOTE] |
| To use SSH you may need to link:user-upload.html#ssh[configure your SSH public |
| key in your `Settings`]. |
| |
| [[code-review]] |
| == Code Review Workflow |
| |
| With Gerrit _Code Review_ means to link:#review-change[review] every |
| commit *before* it is accepted into the code base. The author of a code |
| modification link:user-upload.html#push_create[uploads a commit] as a |
| change to Gerrit. In Gerrit each change is stored in a |
| link:#change-ref[staging area] where it can be checked and reviewed. |
| Only when it is approved and submitted it gets applied to the code |
| base. If there is feedback on a change, the author can improve the code |
| modification by link:#upload-patch-set[amending the commit and |
| uploading the new commit as a new patch set]. This way a change is |
| improved iteratively and it is applied to the code base only when is |
| ready. |
| |
| [[upload-change]] |
| == Upload a Change |
| |
| 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`. |
| |
| .Push for Code Review |
| ---- |
| $ git commit |
| $ git push origin HEAD:refs/for/master |
| |
| // this is the same as: |
| $ git commit |
| $ git push origin HEAD:refs/for/refs/heads/master |
| ---- |
| |
| .Push with bypassing Code Review |
| ---- |
| $ git commit |
| $ git push origin HEAD:master |
| |
| // this is the same as: |
| $ git commit |
| $ git push origin HEAD:refs/heads/master |
| ---- |
| |
| [[push-fails]] |
| [NOTE] |
| If pushing to Gerrit fails consult the Gerrit documentation that |
| explains the link:error-messages.html[error messages]. |
| |
| [[change-ref]] |
| When a commit is pushed for review, Gerrit stores it in a staging area |
| which is a branch in the special `refs/changes/` namespace. Understanding |
| the format of this ref is not required for working with Gerrit, but it |
| is explained below. |
| |
| A change ref has the format `refs/changes/X/Y/Z` where `X` is the last |
| two digits of the change number, `Y` is the entire change number, and `Z` |
| is the patch set. For example, if the change number is |
| link:https://gerrit-review.googlesource.com/c/gerrit/+/263270[263270,role=external,window=_blank], |
| the ref would be `refs/changes/70/263270/2` for the second patch set. |
| |
| [[fetch-change]] |
| Using the change ref git clients can fetch the corresponding commit, |
| e.g. for local verification. |
| |
| .Fetch Change |
| ---- |
| $ git fetch https://gerrithost/myProject refs/changes/74/67374/2 && git checkout FETCH_HEAD |
| ---- |
| |
| [NOTE] |
| The fetch command can be copied from the |
| link:user-review-ui.html#download[download commands] in the change |
| screen. |
| |
| The `refs/for/` prefix is used to map the Gerrit concept of |
| "Pushing for Review" to the git protocol. For the git client it looks |
| like every push goes to the same branch, e.g. `refs/for/master` but in |
| fact for each commit that is pushed to this ref Gerrit creates a new |
| branch under the `refs/changes/` namespace. In addition Gerrit creates |
| an open change. |
| |
| [[change]] |
| A change consists of a link:user-changeid.html[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. |
| |
| [[change-id]] |
| 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. |
| |
| The Change-Id is a SHA-1 that is prefixed with an uppercase `I`. It is |
| specified as footer in the commit message (last paragraph): |
| |
| ---- |
| Improve foo widget by attaching a bar. |
| |
| We want a bar, because it improves the foo by providing more |
| wizbangery to the dowhatimeanery. |
| |
| Bug: #42 |
| Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b |
| Signed-off-by: A. U. Thor <author@example.com> |
| ---- |
| |
| If a commit that has a Change-Id in its commit message is pushed for |
| review, Gerrit checks if a change with this Change-Id already exists |
| for this project and target branch, and if yes, Gerrit creates a new |
| patch set for this change. If not, a new change with the given |
| Change-Id is created. |
| |
| If a commit without Change-Id is pushed for review, Gerrit creates a |
| new change and generates a Change-Id for it. Since in this case the |
| Change-Id is not included in the commit message, it must be manually |
| inserted when a new patch set should be uploaded. Most projects already |
| link:project-configuration.html#require-change-id[require a Change-Id] |
| when pushing the very first patch set. This reduces the risk of |
| accidentally creating a new change instead of uploading a new patch |
| set. Any push without Change-Id then fails with |
| link:error-missing-changeid.html[missing Change-Id in commit message |
| footer]. |
| |
| 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. |
| |
| .Push new Patch Set |
| ---- |
| $ git commit --amend |
| $ git push origin HEAD:refs/for/master |
| ---- |
| |
| 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 link:user-search.html[search] by the Change-Id |
| in the Gerrit web UI to find a fix in all branches. |
| |
| Change-Ids can be created automatically by installing the `commit-msg` |
| hook as described in the link:user-changeid.html#creation[Change-Id |
| documentation]. |
| |
| Instead of manually installing the `commit-msg` hook for each git |
| repository, you can copy it into the |
| link:http://git-scm.com/docs/git-init#_template_directory[git template |
| directory,role=external,window=_blank]. Then it is automatically copied to every newly cloned |
| repository. |
| |
| [[review-change]] |
| == Review Change |
| |
| After link:#upload-change[uploading a change for review] reviewers can |
| inspect it via the Gerrit web UI. Reviewers can see the code delta and |
| link:user-review-ui.html#inline-comments[comment directly in the code] |
| on code blocks or lines. They can also link:user-review-ui.html#reply[ |
| post summary comments and vote on review labels]. The |
| link:user-review-ui.html[documentation of the review UI] explains the |
| screens and controls for doing code reviews. |
| |
| There are several options to control how patch diffs should be |
| rendered. Users can configure their preferences in the |
| link:user-review-ui.html#diff-preferences[diff preferences]. |
| |
| [[upload-patch-set]] |
| == Upload a new Patch Set |
| |
| If there is feedback from code review and a change should be improved a |
| new patch set with the reworked code should be uploaded. |
| |
| This is done by amending the commit of the last patch set. If needed |
| this commit can be fetched from Gerrit by using the fetch command from |
| the link:user-review-ui.html#download[download commands] in the change |
| screen. |
| |
| It is important that the commit message contains the |
| link:user-changeid.html[Change-Id] of the change that should be updated |
| as a footer (last paragraph). Normally the commit message already |
| contains the correct Change-Id and the Change-Id is preserved when the |
| commit is amended. |
| |
| .Push Patch Set |
| ---- |
| // fetch and checkout the change |
| // (checkout command copied from change screen) |
| $ git fetch https://gerrithost/myProject refs/changes/74/67374/2 && git checkout FETCH_HEAD |
| |
| // rework the change |
| $ git add <path-of-reworked-file> |
| ... |
| |
| // amend commit |
| $ git commit --amend |
| |
| // push patch set |
| $ git push origin HEAD:refs/for/master |
| ---- |
| |
| [NOTE] |
| Never amend a commit that is already part of a central branch. |
| |
| Pushing a new patch set triggers email notification to the reviewers. |
| |
| [[multiple-features]] |
| == Developing multiple Features in parallel |
| |
| Code review takes time, which can be used by the change author to |
| implement other features. Each feature should be implemented in its own |
| local feature branch that is based on the current HEAD of the target |
| branch. This way there is no dependency to open changes and new |
| features can be reviewed and applied independently. If wanted, it is |
| also possible to base a new feature on an open change. This will create |
| a dependency between the changes in Gerrit and each change can only be |
| applied if all its predecessor are applied as well. Dependencies |
| between changes can be seen from the |
| link:user-review-ui.html#related-changes-tab[Related Changes] tab on |
| the change screen. |
| |
| [[watch]] |
| == Watching Projects |
| |
| To get to know about new changes you can link:user-notify.html#user[ |
| watch the projects] that you are interested in. For watched projects |
| Gerrit sends you email notifications when a change is uploaded or |
| modified. You can decide on which events you want to be notified and |
| you can filter the notifications by using link:user-search.html[change |
| search expressions]. For example '+branch:master file:^.*\.txt$+' would |
| send you email notifications only for changes in the master branch that |
| touch a 'txt' file. |
| |
| It is common that the members of a project team watch their own |
| projects and then pick the changes that are interesting to them for |
| review. |
| |
| Project owners may also configure |
| link:intro-project-owner.html#notifications[notifications on |
| project-level]. |
| |
| [[adding-reviewers]] |
| == Adding Reviewers |
| |
| In the link:user-review-ui.html#reviewers[change screen] reviewers can |
| be added explicitly to a change. The added reviewer will then be |
| notified by email about the review request. |
| |
| Mainly this functionality is used to request the review of specific |
| person who is known to be an expert in the modified code or who is a |
| stakeholder of the implemented feature. Normally it is not needed to |
| explicitly add reviewers on every change, but you rather rely on the |
| project team to watch their project and to process the incoming changes |
| by importance, interest, time etc. |
| |
| There are also link:intro-project-owner.html#reviewers[plugins which |
| can add reviewers automatically] (e.g. by configuration or based on git |
| blame annotations). If this functionality is required it should be |
| discussed with the project owners and the Gerrit administrators. |
| |
| [[dashboards]] |
| == Dashboards |
| |
| Gerrit supports a wide range of link:user-search.html#search-operators[ |
| query operators] to search for changes by different criteria, e.g. by |
| status, change owner, votes etc. |
| |
| The page that shows the results of a change query has the change query |
| contained in its URL. This means you can bookmark this URL in your |
| browser to save the change query. This way it can be easily re-executed |
| later. |
| |
| Several change queries can be also combined into a dashboard. A |
| dashboard is a screen in Gerrit that presents the results of several |
| change queries in different sections, each section having a descriptive |
| title. |
| |
| A default dashboard is available under `My` > `Changes`. It has |
| sections to list outgoing reviews, incoming reviews and recently closed |
| changes. |
| |
| Users can also define link:user-dashboards.html#custom-dashboards[ |
| custom dashboards]. Dashboards can be bookmarked in a browser so that |
| they can be re-executed later. |
| |
| It is also possible to link:#my-menu[customize the My menu] and add |
| menu entries for custom queries or dashboards to it. |
| |
| Dashboards are very useful to define own views on changes, e.g. you can |
| have different dashboards for own contributions, for doing reviews or |
| for different sets of projects. |
| |
| [NOTE] |
| You can use the link:user-search.html#limit[limit] and |
| link:user-search.html#age[age] query operators to limit the result set |
| in a dashboard section. Clicking on the section title executes the |
| change query without the `limit` and `age` operator so that you can |
| inspect the full result set. |
| |
| Project owners can also define shared |
| link:user-dashboards.html#project-dashboards[dashboards on |
| project-level]. The project dashboards can be seen in the web UI under |
| `Projects` > `List` > <project-name> > `Dashboards`. |
| |
| [[submit]] |
| == Submit a Change |
| |
| Submitting a change means that the code modifications of the current |
| patch set are applied to the target branch. Submit requires the |
| link:access-control.html#category_submit[Submit] access right and is |
| done on the change screen by clicking on the |
| link:user-review-ui.html#submit[Submit] button. |
| |
| In order to be submittable changes must first be approved by |
| link:user-review-ui.html#vote[voting on the review labels]. By default |
| a change can only be submitted if it has a vote with the highest value |
| on each review label and no vote with the lowest value (veto vote). |
| Projects can configure link:intro-project-owner.html#labels[custom |
| labels] and link:intro-project-owner.html#submit-rules[custom submit |
| rules] to control when a change becomes submittable. |
| |
| How the code modification is applied to the target branch when a change |
| is submitted is controlled by the |
| link:config-project-config.html#submit-type[submit type] which can be |
| link:intro-project-owner.html#submit-type[configured on project-level]. |
| |
| Submitting a change may fail with conflicts. In this case you need to |
| link:#rebase[rebase] the change locally, resolve the conflicts and |
| upload the commit with the conflict resolution as new patch set. |
| |
| If a change cannot be merged due to path conflicts this is highlighted |
| on the change screen by a bold red `Cannot Merge` label. |
| |
| [[rebase]] |
| == Rebase a Change |
| |
| While a change is in review the HEAD of the target branch can evolve. |
| In this case the change can be rebased onto the new HEAD of the target |
| branch. When there are no conflicts the rebase can be done directly |
| from the link:user-review-ui.html#rebase[change screen], otherwise it |
| must be done locally. |
| |
| .Rebase a Change locally |
| ---- |
| // update the remote tracking branches |
| $ git fetch |
| |
| // fetch and checkout the change |
| // (checkout command copied from change screen) |
| $ git fetch https://gerrithost/myProject refs/changes/74/67374/2 && git checkout FETCH_HEAD |
| |
| // do the rebase |
| $ git rebase origin/master |
| |
| // resolve conflicts if needed and stage the conflict resolution |
| ... |
| $ git add <path-of-file-with-conflicts-resolved> |
| |
| // continue the rebase |
| $ git rebase --continue |
| |
| // push the commit with the conflict resolution as new patch set |
| $ git push origin HEAD:refs/for/master |
| ---- |
| |
| Doing a manual rebase is only necessary when there are conflicts that |
| cannot be resolved by Gerrit. If manual conflict resolution is needed |
| also depends on the link:intro-project-owner.html#submit-type[submit |
| type] that is configured for the project. |
| |
| Generally changes shouldn't be rebased without reason as it |
| increases the number of patch sets and creates noise with |
| notifications. However if a change is in review for a long time it may |
| make sense to rebase it from time to time, so that reviewers can see |
| the delta against the current HEAD of the target branch. It also shows |
| that there is still an interest in this change. |
| |
| [NOTE] |
| Never rebase commits that are already part of a central branch. |
| |
| [[move]] |
| == Move a Change |
| |
| Changes can be link:rest-api-changes.html#move-change[moved] to a desired |
| destination branch in the same project. This is useful in cases where |
| development activity switches from one branch to another and there is a |
| need to move open changes on the inactive branch to the new active one. |
| Another useful case is to move changes from a newer branch back to an older |
| bugfix branch where an issue first appeared. |
| |
| Users can move a change only if they have link:access-control.html#category_abandon[ |
| abandon permission] on the change and link:access-control.html#category_push[ |
| push permission] on the destination branch. |
| |
| The move operation will not update the change's parent and users will have |
| to link:#rebase[rebase] the change. |
| |
| [[abandon]] |
| [[restore]] |
| == Abandon/Restore a Change |
| |
| Sometimes during code review a change is found to be bad and it should |
| be given up. In this case the change can be |
| link:user-review-ui.html#abandon[abandoned] so that it doesn't appear |
| in list of open changes anymore. |
| |
| Abandoned changes can be link:user-review-ui.html#restore[restored] if |
| later they are needed again. |
| |
| [[cherrypickof]] |
| == Cherry-Pick changes of a Change |
| |
| When a change is created/updated using the 'cherry-pick' functionalty, |
| the original change and patchset details are recorded in the Change's |
| cherrypick field. This field cannot be set or updated by the user in |
| any way. It is set automatically after the cherry-pick operation completes |
| successfully. |
| |
| [[topics]] |
| == Using Topics |
| |
| Changes can be grouped by topics. This is useful because it allows you |
| to easily find related changes by using the |
| link:user-search.html#topic[topic search operator]. Also on the change |
| screen link:user-review-ui.html#same-topic[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 |
| link:user-review-ui.html#project-branch-topic[change screen]. |
| |
| It is also possible to link:user-upload.html#topic[set a topic on |
| push], either by appending `%topic=...` to the ref name or through |
| the use of the command line flag `--push-option`, aliased to `-o`, |
| followed by `topic=...`. |
| |
| Gerrit may be link:config-gerrit.html#change.submitWholeTopic[configured] to |
| submit all changes in a topic together with a single click, even when topics |
| span multiple projects. |
| |
| .Set Topic on Push |
| ---- |
| $ git push origin HEAD:refs/for/master%topic=multi-master |
| |
| // this is the same as: |
| $ git push origin HEAD:refs/heads/master -o topic=multi-master |
| ---- |
| |
| For more information about using topics, see the user guide: |
| link:cross-repository-changes.html[Submitting Changes Across Repositories by using Topics]. |
| |
| [[hashtags]] |
| == Using Hashtags |
| |
| Hashtags are freeform strings associated with a change, like on social media |
| platforms. In Gerrit, you explicitly associate hashtags with changes using a |
| dedicated area of the UI; they are not parsed from commit messages or comments. |
| |
| Similar to topics, hashtags can be used to group related changes together, and |
| to search using the link:user-search.html#hashtag[`hashtag:`] operator. Unlike |
| topics, a change can have multiple hashtags, and they are only used for |
| informational grouping; changes with the same hashtags are not necessarily |
| submitted together. |
| |
| .Set Hashtag on Push |
| ---- |
| $ git push origin HEAD:refs/for/master%t=stable-bugfix |
| |
| // this is the same as: |
| $ git push origin HEAD:refs/heads/master -o t=stable-bugfix |
| ---- |
| |
| [[wip]] |
| == Work-in-Progress Changes |
| |
| Work-in-Progress (WIP) changes are visible to anyone, but do not notify or |
| require an action from a reviewer. |
| |
| Specifically, when you mark a change as Work-in-Progress: |
| |
| * Reviewers are not notified for most operations, such as adding or removing, |
| posting comments, and so on. See the REST API documentation |
| link:rest-api-changes.html#set-review-notifications[tables] for more |
| information. |
| * The change does not show in reviewers' dashboards. |
| |
| WIP changes are useful when: |
| |
| * You have implemented only part of a change, but want to push your change |
| to the server to run tests or perform other actions before requesting |
| reviewer feedback. |
| * During a review, you realize you need to rework your change, and you |
| want to stop notifying reviewers of the change until you finish your |
| update. |
| |
| To set the status of a change to Work-in-Progress, you can use either |
| the command line or the user interface. To use the command line, append |
| `%wip` to your push request. |
| |
| ---- |
| $ git push origin HEAD:refs/for/master%wip |
| ---- |
| Alternatively, click *WIP* from the *More* menu on the Change screen. |
| The Change screen updates with a yellow header, indicating that |
| the change is in a Work-in-Progress state. |
| |
| To mark the change as ready for review, append `%ready` to your push |
| request. |
| |
| ---- |
| $ git push origin HEAD:refs/for/master%ready |
| ---- |
| There are two options for marking the change ready for review from the Change |
| screen: |
| |
| 1. Click *Start Review* (the primary action *Reply* is renamed when in WIP |
| state). |
| + |
| This will open the reply-modal and allow you to add reviewers and/or CC |
| before you start review. |
| |
| 2. Click button *Mark As Active*. |
| + |
| This will only change the state from WIP to ready, without opening the |
| reply-modal. |
| |
| Change owners, project owners, site administrators and members of a group that |
| was granted link:access-control.html#category_toggle_work_in_progress_state[ |
| Toggle Work In Progress state] permission can mark changes as `work-in-progress` |
| and `ready`. |
| |
| [[private-changes]] |
| == Private Changes |
| |
| Private changes are changes that are only visible to their owners, reviewers |
| and users with the link:access-control.html#category_view_private_changes[ |
| View Private Changes] global capability. Private changes are useful in a number |
| of cases: |
| |
| * You want a set of collaborators to review the change before formal review |
| starts. By creating a Private change and adding only a selected few as |
| reviewers you can control who can see the change and get a first opinion |
| before opening up for all reviewers. |
| |
| * You want to check what the change looks like before formal review starts. |
| By marking the change private without reviewers, nobody can |
| prematurely comment on your changes. |
| |
| * You want to use Gerrit to sync data between different devices. By |
| creating a private throwaway change without reviewers, you can push |
| from one device, and fetch to another device. |
| |
| Do *not* use private changes for making security fixes (see |
| link:#private-changes-pitfalls[pitfalls] below). How to make security |
| fixes is explained link:#security-fixes[below]. |
| |
| To create a private change, you push it with the `private` option. |
| |
| .Push a private change |
| ---- |
| $ git commit |
| $ git push origin HEAD:refs/for/master%private |
| ---- |
| |
| The change will remain private on subsequent pushes until you specify |
| the `remove-private` option. Alternatively, the web UI provides buttons |
| to mark a change private and non-private again. |
| |
| When pushing a private change with a commit that is authored by another |
| user, the other user will not be automatically added as a reviewer and |
| must be explicitly added. |
| |
| For CI systems that must verify private changes, a special permission |
| can be granted |
| (link:access-control.html#category_view_private_changes[View Private Changes]). |
| In that case, care should be taken to prevent the CI system from |
| exposing secret details. |
| |
| [[private-changes-pitfalls]] |
| === Pitfalls |
| |
| If private changes are used, be aware of the following pitfalls: |
| |
| * If a private change gets merged the corresponding commit gets visible |
| for all users that can access the target branch and the private flag |
| from the change is automatically removed. This makes private changes |
| a bad choice for security fixes, as the security fix will be |
| accessible as soon as the change was merged, but for security issues |
| you want to keep an embargo until new releases have been made |
| available. |
| * If you push a non-private change on top of a private change the |
| commit of the private change gets implicitly visible through the |
| parent relationship of the follow-up change. |
| * If you have a series of private changes and share one with reviewers, |
| the reviewers can also see the commits of the predecessor private |
| changes through the commit parent relationship. |
| * Users who would have permission to access the change except for its |
| private status and knowledge of its commit ID (e.g. through CI logs |
| or build artifacts containing build numbers) can fetch the code |
| using the commit ID. |
| |
| [[ignore]] |
| == Ignoring Or Marking Changes As 'Reviewed' |
| |
| Changes can be ignored, which means they will not appear in the 'Incoming |
| Reviews' dashboard and any related email notifications will be suppressed. |
| This can be useful when you are added as a reviewer to a change on which |
| you do not actively participate in the review, but do not want to completely |
| remove yourself. |
| |
| Alternatively, rather than completely ignoring the change, it can be marked |
| as 'Reviewed'. Marking a change as 'Reviewed' means it will not be highlighted |
| in the dashboard, until a new patch set is uploaded. |
| |
| [[inline-edit]] |
| == Inline Edit |
| |
| It is possible to link:user-inline-edit.html#editing-change[edit |
| changes inline] directly in the web UI. This is useful to make small |
| corrections immediately and publish them as a new patch set. |
| |
| It is also possible to link:user-inline-edit.html#create-change[create |
| new changes inline]. |
| |
| [[roles]] |
| == Roles |
| |
| Making and reviewing changes usually involves multiple users that |
| assume different roles: |
| |
| - Author: |
| + |
| The person who wrote the code change. Recorded as author in the Git |
| commit. |
| |
| - Committer: |
| + |
| The person who created the Git commit, e.g. the person that executed |
| the `git commit` command. Recorded as committer in the Git commit. |
| |
| - Uploader: |
| + |
| The user that uploaded the commit as a patch set to Gerrit, e.g. the |
| user that executed the `git push` command. For commits that are created through |
| an action in the web UI the uploader is the user that triggered the action (e.g. |
| if a commit is created by clicking on the `REBASE` button, the user clicking on |
| the button becomes the uploader of the newly created commit). |
| + |
| The uploader of the first patch set is the change owner. |
| + |
| The uploader of the latest patch set, the user that uploaded the |
| current patch set, is relevant when |
| link:config-labels.html#label_ignoreSelfApproval[self approvals on labels are |
| ignored], as in this case approvals from the uploader of the latest patch set |
| are ignored. |
| |
| - Change Owner: |
| + |
| The user that created the change, e.g. uploaded the first patch set. |
| |
| - Reviewer: |
| + |
| A user that has reviewed the change or has been asked to review the change. |
| |
| Often one user assumes several of these roles, but it's possible that each role |
| is assumed by a different user. |
| |
| [[project-administration]] |
| == Project Administration |
| |
| Every project has a link:intro-project-owner.html#project-owner[project |
| owner] that administrates the project. Project administration includes |
| the configuration of the project |
| link:intro-project-owner.html#access-rights[access rights], but project |
| owners have many more possibilities to customize the workflows for a |
| project which are described in the link:intro-project-owner.html[ |
| project owner guide]. |
| |
| [[no-code-review]] |
| == Working without Code Review |
| |
| Doing code reviews with Gerrit is optional and you can use Gerrit |
| without code review as a pure Git server. |
| |
| .Push with bypassing Code Review |
| ---- |
| $ git commit |
| $ git push origin HEAD:master |
| |
| // this is the same as: |
| $ git commit |
| $ git push origin HEAD:refs/heads/master |
| ---- |
| |
| [NOTE] |
| Bypassing code review must be enabled in the project access rights. The |
| project owner must allow it by assigning the |
| link:access-control.html#category_push_direct[Push] access right on the |
| target branch (`refs/heads/<branch-name>`). |
| |
| [NOTE] |
| If you bypass code review you always need to merge/rebase manually if |
| the tip of the destination branch has moved. Please keep this in mind |
| if you choose to not work with code review because you think it's |
| easier to avoid the additional complexity of the review workflow; it |
| might actually not be easier. |
| |
| [NOTE] |
| The project owner may enable link:user-upload.html#auto_merge[ |
| auto-merge on push] to benefit from the automatic merge/rebase on |
| server side while pushing directly into the repository. |
| |
| [[user-refs]] |
| == User Refs |
| |
| User configuration data such as link:#preferences[preferences] is |
| stored in the `All-Users` project under a per-user ref. The user's |
| ref is based on the user's account id which is an integer. The user |
| refs are sharded by the last two digits (`+nn+`) in the refname, |
| leading to refs of the format `+refs/users/nn/accountid+`. |
| |
| [[preferences]] |
| == Preferences |
| |
| There are several options to control the rendering in the Gerrit web UI. |
| Users can configure their preferences under `Settings` > `Preferences`. |
| The user's preferences are stored in a `git config` style file named |
| `preferences.config` under the link:#user-refs[user's ref] in the |
| `All-Users` project. |
| |
| The following preferences can be configured: |
| |
| - [[page-size]]`Maximum Page Size`: |
| + |
| The maximum number of entries that are shown on one page, e.g. used |
| when paging through changes, projects, branches or groups. |
| |
| - [[date-time-format]]`Date/Time Format`: |
| + |
| The format that should be used to render dates and timestamps. |
| |
| - [[email-notifications]]`Email Notifications`: |
| + |
| This setting controls the email notifications. |
| + |
| ** [[cc-me]]`Every comment`: |
| + |
| Email notifications are enabled and you get notified by email as CC |
| on comments that you write yourself. |
| + |
| ** `Only comments left by others` |
| + |
| Email notifications are enabled for all activities excluding comments or |
| reviews authored by you. |
| + |
| ** `Only when I am in the attention set` |
| + |
| Email notifications are only sent if the recipient is in the attention set. |
| + |
| ** `None`: |
| + |
| Email notifications are disabled. |
| |
| - [[email-format]]`Email Format`: |
| + |
| This setting controls the email format Gerrit sends. Note that this |
| setting has no effect if the administrator has disabled HTML emails |
| for the Gerrit instance. |
| + |
| ** `Plaintext Only`: |
| + |
| Email notifications contain only plaintext content. |
| + |
| ** `HTML and Plaintext`: |
| + |
| Email notifications contain both HTML and plaintext content. |
| |
| - [[default-base-for-merges]]`Default Base For Merges`: |
| + |
| This setting controls which base should be pre-selected in the |
| `Diff Against` drop-down list when the change screen is opened for a |
| merge commit. |
| + |
| ** `Auto Merge`: |
| + |
| Pre-selects `Auto Merge` in the `Diff Against` drop-down list when the |
| change screen is opened for a merge commit. |
| + |
| ** `First Parent`: |
| + |
| Pre-selects `Parent 1` in the `Diff Against` drop-down list when the |
| change screen is opened for a merge commit. |
| + |
| |
| - [[diff-view]]`Diff View`: |
| + |
| Whether the Side-by-Side diff view or the Unified diff view should be |
| shown when clicking on a file path in the change screen. |
| |
| - [[show-site-header]]`Show Site Header / Footer`: |
| + |
| Whether the site header and footer should be shown. |
| |
| - [[relative-dates]]`Show Relative Dates In Changes Table`: |
| + |
| Whether timestamps in change lists and dashboards should be shown as |
| relative timestamps, e.g. '12 days ago' instead of absolute timestamps |
| such as 'Apr 15'. |
| |
| - [[change-size-bars]]`Show Change Sizes As Colored Bars`: |
| + |
| Whether change sizes should be visualized as colored bars. If disabled |
| the numbers of added and deleted lines are shown as text, e.g. |
| '+297, -63'. |
| |
| - [[show-change-number]]`Show Change Number In Changes Table`: |
| + |
| Whether in change lists and dashboards an `ID` column with the numeric |
| change IDs should be shown. |
| |
| - [[mute-common-path-prefixes]]`Mute Common Path Prefixes In File List`: |
| + |
| Whether common path prefixes in the file list on the change screen |
| should be link:user-review-ui.html#repeating-path-segments[grayed out]. |
| |
| - [[inline-signed-off]]`Insert Signed-off-by Footer For Inline Edit Changes`: |
| + |
| Whether a `Signed-off-by` footer should be automatically inserted into |
| changes that are created from the web UI (e.g. by the `Create Change` |
| and `Edit Config` buttons on the project screen, and the `Follow-Up` |
| button on the change screen). |
| |
| - [[publish-comments-on-push]]`Publish comments on push`: |
| + |
| Whether to publish any outstanding draft comments by default when pushing |
| updates to open changes. This preference just sets the default; the behavior can |
| still be overridden using a link:user-upload.html#publish-comments[push option]. |
| |
| - [[use-flash]]`Use Flash Clipboard Widget`: |
| + |
| Whether the Flash clipboard widget should be used. If enabled and the Flash |
| plugin is available, Gerrit offers a copy-to-clipboard icon next to IDs and |
| commands that need to be copied frequently, such as the Change-Ids, commit IDs |
| and download commands. Note that this option is only shown if the Flash plugin |
| is available and the JavaScript Clipboard API is unavailable. |
| |
| - [[work-in-progress-by-default]]`Set new changes work-in-progress`: |
| + |
| Whether new changes are uploaded as work-in-progress per default. This |
| preference just sets the default; the behavior can still be overridden using a |
| link:user-upload.html#wip[push option]. |
| |
| [[my-menu]] |
| In addition it is possible to customize the menu entries of the `My` |
| menu. This can be used to make the navigation to frequently used |
| screens, e.g. configured link:#dashboards[dashboards], quick. |
| |
| [[reply-by-email]] |
| == Reply by Email |
| |
| Gerrit sends out email notifications to users and supports parsing back replies |
| on some of them (when link:config-gerrit.html#receiveemail[configured]). |
| |
| Gerrit supports replies on these notification emails: |
| |
| * Notifications about new comments |
| * Notifications about new labels that were applied or removed |
| |
| While Gerrit supports a wide range of email clients, the following ones have |
| been tested and are known to work: |
| |
| * Gmail |
| * Gmail Mobile |
| |
| Gerrit supports parsing back all comment types that can be applied to a change |
| via the WebUI: |
| |
| * Change messages |
| * Inline comments |
| * File comments |
| |
| Please note that comments can only be sent in reply to a comment in the original |
| notification email, while the change message is independent of those. |
| |
| Gerrit supports parsing a user's reply from both HTML and plaintext. Please note |
| that some email clients extract the text from the HTML email they have received |
| and send this back as a quoted reply if you have set the client to plaintext |
| mode. In this case, Gerrit only supports parsing a change message. To work |
| around this issue, consider setting a <<email-format,User Preference>> to |
| receive only plaintext emails. |
| |
| Example notification: |
| ---- |
| Some User has posted comments on this change. |
| (https://gerrit-review.googlesource.com/123123 ) |
| |
| Change subject: My new change |
| ...................................................................... |
| |
| |
| Patch Set 3: |
| |
| Just a couple of smaller things I found. |
| |
| https://gerrit-review.googlesource.com/#/c/123123/3/MyFile.java |
| File |
| MyFile.java: |
| |
| https://gerrit-review.googlesource.com/#/c/123123/3/MyFile@420 |
| PS3, Line 420: someMethodCall(param); |
| Seems to be failing the tests. |
| |
| |
| -- |
| To view, visit https://gerrit-review.googlesource.com/123123 |
| To unsubscribe, visit https://gerrit-review.googlesource.com/settings |
| |
| (Footers omitted for brevity, must be included in all emails) |
| ---- |
| |
| Example response from the user: |
| ---- |
| Thanks, I'll fix it. |
| > Some User has posted comments on this change. |
| > (https://gerrit-review.googlesource.com/123123 ) |
| > |
| > Change subject: My new change |
| > ...................................................................... |
| > |
| > |
| > Patch Set 3: |
| > |
| > Just a couple of smaller things I found. |
| > |
| > https://gerrit-review.googlesource.com/#/c/123123/3/MyFile.java |
| > File |
| > MyFile.java: |
| Rename this file to File.java |
| > |
| > https://gerrit-review.googlesource.com/#/c/123123/3/MyFile@420 |
| > PS3, Line 420: someMethodCall(param); |
| > Seems to be failing the tests. |
| > |
| Yeah, I see why, let me try again. |
| > |
| > -- |
| > To view, visit https://gerrit-review.googlesource.com/123123 |
| > To unsubscribe, visit https://gerrit-review.googlesource.com/settings |
| > |
| > (Footers omitted for brevity, must be included in all emails) |
| ---- |
| |
| In this case, Gerrit will persist a change message ("Thanks, I'll fix it."), |
| a file comment ("Rename this file to File.java") as well as a reply to an |
| inline comment ("Yeah, I see why, let me try again."). |
| |
| [[security-fixes]] |
| -- Security Fixes |
| |
| If a security vulnerability is discovered you normally want to have an |
| embargo about it until fixed releases have been made available. This |
| means you want to develop and review security fixes in private. |
| |
| If your repository is public or grants broad read access it is |
| recommended to fix security issues in a copy of your repository which |
| has very restricted read permissions (e.g. `myproject-security-fixes`). |
| You can then implement, review and submit the security fix in this |
| repository, make and publish a new release and only then integrate the |
| security fix back into the normal (public) repository. |
| |
| Alternatively you can do the security fix in your normal repository in |
| a branch with restricted read permissions. We don't recommend this |
| because there is a risk of configuring the access rights wrongly and |
| unintentionally granting read access to the wrong people. |
| |
| Using private changes for security fixes is *not* recommended due to |
| the link:#private-changes-pitfalls[pitfalls] discussed above. |
| Especially you don't want the fix to become visible after submit and |
| before you had a chance to make and publish a new release. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |