Schema Change

WARNING: This release contains schema changes. To upgrade:

  java -jar gerrit.war init -d site_path

WARNING: Upgrading to 2.2.x requires the server be first upgraded to 2.1.7 (or a later 2.1.x version), and then to 2.2.x.

New Features


  • issue 971 Use Prolog Cafe for ChangeControl.canSubmit()

  • Add per-project prolog submit rule files

    When loading the prolog environment, now checks refs/meta/config branch for a file called If it exists, consult the file. Expects a predicate called submit_rule. If no file is found, uses the default_submit predicate in

  • Add inheritance of prolog rules

    Projects now inherit the prolog rules defined in their parent project. Submit results from the child project are filtered by the parent project using the filter predicate defined in the parent’s The results of the filtering are then passed up to the parent’s parent and filtered, repeating this process up to the top level All-Projects.

  • Load precompiled prolog rules from jar file

    Looks in (site)/cache/rules for a jar file called: rules-(sha1 of Loads the precompiled prolog rules and uses them instead of consulting If the jar does not exist, consults If does not exist, uses the default submit rules.

  • Cmd line tool rulec to compile jar from prolog

    Rulec takes from the refs/meta/config branch and creates a jar file named rules-(sha1 of in (sitepath)/cache/rules. Generates temporary prolog, java src, and class files which are deleted afterwards.

  • prolog-shell: Simple command line Prolog interpreter

    Define a small interactive interpreter that users or site administrators can play around with by downloading the Gerrit WAR file and executing: java -jar gerrit.war prolog-shell

Prolog Predicates

  • Add Prolog Predicates to check commit messages and edits

    commit_message returns the commit message as a symbol.

    commit_message_matches takes in a regex pattern and checks it against the commit message.

    commit_edits takes in a regex pattern for filenames and a regex pattern for edits. For all files in a commit that match the filename regex. Returns true if the edits in any of those files match the edit regex.

  • Add Prolog Predicates to expose commit filelist

    commit_delta/1,3,4 each takes a regular expression and matches it to the path of all the files in the latest patchset of a commit. If applicable (changes where the file is renamed or copied), the regex is also checked against the old path.

    commit_delta/1 returns true if any files match the regex

    commit_delta/3 returns the changetype and path, if the changetype is renamed, it also returns the old path. If the changetype is rename, it returns a delete for oldpath and an add for newpath. If the changetype is copy, an add is returned along with newpath.

    commit_delta/4 returns the changetype, new path, and old path (if applicable).

  • Add Prolog predicates that expose the branch, owner, project, and topic of a change, the author and committer of the most recent patchset in the change, and who is the current user.

  • For user-related predicates, if the user is not a gerrit user, will return user(anonymous) or similar. Author and committer predicates for commits return user(id), name, and email.

  • Make max_with_block/4 public

    This is the current rule generally applied to a label function. Make it exportable for now until we can come back and clean up the legacy approval data code.


  • Support in Firefox delete key in NpIntTextBox

    Pressing the delete key while being in a NpIntTextBox (e.g. in the text box for the Tab Width or Columns preference when comparing a file) now works in Firefox.

  • Make sure special keys work in text fields

    There is a bug in gwt 2.1.0 that prevents pressing special keys like Enter, Backspace etc. from being properly recognized and so they have no effect.


  • issue 855 Indicate outdated dependencies on the ChangeScreen

    If a change dependency is no longer the latest patchSet for that change, mark it OUTDATED in the dependencies table and make its row red, and add a warning message to the dependencies header, also keep the dependencies disclosure panel open even when an outdated dependent change is merged. Additionally make the link for dependencies link to the exact patchSet of the dependent change.

  • issue 881 Allow adding groups as reviewer

    On the ChangeScreen it is now possible to add a group as reviewer for a change. When a group is added as reviewer the group is resolved and all its members are added as reviewers to the change.

  • Update approvals in web UI to adapt to submit_rule

    The UI now shows whatever the results of the submit_rule are, which permits the submit_rule to make an ApprovalCategory optional, or to make a new label required.

Diff Screen

  • Add top level menus for a new PatchScreen header

    Modify the PatchScreen so that the header contents is selectable using top level menus. Allow the header to display the commit message, the preferences, the Patch Sets, or the File List.

  • Add SideBySide and Unified links to Differences top level menus

    These new menu entries allow a user to switch view types easily without returning to the ChangeScreen. Also, they double as a way to hide the header on the PatchScreen (when clicking on the currently displayed type).

  • Add user pref to retain PatchScreen Header when changing files

  • Flip the orientation of PatchHistory Table

  • Remove the Change SHA1: from the PatchScreen title

  • Remove scrollbar from Commit Message

  • Allow comment editing with single click on line numbers

    Make it easier to comment (and now possible on android devices which zoom on double click) on a patch by simply clicking on the line number.

  • Add a "Save" button to the PatchScriptSettingsPanel

    The "Update" button now only updates the display. Additionally, for logged in users, a "Save" button now behaves the way that "Update" used to behave for logged in users.

  • issue 665 Display merge changes as differences from automatic result

    Instead of displaying nothing for a two-parent merge commit, compute the automatic merge result and display the difference between the automatic result that Git would create, and the actual result that was uploaded by the author/committer of the merge.


  • Add menu to AccountGroupScreen

    This change introduces a menu in the AccountGroupScreen and different screens for subsets of the functionality (similar as it’s done for the ProjectScreen). Links from other screens to the AccountGroupScreen are resolved depending on the group type.

  • Display groupUUID on AccountGroupInfoScreen

    To assign a privilege to a new group by editing the project.config file, the new group needs to be added to the groups file in the refs/meta/config branch which requires the UUID of the group to be known.

Project Access

  • Automatically add new rule when adding new permission

    If a new permission was added to a block, immediately create the new group entry box and focus it, so the user can assign the permission.

  • Only show Exclusive checkbox on reference sections

    In the access editor, hide the Exclusive checkbox on the Global Capabilities section since it has no inheritance and the exclusive bit isn’t supported.

  • Disable editing after successful save of Access screen

    When the access has been successfully modified for a project, switch back to the "read-only" view where the widgets are all disabled and the Edit button is enabled.

Project Branches

  • Display refs/meta/config branch on ProjectBranchesScreen

    The new refs/meta/config branch was not shown in the ProjectBranchesScreen. Since refs/meta/config is not just any branch, but has a special meaning to Gerrit it is now displayed at the top below HEAD.

  • Highlight HEAD and refs/meta/config

    Since HEAD and refs/meta/config do not represent ordinary branches, highlight their rows with a special style in the ProjectBranchesScreen.



  • Added a set-reviewers ssh command

  • Support removing more than one reviewer at once

    This way we can batch delete reviewers from a change.

  • issue 881 Support adding groups as reviewer by SSH command

    With the set-reviewers SSH command it is now possible to also add groups as reviewer for a change.

  • Fail review command for changing labels when change is closed

    If a reviewer attempts to change a review label (approval) after a change is closed using the ssh review command, cause it to fail the command and output a message.

  • ls-projects: Fix display of All-Projects under --tree

    Everything should be nested below All-Projects, since that is actually the root level.

  • ls-projects: Add --type to filter by project type

    ls-projects now supports --type code|permissions|all. The default is code which now skips permissions only projects, restoring the output to what appears from Gerrit 2.1.7 and earlier.

  • show-caches: Improve memory reporting

    Change the way memory is reported to show the actual values, and the equation that determines how these are put together to form the current usage. Include some additional data including server version, current time, process uptime, active SSH connections, and tasks in the task queue. The --show-jvm option will report additional data about the JVM, and tell the caller where it is running.


  • Output patchset creation date for query command.

  • issue 1053 Support comments option in query command

    Query SSH command will show all comments if option --comments is used. If --comments is used together with --patch-sets all inline comments are included in the output.


  • Move batch user priority to a capability

    Instead of using a magical group, use a special capability to denote users that should get the batch priority behavior.

  • issue 742 Make administrator, create-project a global capability

    This gets rid of the special entries in system_config and gerrit.config related to who the Administrators group is, or which groups are permitted to create new projects on this server.

  • issue 48 & 742 Add fine-grained capabilities for administrative actions

    The Global Capabilities section in All-Projects can now be used to grant subcommands that are available over SSH and were previously restricted to only Administrators.

  • Disallow project names ending in "/"

  • issue 934 query: Enable configurable result limit

    Allow site administrators to configure the query limit for user to be above the default hard-coded value of 500 by adding a global [capability] block to All-Projects project.config file with group(s) that should have different limits.

  • Introduced a new PermissionRule.Action: BLOCK.

    Besides already existing ALLOW and DENY actions this change introduces the BLOCK action in order to enable blocking some permission rules globally.

  • issue 813 Use to hide permissions

    Administrators can now disable replication of permissions-only projects and the per-project refs/meta/config in replication.config by setting the replicatePermissions field to false.

  • Add a Restored.vm template and use it.

    The restore action has been erroneously using the Abandoned.vm template. Create a template and sender for the restorecommand.

  • sshd.advertisedAddress: specify the displayed SSH host/port

    This allows aliases which redirect to gerrit’s ssh port (say from port 22) to be setup and advertised to users.


  • Updated eclipse settings for 3.7 and m2e 1.0

  • Fix build in m2eclipse 1.0

    Ignore the antrun and the build-helper-maven-plugin tasks in m2eclipse.

  • Make Gerrit with gwt 2.3.0 run in gwtdebug mode

  • Fix a number of build warnings that have crept in

  • Accept email address automatically

    Enable Gerrit to accept email address automatically in "DEVELOPMENT_BECOME_ANY_ACCOUNT" mode without a confirmation email.

  • Added clickable user names at the BecomeAnyAccountLoginServlet.

    The first 5 (by accountId) user names are displayed as clickable links. Clicking a user name logs in as this user, speeding up switching between different users when using the DEVELOPMENT_BECOME_ANY_ACCOUNT authentication type.


  • Permit adding reviewers to closed changes

    Permit adding a reviewer to closed changes to support post-submit discussion threads.

  • issue 805 Don’t check for multiple change-ids when pushing directly to refs/heads.

  • Avoid costly findMergedInto during push to refs/for/*

    No longer close a change when a commit is pushed to res/for/* and the Change-Id in the commit message footer matches another commit on an existing branch or tag.

  • Allow serving static files in subdirectories

  • issue 1019 Normalize OpenID URLs with http:// prefix

    No longer violate OpenID 1.1 and 2.0, both of which require OpenIDs to be normalized (http:// added).

  • Allow container-based authentication for git over http

    Gerrit was insisting on DIGEST authentication when doing git over http. A new boolean configuration parameter auth.trustContainerAuth allows gerrit to be configured to trust the container to do the authentication.

  • issue 848 Add rpc method for GerritConfig

    Exposes what types of reviews are possible via json rpc, so that the Eclipse Reviews plugin currently can parse the javascript from a gerrit page load.


  • Bumped Brics version to 1.11.8

    This Brics version fixes a performance issue in some larger Gerrit systems.

  • Add permission_sort cache to remember sort orderings

    Cache the order AccessSections should be sorted in, making any future sorting for the same reference name and same set of section patterns cheaper.

  • Refactor how permissions are matched by ProjectControl, RefControl

    More aggressively cache many of the auth objects at a cost of memory, but this should be an improvement in response times.

  • Substantially speed up pushing changes for review

    Pushing a new change for review checks if the change is related to the branch it’s destined for. It used to do this in a way that required a topo-sort of the rev history, and now uses JGit’s merge-base functionality.

  • Add cache for tag advertisements

    To make the general case more efficient, introduce a cache called "git_tags".

    On a trivial usage of the Linux kernel repository, the average running time of the VisibleRefFilter when caches were hot was 7195.68 ms. With this commit, it is a mere 5.07 milliseconds on a hot cache. A reduction of 99% of the running time.

  • Don’t set lastCheckTime in ProjectState

    The lastCheckTime/generation fields are actually a counter that is incremented using a background thread. The values don’t match the system clock, and thus reading System.currentTimeMillis() during the construction of ProjectState is a waste of resources.


  • Upgrade to GWT 2.3.0

  • Upgrade to Gson to 1.7.1

  • Upgrade to gwtjsonrpc 1.2.4

  • Upgrade to gwtexpui 1.2.5

  • Upgrade to Jsch 0.1.44-1

  • Upgrade to Brics 1.11.8

Bug Fixes

  • Fix: Issue where Gerrit could not linkify certain URLs

  • issue 1015 Fix handling of regex ref patterns in Access panel

    regex patterns such as "^refs/heads/[A-Z]{2,}-[0-9]+.*" were being prefixed with "refs/heads/", resulting in invalid reference patterns like "refs/heads/^refs/heads/[A-Z]{2,}-[0-9]+.*".

  • issue 1002 Check for and disallow pushing of invalid refs/meta/config

    If the project.config or groups files are somehow invalid on the refs/meta/config branch, or would be made invalid due to a bad code review being submitted to this branch, reject the user’s attempt to push.

  • issue 1002 Fix NPE in PermissionRuleEditor when group lacks UUID

    If a group does not have an entry in the "groups" table within the refs/meta/config branch render the group name as a span, without the link instead of crashing the UI.

  • issue 972 Filter access section rules to only visible groups

    Users who are not the owner of an access section can now only see group names and rules for groups which they are a member of, are visible to all users, or that they own.

  • Correctly handle missing refs/meta/config branch

    If the refs/meta/config branch did not exist, getRevision() no longer throws an NPE when trying to access the ProjectDetail.

  • Allow loading Project Access when there is no refs/meta/config

    Enable loading the access screen with a null revision field, and on save of any edits require the branch to be new.

  • create-project: Fix creation vs. replication order

    Create the project on remote mirrors before creating either the refs/meta/config or the initial empty branch. This way those can be replicated to the remote mirrors once they have been created locally.

  • create-project: Bring back --permissions-only flag

    If a project is permissions only, assign HEAD to point to refs/meta/config. This way the gitweb view of the project shows the permissions history by default, and clients that clone the project are able to get a detached HEAD pointing to the current permission state, rather than an empty repository.

  • create-project: Fix error reporting when repository exists

    If a repository already exists, tell the user it already is available, without disclosing the server side path from gerrit.basePath.

  • Do not log timeout errors on upload and receive connections

  • Only automatically create accounts for LDAP systems

    If the account management is LDAP, try to automatically create accounts by looking up the data in LDAP. Otherwise fail and reject an invalid account reference that was supplied on the command line via SSH.

  • Add missing RevWalk.reset() after checking merge base

    This fixes an exception from RevWalk when trying to push a new commit for review.

  • issue 1069 Do not send an email on reviews when there is no message.

    No longer send an email when reviewing a change via ssh, and the change message is blank (when no change message is actually added to the review).

  • Ignore PartialResultException from LDAP.

    This exception occurs when the server isn’t following referrals for you, and thus the result contains a referral. That happens when you’re using Active Directory. You almost certainly don’t really want to follow referrals in AD anyways, so just ignore these exceptions, so we can still use the actual data.

  • issue 518 Fix MySQL counter resets

    gwtorm 1.1.5 was patched to leave in the dummy row that incremented the counter, ensuring the server will use MAX() + 1 instead of 1 on the next increment after restart.

  • Don’t delete account_id row on MySQL

    If the table is an InnoDB table deleting the row after allocation may cause the sequence to reset when the server restarts, giving out duplicate account_ids later.


New Documents

  • First Cut of Gerrit Walkthrough Introduction documentation.

    Add a new document intended to be a complement for the existing reference documentation to allow potential users to easily get a feel for how Gerrit is used, where it fits and whether it will work for them.

  • Introducing a quick and dirty setup tutorial

    The new document covers quick installation, new project and first upload. It contains lots of quoted output, with a demo style to it.

Access Control

  • Code review

  • Conversion table between 2.1 and 2.2

    Add a table to ease conversion from 2.1.x. The table tries to address the old permissions one by one except for the push tag permission which in effect needed two permissions to work properly. This should be familiar to the administrator used to the 2.1.x permission model however.

  • Reformatted text

  • Verify

    Updated some text in the Per project-section and edited the verified section to reflect the current label.

  • Capabilities

    Adds general information about global capabilities, how the server ownership is administered.

  • Added non-interactive users

    This change adds the non-interactive user group. It also adds that groups can be members of other groups. The groups are now sorted in alphabetical order.

  • Reordering categories

    Access categories are now sorted to match drop down box in UI

Other Documentation

  • Added additional information on the install instructions.

    The installation instructions presumes much prior knowledge, make some of that knowledge less implicit.

  • Provides a template to the download example.

    Clarifies that the example host must be replaced with proper hostname.

  • Provided an example on how to abandon a change from the command line

  • update links from to

  • Rename -- All Projects -- in documentation to All-Projects

  • Explain Automatically resolve conflicts

  • Update documentation for testing SSH connection

    The command output that is shown in the example and the description how to set the ssh username were outdated.

  • Remove unneeded escape characters from the documentation

    The old version of asciidoc required certain characters to be escaped with a backslash and when the upgrade to the new version was done all those backslashes that were used for escaping became visible.

  • Clean up pgm-index

    Break out the utilities into their own section, and correct some of the item descriptions.

  • Update manual project creation instructions

  • Update project configuration documentation

    Remove the textual reference to obsolete SQL insert statement to create new projects.

  • Clean up command line documentation, examples

    The formatting was pretty wrong after upgrading to a newer version of AsciiDoc, so fix up most of the formatting, correct some order of commands in the index, and make create-project conform to the same format used by create-account and create-group.

  • Correct syntax of SQL statement for inserting approval category