Gerrit 2.6 is now available:

Gerrit 2.6 includes the bug fixes done with Gerrit 2.5.1, Gerrit 2.5.2, Gerrit 2.5.3, and Gerrit 2.5.4. These bug fixes are not listed in these release notes.

Schema Change

WARNING: This release contains schema changes. To upgrade:

  java -jar gerrit.war init -d site_path

WARNING: Upgrading to 2.6.x requires the server be first upgraded to 2.1.7 (or a later 2.1.x version), and then to 2.6.x. If you are upgrading from 2.2.x.x or newer, you may ignore this warning and upgrade directly to 2.6.x.

Reverse Proxy Configuration Changes

If you are running a reverse proxy in front of Gerrit (e.g. Apache or Nginx), make sure to check your configuration, especially if you are encountering Page Not Found errors when opening the change screen. See the Reverse Proxy Configuration for details.

Gerrit now requires passed URLs to be unchanged by the proxy.

Release Highlights

  • 42x improvement on git clone and git fetch

    Running gerrit gc allows JGit to optimize a repository to serve clone and fetch faster than C Git can, with massively lower server CPU required. Typically Gerrit 2.6 can completely transfer a project to a client faster than C Git can finish "Counting" the objects.

  • Completely customizable workflow

    Individual projects can add (or remove) score categories through labels and Prolog rules.

New Features

Web UI


  • New Login Screens

    New form based HTML screens for login allow browsers to offer the choice to save the login data locally in the user’s password store.

  • Rename "Groups" top-level menu to "People"

  • Move "Draft Comments" link next to "Drafts" link

  • Highlight the active menu item

  • Move user info, settings, and logout to popup dialog

  • Show a small version of the avatar image next to the user’s name.

  • Show avatar image in user info popup dialog

  • Always show Working … message

    The Working … message is relatively positioned from the top of the browser, so that the message is always visible, even if the user has scrolled down the page.

  • suggest.from configures a minimum number of characters before matches for reviewers, accounts, groups or projects are offered.

  • Make the default font size "small".

  • Mark all CSS classes as external so users can rely on them.

  • Add a link to the REST API documentation in the top menu.

  • Suggest projects, groups and users in search panel

    Suggest projects, groups and users in the search panel as parameter for those search operators that expect a project, group or user.

  • In search panel suggest self as value for operators that expect a user

  • Quote values suggested for search operators only if needed

    The values that are suggested for the search operators in the search panel are now only quoted if they contain a whitespace.

Change Screens

  • A change’s commit message can be edited from the change screen.

  • A change’s topic can be added, removed or changed from the change screen.

  • An "Add Comment" button is added to change screen

  • The reviewer matrix on a change displays gray boxes where permissions do not allow voting in that category.

    The coloring enables authors to quickly identify if another reviewer is necessary to continue the change.

  • Issue 353 & Issue 1123: New Rebase If Necessary submit type

    This is similar to cherry pick, but honors change dependency information.

  • The rebase button is hidden when the patch set is current.

  • Improved review message when a change is rebased in the UI

    When a change is rebased in the UI by pressing the rebase button, a comment is added onto the review. Instead of only saying Rebased the message is now more verbose, e.g. Patch Set 1 was rebased.

  • The submit type that is used for submitting a change is shown on the change screen in the info block.

    This is useful because the submit type of a change can now be controlled by Prolog.

  • Replace the All Diff buttons on the change screen with links

    The action buttons to open the diff for all files in own tabs consumed too much space due to the long label texts.

  • The patch set review screen can include radio buttons for custom labels if enabled by submit rules.

  • Voting on draft changes is now possible.

  • Recommend rebase on Path Conflict.

  • Issue 1685: After Up to change expand the patch set that was just reviewed

    After clicking on the Up to change link on a patch screen, the patch set that was just reviewed is automatically expanded on the change screen.

  • Allow direct change URLs to end with /.

  • Slightly increase commit message text size from 8px to 9px.

  • Issue 1381: Remove the ID column from change tables

    Users don’t really need the ID column present. For most changes the subject is descriptive and unique enough to identify the correct change.

  • Do not wrap project/branch/owner fields in change table.

    This makes it easier to use Gerrit on narrow screens.

  • Rename "Old Version History" to "Reference Version".

Patch Screens

  • Support for file comments

    It is now possible to comment on a whole file in a patch.

  • Have the reviewed panel also at the bottom of the patch screen

    Reviewers normally review patches top down, finishing the review when they reach the bottom of the patch. To use the streamlined review workflow they now don’t need to scroll back to the top to find the reviewed checkbox and link.

  • Issue 1494: Use mono-font for displaying the file contents

    This avoids alignment errors when syntax highlighting is enabled.

  • Distinguish between error and timeout in intraline diff error message.

  • Enable expanding skipped lines even if Syntax Coloring is off.

Project Screens

  • Support filtering of projects in the project list screen

    Filter matches are highlighted by bold printing.

    The filter is reflected by the filter URL parameter.

  • Support filtering of projects in ProjectListPopup

    Filter matches are highlighted by bold printing.

  • Display a query icon for each project in the project list screen that links to the default query/dashboard of that project.

  • Replace projects side menus with top menus

    The top menus are submenus to the Project Menu and they appear only when a project has been selected.

  • Remember the last Project Screen used

    Remember the last project screen used every time a project screen is loaded. Go to the remembered screen when selecting a new project from the project list instead of always going to the project info screen.

  • Remember the last project viewed

    Remember the last project viewed when navigating away from a project screen. If there is a remembered project, then the extra project links are not hidden.

  • Add clone panel to the project general screen

  • New screen for listing and accessing the project dashboards.

  • Issue 1677: Place the Browse button to select a watched project next to input field

  • Ask user to login if project is not found

    Accessing a project URL was failing with Not Found - The page you requested was not found, or you do not have permission to view this page if the user was not signed in and the project was not visible to Anonymous Users. Instead Gerrit now asks the user to login and afterwards shows the project to the user if it exists and is visible. If the project doesn’t exist or is not visible, the user will still get the Not Found screen after sign in.

  • Improve error handling on branch creation

    Improve the error messages that are displayed in the WebUI if the creation of a branch fails due to invalid user input.

Group Screens

  • Support filtering of groups in the group list screen

    Filter matches are highlighted by bold printing.

    The filter is reflected by the filter URL parameter.

  • Remove group type from group info screen

    The information about the group type was not much helpful. All groups that can be seen in Gerrit are of type INTERNAL, except a few well-known system groups which are of type SYSTEM. The system groups are so well-known that there is no need to display the type for them.

Dashboard Screens

  • Link dashboard title to a URL version of itself

    When using a stable project dashboard URL, the URL obfuscates the content of the dashboard which can make it hard to debug a dashboard or copy and modify it. In the special case of stable dashboards, make the title a link to an unstable URL version of the dashboard with the URL reflecting the actual dashboard contents the way a custom dashboard does.

  • Increase time span for "Recently Closed" section in user dashboard to 4 weeks.

Account Screens

  • Issue 1740: Display description how to generate SSH Key in SshPanel

    Display a description of how to generate an SSH Key in an expandable section in the SshPanel instead of linking to the GitHub SSH tutorial. The GitHub SSH tutorial was partially not relevant and confused users.

  • Make the text for "Register" customizable

Plugin Screens

  • Show status for enabled plugins in the WebUI as Enabled

    Earlier no status was shown for enabled plugins, which was confusing to some users.


  • A big chunk of the Gerrit functionality is now available via the REST API.

    The REST API is NOT complete yet and some functionality is still missing.

    To find out which functionality is available, check the REST endpoint documentation for projects, changes, groups and accounts.

  • Support setting HEAD of a project via REST.

  • Audit support for REST API.

    Allow generating Audit events related to REST API execution. The structure of the AuditEvent has been extended to support the new name-multivalue pairs used in the REST API.

    This is breaking compatibility with the 2.5 API as it changes the params data type, this is needed anyway as the previous list of Objects was not providing all the necessary information of "what relates to what" in terms of parameters info.

    Existing support for SSH and JSON-RPC events have been adapted in order to fit into the new name-multivalue syntax: this allow a generic audit plug-in to capture all parameters regardless of where they have been generated.

  • Remove support for deprecated --format option when listing changes

    Querying changes via REST is now always producing JSON output.

  • Introduce id property on REST entities

    The /changes/ entities now use id to include a triplet of the project, branch and change-id string to uniquely identify that change on the server. This moves the old id field to be named change_id, which is a breaking change.

  • Accept common forms of malformed JSON

    Some clients may send JSON-ish instead of JSON. Be nice to those clients and accept various useful forms of incorrect syntax:

    • End of line comments starting with // or # and ending with a newline character.

    • C-style comments starting with /* and ending with */ Such comments may not be nested.

    • Names that are unquoted or single quoted.

    • Strings that are unquoted or single quoted.

    • Array elements separated by ; instead of ,.

    • Unnecessary array separators. These are interpreted as if null was the omitted value.

    • Names and values separated by = or => instead of :.

    • Name/value pairs separated by ; instead of ,.

  • Be more liberal about parsing JSON responses

    If the response begins with the JSON magic string, remove it before parsing. If a response is missing this leading string, parse the response as-is.

  • Accept simple form encoded data for REST APIs

    Simple cases like /review or /abandon can now accept standard form values for basic properties, making it simple for tools to directly post data:

      curl -n --digest \
      --data 'message=Does not compile.' \
      --data labels.Verified=-1 \

    Form field names are JSON field names in the top level object. If dot appears in the name the part to the left is taken as the JSON field name and the part to the right as the key for a Map. This nicely fits with the labels structure used by /review, but doesn’t support the much more complex inline comment case. Clients that need to use more complex fields must use JSON formatting for the request body.

  • Allow administrators to see other user capabilities

    Expand /accounts/{id}/capabilities to permit an administrator to inspect another user’s effective capabilities.

  • Declare kind in JSON API results

    This is recommended to hint to clients what the entity type is when processing the JSON payload.

  • Format h/help output as plain text not JSON

    The output produced when the client requested the h or help property from a JSON API is always produced from constant compiled into the server. Assume this safe to return to the client as text/plain content and avoid wrapping it into an HTML escaped JSON string.

  • Use string for JSON encoded plain text replies

    Instead of wrapping the value into an object, just return the string by itself. This better matches what happens with the plain text return format.

  • Wrap possible HTML plain text in JSON on GET

    If the HTML appears like MSIE might guess it is HTML (such as if it contains <) encode the response as a JSON object instead of as a simple plain text string. This won’t show up very often for clients, and protects MSIE users stuck on ancient versions (pre MSIE 8).

  • Ask MSIE to never sniff content types on REST API responses

    Newer versions of MSIE can disable the content sniffing feature if the server asks it to by setting an extension header. It is annoying, but necessary, that a server needs to say "No really, I am telling you the right Content-Type, trust it."

    This feature was added in MSIE 8 Beta 2 so it doesn’t protect users running MSIE 6 or 7, but those are ancient and users should upgrade.

    Enable this on the REST API responses because we sometimes send back text/plain results that are really just plain text. Existing JSON responses are protected from accidental sniffing and treatment as HTML thanks to Gson encoding HTML control characters using Unicode character escapes within JSON strings.

Project Dashboards

  • Support for storing custom dashboards for projects

    Custom dashboards can now be stored in the projects refs/meta/dashboards/* branches.

    The project dashboards are shown in a new project screen and can be accessed via REST.

  • Allow defining a default dashboard for projects

  • Support inheritance for project dashboards.

    In dashboards queries the ${project} token can be used as placeholder for the project name. This token will be replaced with the project to which a dashboard is being applied.

  • On the project list screen a query icon is displayed for each project that links to the default dashboard of that project.

  • Support a foreach parameter for custom dashboards.

    The foreach parameter which will get appended to all the queries in the dashboard.

Access Controls

  • Allow to overrule BLOCK permissions on the same project

    It was impossible to block a permission for a group and allow the same permission for a sub-group of that group as the BLOCK permission always won over any ALLOW permission. For example, it was impossible to block the "Forge Committer" permission for all users and then allow it only for a couple of privileged users.

    An ALLOW permission has now priority over a BLOCK permission when they are defined in the same access section of a project. To achieve the above mentioned policy the following could be defined:

    [access "refs/heads/*"]
      forgeCommitter = block group Anonymous Users
      forgeCommitter = group Privileged Users

    Across projects the BLOCK permission still wins over any ALLOW permission. This way one cannot override an inherited BLOCK permission in a subproject.

    Overruling of BLOCK permissions with ALLOW permissions also works for labels i.e. permission ranges. If a dedicated Verifiers group need to be the only group who can vote in the Verified label and it must be ensured that even project owners cannot change this policy, then the following can be defined in a common parent project:

    [access "refs/heads/*"]
      label-Verified = block -1..+1 group Anonymous Users
      label-Verified = -1..+1 group Verifiers
  • issue 1516: Show global capabilities to all users that can read refs/meta/config

    Users can now propose changes to the global capabilities for review from the WebUI.

  • Remove Reviewer is a new permission.

  • Pushing a signed tag is a new permission.

  • Editing the topic name is a new permission.

  • Raw database access with the gsql command is a new global capability.

    Previously site administrators had this capability by default. Now it has to be explicitly assigned, even for site administrators.

  • Issue 1585: Viewing other users' draft changes is a new permission.

  • Issue 1675: Deleting and publishing other users' draft changes is a new permission.

  • Grant most permissions when creating All-Projects

    Make Gerrit more like a Git server out-of-the box by granting both Administrators and Project Owners permissions to review changes, submit them, create branches, create tags, and push directly to branches.

  • LDAP group names are configurable, cn is still the default.

  • Kerberos authentication to LDAP servers is now supported.

  • Basic project properties are now inherited by default from parent projects: Use Content Merge, Require Contributor Agreement, Require Change Id, Require Signed Off By.

  • Allow assigning Push for refs/meta/config on All-Projects

    The refs/meta/config branch of the All-Projects project should only be modified by Gerrit administrators because being able to do modifications on this branch means that the user could assign himself administrator permissions.

    In addition to being administrator Gerrit requires that the administrator has the Push access right for refs/meta/config in order to be able to modify it (just as with all other branches administrators do not have edit permissions by default).

    The problem was that assigning the Push access right for refs/meta/config on the All-Projects project was not allowed.

    Having the Push access right for refs/meta/config on the All-Projects project without being administrator has no effect.


  • Change topic is passed to hooks as --topic NAME.

  • Issue 1200: New reviewer-added hook and stream event when a reviewer is added.

  • Issue 1237: New merge-failed hook and stream event when a change cannot be submitted due to failed merge.

  • Issue 925: New ref-update hook run before a push is accepted by Gerrit.

  • Add --is-draft parameter to comment-added hook


  • Add options to refs/for/ magic branch syntax

    Git doesn’t want to modify the network protocol to support passing data from the git push client to the server. Work around this by embedding option data into a new style of reference specification:


    is now parsed by the server as:

    • set topic to "options"

    • CC charlie and bob

    • add reviewer alice

    • for branch refs/heads/master

    If % is used the extra information after the branch name is parsed as options with args4j. Each option is delimited by ,.

    Selecting publish vs. draft should be done with the options draft or publish, appearing anywhere in the refspec after the % marker:

  • Enable content merge by default

    Most teams seem to expect Gerrit to manage simple merges within a source code file. Enable this out-of-the-box.

  • Added a server-level option to use JGit’s new, experimental recursive merger.

  • Issue 1608: Commits pushed without a Change-Id now warn with instructions on how to download and install the commit-msg hook.

  • Add oldObjectId and newObjectId to the GitReferenceUpdatedListener.Update


  • New SSH command to run Git garbage collection

    All GC runs are logged in a GC log file.

  • Descriptions are added to ssh commands.

    If gerrit is called without arguments, it will now show a list of available commands with their descriptions.

  • create-account --http-password enables setting/resetting the HTTP password of role accounts, for Git or REST API access.

  • ls-user-refs lists which refs are visible for a given user.

  • ls-projects --has-acl-for lists projects that mention a group in an ACL, identifying where rights are granted.

  • review command supports project-specific labels

  • test-submit-rule was renamed to test-submit rule:

    rule is now a subcommand of the test-submit command.

  • test-submit type tests the Prolog submit type with a chosen change.


  • Allow {} to be used for quoting in query expressions

    This makes it a little easier to query for group names that contain a space over SSH:

    ssh srv gerrit query " 'status:open NOT reviewerin:{Developer Group}' "
  • The query summary block includes resumeSortKey.

  • Query results include author and change size information when certain options are specified.

  • When a file is renamed the old file name is included in the Patch attribute


  • Plugins can contribute Prolog facts/predicates from Java.

  • Plugins can prompt for parameters during init with InitStep.

  • Plugins can now contribute JavaScript to the web UI. UI plugins can also be written and compiled with GWT.

  • New Maven archetypes for JavaScript and GWT plugins.

  • Plugins can contribute validation steps to received commits.

  • Commit message length checks are moved to the commit-message-length-validator plugin which is included as a core plugin in the Gerrit distribution and can be installed during site initialization.

  • Creation of code review notes is moved to the reviewnotes plugin which is included as a core plugin in the Gerrit distribution and can be installed during site initialization.

  • A plugin extension point for avatar images was added.

  • Allow HTTP plugins to change static or docs prefixes

    An HTTP plugin may want more control over its URL space, but still delegate to the plugin servlet’s magic handling for static files and documentation. Add JAR attributes to configure these prefixes.


  • Support controlling the submit type for changes from Prolog

    Similarly like the submit_rule there is now a submit_type predicate which returns the allowed submit type for a change. When the submit_type predicate is not provided in the then the project default submit type is used for all changes of that project.

    Filtering the results of the submit_type is also supported in the same way like filtering the results of the submit_rule. Using a submit_type_filter predicate one can enforce a particular submit type from a parent project.

  • Plugins can contribute Prolog facts/predicates from Java.

  • Issue 288: Expose basic commit statistics for the Prolog rule engine

    A new method gerrit:commit_stats(-Files,-Insertions, -Deletions) was added.

  • A new max_with_block predicate was added for more convenient usage


  • Notify project watchers if draft change is published

  • Notify users mentioned in commit footer on draft publish

  • Add new notify type that allows watching of new patch sets

  • Issue 1686: Add new notify type that allows watching abandoning of changes

  • Notifications configured in project.config can now be addressed using any of To, CC, or BCC headers.

  • Issue 1531: Email footers now include Gerrit-HasComments: {Yes|No}.

  • #if($email.hasInlineComments()) can be used in templates to test if there are comments to be included in this email.

  • Notification emails are sent to included groups.

  • Comment notification emails are sent to project watchers.

  • "Change Merged" emails include the diff output when sendemail.includeDiff is enabled.

  • When posting a review via REST the caller can control email delivery

    This may help automated systems to be less noisy. Tools can now choose which review updates should send email, and which categories of users on a change should get that email.


  • Approval categories stored in the database have been replaced with labels configured in project.config. Existing categories are migrated to project.config in All-Projects as part of the schema upgrade; no user action is required.

  • Labels are no longer global; projects may define their own labels, with inheritance.

  • Don’t create Verify category by default

    Most project teams seem confused with the out-of-the-box experience needing to vote on both Code-Review and Verified categories in order to submit a change. Simplify the out-of-the-box workflow to only have Code-Review. When a team installs the Hudson/Jenkins integration or their own build system they can now trivially add the Verified category by pasting 5 lines into project.config.


  • Support loading debug JavaScript

  • Gerrit acceptance tests

    An infrastructure for testing the Gerrit daemon via REST and/or SSH protocols has been added. Gerrit daemon is run in the headless mode and in the same JVM where the tests run. Besides using REST/SSH, the tests can also access Gerrit server internals to prepare the test environment and to perform assertions.

    A new review site is created for each test and the Gerrit daemon is started on that site. When the test has finished the Gerrit daemon is shutdown.

  • Lightweight LDAP server for debugging

  • Add asciidoc checks in the documentation makefile

    Exit with error if the asciidoc executable is not available or has version lower than 8.6.3.

    The release script is aborted if asciidoc is missing.

  • Added sublime project files to .gitignore

  • Exclude all pom.xml files that are archetype resources in

  • Source files generated by Prolog are now correctly included in the Eclipse project.

  • Core plugins are now included as git submodules.

  • mvn package now generates the documentation by default.

    The documentation will always be generated unless -Dgerrit.documentation.skip is given on the command line.

  • mvn verify now runs acceptance tests by default.

    The acceptance profile is no longer used. Acceptance tests will always be run unless -Dgerrit.acceptance-tests.skip=True is given on the command line.

  • Vertically align the "Choose:" header on the Become Any Account page.

  • "Become Any Account" can be used for accounts whose full name is an empty string.


  • Bitmap Optimizations

    On running the garbage collection JGit creates bitmap data that is saved to an auxiliary file. The bitmap optimizations improve the clone and fetch performance. git-core will ignore the bitmap data.

  • Improve suggest user performance when adding a reviewer.

    Do not check the visibility of the change for each suggested account if the ref is visible by all registered users.

    On a system with about 2-3000 users, where most of the projects are visible by every registered user, this improves the performance of the suggesting reviewer by a factor of 1000 at least.

  • Cache RefControl.isVisible()

    For Git repositories with many changes the time for calculating visible refs is reduced by 30-50%.

  • Allow admins to disable magic ref check on upload

    Some sites manage to run their repositories in a way that prevents users from ever being able to create refs/for, refs/drafts or refs/publish names in a repository. Allow admins on those servers to disable this (somewhat) expensive check before every upload.

  • Permit ProjectCacheClock to be completely disabled

    Some admins may just want to require all updates to projects to be made through the web interface, and avoid the small expense of a background thread ticking off changes.

  • Batch read Change objects during query

  • Default core.streamFileThreshold to a larger value

    If this value is not configured by the server administrator performance on larger text files suffers considerably and Gerrit may grind to a halt and be unable to answer users.

    Default to either 25% of the available JVM heap or ~2048m.

  • Improve performance of ReceiveCommits for repositories with many refs

    Avoid adding refs/changes/ and refs/tags/ to RevWalk’s as uninteresting since JGit RevWalk doesn’t perform well when a large number of objects is marked as uninteresting.

  • PatchSet.isRef()-optimizations.

    PatchSet.isRef() is used extensively when preparing for a ref advertisement and the regular expression used by isRefs() was notably costly in these circumstances, especially since it could not be pre-compiled.

    The regular expression is removed and the check is now directly implemented. As result the performance of git ls-remote could be increased by up to 15%.

  • New config option receive.checkReferencedObjectsAreReachable

    If set to true, Gerrit will validate that all referenced objects that are not included in the received pack are reachable by the user.

    Carrying out this check on Git repositories with many refs and commits can be a very CPU-heavy operation. For non public Gerrit servers it may make sense to disable this check, which is now possible.

  • Cache config value in LdapAuthBackend

  • Perform a single /accounts/self/capabilities on page load

    This joins up 3 requests into a single call, which should speed up initial page load for most users.

  • Only gzip compress responses that are smaller compressed

  • Caching of changes

    During Ref Advertisements (via VisibleRefFilter), all changes need to be fetched from the database to allow Gerrit to figure out which change refs are visible and should be advertised to the user. To reduce database traffic a cache for changes was introduced. This cache is disabled by default since it can mess up multi-server setups.


  • Add config parameter to make new groups by default visible to all

    Add a new Gerrit configuration parameter that controls whether newly created groups should be by default visible to all registered users.

  • Support for OpenID domain filtering

    Added the ability to only allow email addresses under specific domains to be used for OpenID login.

    The allowed domains can be configured by setting auth.openIdDomain in the Gerrit configuration.

  • Always configure gerrit.canonicalWebUrl on init

    Gerrit has been requiring this field for several versions now, but init did not configure it. Ensure there is a value set so the server is not confused at runtime.

  • Add submodule subscriptions fetching by projects

    While submodule subscriptions can be fetched by branch, some plugins (e.g.: delete-project) would rather need to access all submodule subscriptions of a project (regardless of the branch). Instead of iterating over all branches of a project, and fetching the subscription for each branch separately, we allow fetching of subscriptions directly by projects.

  • Issue 1805: Make client SSL certificates that contain an email address work

    Authentication with CLIENT_SSL_CERT_LDAP didn’t work if the certificate contained email address.

  • Guess LDAP type of Active Directory LDS as ActiveDirectory

    If Gerrit connects to an AD LDS [1] server it will guess its type as RCF_2307 instead of ActiveDirectory. The reason is that an AD LDS doesn’t support the "1.2.840.113556.1.4.800" capability. However, AD LDS behaves like ActiveDirectory and Gerrit also needs to guess its type as ActiveDirectory to make the default query patterns work properly.

    Extend the LDAP server type guessing by checking for presence of the "1.2.840.113556.1.4.1851" capability which indicates that this LDAP server runs ActiveDirectory as AD LDS [2].

    Also remove the check for the presence of the "defaultNamingContext" attribute as we don’t use it anywhere and, by default, this attribute is not set on an AD LDS [3]

  • Allow group descriptions to supply email and URL

    Some backends have external management interfaces that are not embedded into Gerrit Code Review. Allow those backends to supply a URL to the web management interface for a group, so a user can manage their membership, view current members, or do whatever other features the group system might support.

    Some backends also have an email address associated with every group. Sending email to that address will distribute the message to the group’s members. Permit backends to supply an optional email address, and use this in the project level notification system if a group is selected as the target for a message.

  • Allow group backends to guess on relevant UUIDs

    Expose all cheaply known group UUIDs from the ProjectCache, enumerating groups used by access controls. This allows a backend that has a large number of groups to filter its getKnownGroups() output to only groups that may be relevant for this Gerrit server.

    The best use case to consider is an LDAP server at a large organization. A typical user may belong to 50 LDAP groups, but only 3 are relevant to this Gerrit server. Taking the intersection of the two groups limits the output Gerrit displays to users, or uses when considering same group visibility.

  • Add more forbidden characters for project names

    ?, %, *, :, <, >, |, $, \r are now forbidden in project names.

  • Make LSB compliant

  • Option to start headless Gerrit daemon

    Add --headless option to the Daemon which will start Gerrit daemon without the Web UI front end (headless mode).

    This may be useful for running Gerrit server with an alternative (rest based) UI or when starting Gerrit server for the purpose of automated REST/SSH based testing.

    Currently this option is only supported via the --headless option of the daemon program. We would need to introduce a config option in order to support this feature for deployed war mode.

  • Show path to gerrit.war in command for upgrade schema


  • Issue 1619: Embedded Jetty is now 8.1.7.v20120910.

  • ASM bytecode library is now 4.0.

  • JGit is now

  • asciidoc 8.6.3 is now required to build the documentation.

  • Issue 1155: prettify is now r225

  • The used GWT version is now 2.5.0

    Fixes some issues with IE9 and IE10.

Bug Fixes

Web UI

  • Issue 1662: Don’t show error on ACL modification if empty permissions are added

    This error message was incorrectly displayed if a permission without rules was added, although the save was actually successful.

  • Don’t show error on ACL modification if a section is added more than once

    This error message was incorrectly displayed if multiple sections for the same ref were added, although the save was actually successful.

  • Links to CGit were broken when remove-suffix was enabled.

  • Issue 926: Internet Explorer versions 9 and 10 are supported.

  • Issue 1664: Reverting a change did not preserve the change’s topic

  • Fix: User could get around restrictions by reverting a commit

    The Gerrit server may enforce several restrictions on the commit message (change-id required, signed-off-by, etc). A user was able to get around these restrictions by reverting a commit using the UI.

  • Issue 1518: Reset Old Version History if dependent change is opened

    Following the navigation link in the dependencies table on the change screen, the user can directly navigate to dependent changes. The value for Old Version History of the current change was incorrectly applied to the new change. If the value was invalid for the new change the Old Version History field became blank.

  • Issue 1736: Clear Old Version History ListBox before populating it

    The ListBox was not always cleared and as result the same entries were sometimes added multiple times e.g. after rebasing a change in the WebUI.

  • Issue 1673: Fix disappearance of patch headers when compared patches are identical

    When two patches were compared that were identical No Differences is displayed to the user. In this case the patch headers disappeared and as result the user couldn’t change the patch selection anymore.

  • Issue 1759: Fix ArrayIndexOutOfBoundsException on intraline diff

    In some cases displaying the intraline diff failed with an exception like this:

    java.lang.ArrayIndexOutOfBoundsException: Array index out of range: 10

    This happened when the old line was:


    and the new line was:

  • Prevent leading and trailing spaces on user’s Full Name

    Strip off the leading and trailing spaces from the Full Name that the user enters on the Contact Information form.

  • Issue 1480: Show proper error message if registering email address fails

  • Issue 816: Due to issues with the diff_intraline cache the file indention in the Side-By-Side diff was sometimes wrong.

  • Make rebase failed and merge failed messages consistent

  • Select Projects menu on loading of a project screen

    If in the top level menu All is selected and the user navigates to a change and then from the change to the project by clicking on the project link in the ChangeInfoBlock, the project screen is loaded but the Projects menu was not selected.

  • Fix display issues for inline comments and inline comment editors

    • Sometimes a second comment editor was shown instead of using the existing comment editor.

    • Fix duplicated border line between comments.

    • Sometimes the parts of the border were missing when a comment was expanded.

    • Fix displaying the blue line that marks the current line when there are several published comments.

    • Sometimes on discard of a comment some frames of the comment editor stayed and some border lines of neighbor comments disappeared.

  • In diff view don’t let arrow column accept clicks.

  • Fix display of commit message

    If there are no HTML tags in the text, just break on lines.

  • Upon selection in AddMemberBox, focus the box’s text field

    In the change screen, after clicking on an element of the Add Reviewer suggestion list, users expect to be able to add the reviewer by hitting enter. This did not work in Firefox.

  • Fix enter key detection in project creation screen

    The enter key detection was not working in all browsers (e.g. Firefox).

  • Display a tooltip for all tiny icons and ensure that the cursor is shown as pointer when hovering over them.

  • Clean query string when switching pages

    If we load a page without a query string, such as Projects→List, My→Changes, or Settings, it might be confusing to show the old query string from the previous page. The query string is now cleared out when switching pages, leaving the help text visible.

  • Fix highlighting in search suggestions

    The provided suggestions should highlight the part that the user has already typed as bold text. This only worked for the first operator. For suggestions of any further operator no highlighting was done.

  • Fix style of hint text in search box on initial page load

    The hint text should be a light gray on the white background, but was coming up black on initial page load due to a style setup ordering issue between the SearchPanel and the HintTextBox.

  • Issue 1661: Update links to Change-Id and Signed-off-by documentation on project info screen

  • Use href="javascript;" for All {Side-by-Side,Unified} links

    These links shouldn’t have an anchor location. There is nothing for the browser to remember or visit if it were opened in a new tab for example.

  • Improve message for unsatisfiable dependencies

    If a change cannot be merged due to unsatisfiable dependencies a comment is added to the change that lists the missing commits and says that a rebase is necessary.

    For each missing commit the comment said "Depends on patch set X of …, however the current patch set is Y."

    If multiple commits are missing it may be that for some commits the dependency is not outdated (X == Y). In this case the message was confusing.

    ", however the current patch set is Y." is now skipped if Y == X.

  • Issue 1843: Enable the "Create Project" and "Create Group" buttons when pasting the name into the text box.

  • Issue 1370: Fix PatchScreen leak when moving between files.

  • Prevent account’s full name from being set to empty string. Set it to null instead.

  • Issue 1682: Correctly handle paths with URL-escaped characters

    URL-unescape the path portion of a change history token to correctly handle paths with URL-escapable characters, i.e. +, ' ', etc.

  • Issue 1915: Don’t show non-visible drafts in the diff screens.

  • Issue 1801: Correctly keep patch set ordering after a new patch set is added via the Web UI.


  • Fix returning of Email Reviewers capability via REST

    The /accounts/self/capabilities/ didn’t return the Email Reviewers capability when it was not explicitly assigned, although by default everyone has the Email Reviewers capability.

    If Email Reviewers capability was allowed or denied, /accounts/self/capabilities/ returned the Email Reviewers capability always as true, which was wrong for the DENY case.

  • Provide a more descriptive error message for unauthenticated REST API access


  • The wildcard . is now permitted in reference regex rules.

  • Checking if a change is mergeable no longer writes to the repository.

  • Submitted but unmerged changes are periodically retried. This is necessary for a multi-master configuration where the second master may need to retry a change not yet merged by the first. Please note we still do not believe this is sufficient to enable multi-master.

  • Retry merge after LOCK_FAILURE when updating branch

    If the project requires fast-forwards, the merge cannot succeed once a lock failure occurs, but in other cases, it is safe to retry the merge immediately.

  • Do not automatically add reviewers from footer lines to draft patch sets

    Gerrit already avoids adding reviewers from footer lines when a new draft change is created. Now the same is done for draft patch sets.

  • Add users mentioned in commit footer as reviewers on draft publish

  • Hide any existing magic branches during push

    If there is a magic branch visible during push, just hide it from the client. Administrators can clear these by accessing the repository directly.

  • Prevent from deleting refs/changes/

    Everything under refs/changes/ should be protected by Gerrit, users shouldn’t be able to delete a particular patch set or a whole change from the review process.

  • Update description file in Git

    When writing the description to project.config, it is also necessary to write it to the description file in the repository so the same text is visible in CGit or GitWeb.

  • Write valid reflog for HEAD when creating the All-Projects project

    When the All-Projects project is created during the schema initialization, HEAD is set to point to the refs/meta/config branch. When HEAD is updated an entry into the reflog is written. This ref log entry should contain the ID of the initial commit as target, but instead the target was the zero ID.

  • Issue 1702: Fix: internal server error when pushing the same commit twice

    On the second push of the same commit to refs/for/<branch name>, Gerrit returns no new changes.

    However if the user pushed to refs/changes/<change id>, Gerrit returned internal server error.

  • Match all git fetch/clone/push commands to the command executor

    Route not just /p/ but any Git access to the same thread pool as the SSH server is using, allowing all requests to compete fairly for resources.

  • Fix auto closing of changes on direct push

    When a commit was directly pushed into a repository (bypassing code review) and this commit had a Change-Id in its commit message then the corresponding change was not automatically closed if it was open.

  • Set change state to NEW if merge fails due to non-existing dest branch

    If a submitted change failed to merge because the destination branch didn’t exist anymore, it stayed in state Submitted, Merge Pending. This meant Gerrit was re-attempting to merge this change (e.g. on startup), but this didn’t make sense. Either the branch did still not exist (then there was no need to try merging it) or a new branch with the old name was created (then it was questionable if the change should still be merged into this branch). This is why it’s better to set the change back to the Review in Progress state and update it with a message saying that it couldn’t be merged because the destination branch doesn’t exist anymore.

    In addition Gerrit was writing an error into the error log if a change couldn’t be merged because the destination branch was missing. That was not really a server error and is not logged anymore.

  • Fix NPE when pushing a patch with an invalid author with Forge Author permissions

  • Fix duplicated GitReferenceUpdated event on project creation.

    Creating a new Gerrit project was firing the GitReferenceUpdated event for the refs/meta/config branch two times.

  • Fix error log message in ReceiveCommits

    When the creation of one or more references failed ReceiveCommits failed with internal server error and wrote the following error log: "Only X of Y new change refs created in xxx; aborting" The printed value for Y could be wrong since it didn’t include the replaceCount. As a result, a confusing message like "Only 0 of 0 new change refs created in xxx; aborting" could appear in the error log.


  • review --restore allows a review score to be added on the restored change.

  • Issue 1721: review --message only adds the message once.

  • ls-groups prints "N/A" if the group’s name is not set.

  • set-project-parent --children-of: Fix getting parent for level 1 projects

    For direct child projects of the All-Projects project the name of the parent project was incorrectly retrieved if the parent name was not explicitly stored as All-Projects in the project.config file.

  • Fix NPE when abandoning change with invalid author

    If the author of a change isn’t known to Gerrit (pushed with Forge Author permissions), trying to abandon that change over SSH failed with an NPE.

  • Fix setting account’s full name via ssh.


  • Issue 1729: Fix query by label:Verified=0

  • Issue 1772: Set _more_changes if result is limited due to configured query limit

  • Fix query cost for "status:merged commit:c0ffee"


  • Skip disabled plugins on rescan

    In a background thread Gerrit periodically scans for new or changed plugins. On every such a rescan disabled plugins were loaded and a new copy of their jar files was stored in the review site’s tmp folder.

  • Fix cleanup of plugins from tmp folder on graceful Gerrit shutdown

    Loaded plugin jars are copied to the review site’s tmp folder to support hot updates of the plugin jars in the plugins folder. On Gerrit shutdown these copies of the jar files should be cleaned up. For this purpose a CleanupHandle is created, but the CleanupHandle wasn’t enqueued in the cleanupQueue which is why cleanup on Gerrit shutdown didn’t happen.

  • Reattempt deletion of plugin jars from tmp folder on JVM termination

    Loaded plugin jars are copied to the review site’s tmp folder to support hot updates of the plugin jars in the plugins folder. On Gerrit shutdown these copies of the jar files should be cleaned up. For this purpose a CleanupHandle is created. The deletion of the tmp file in the CleanupHandle can fail although the jar file was closed. In this case reattempt the deletion on termination of the virtual machine. This normally succeeds.

  • Fix unloading of plugins

    When two plugins, say pluginA, and pluginB had been loaded, and pluginA was removed from $sitePath/plugins, pluginA got stopped, and a cleaning run was ordered. But this cleaning run cleaned both plugins and both plugins had their jars removed. This left pluginB visible to Gerrit although it’s backing jar was gone. Upon calling not yet initialized parts of pluginB (e.g.: viewing not yet viewed Documentation pages of pluginB), exceptions as following were thrown:

      java.lang.IllegalStateException: zip file closed
  • Fix double bound exception when loading extensions

    ServerInformation class was already bound, therefore it shouldn’t be bound a second time for Gerrit extensions.

  • Do not call onModuleLoad() second time

    onModuleLoad() method is automatically called by GWT framework. Calling it once again in PluginGenerator caused double plugin initialization.

  • Require Administrate Server capability to GET /plugins/

    Listing plugins requires being an administrator. This was missed in the REST API.

  • Issue 1827: Allow InternalUser (aka plugins) to see any internal group, and run plugin startup and shutdown as PluginUser.


  • Merge failure emails are only sent once per day.

  • Unused macros are removed from the mail templates.

  • Unnecessary ellipses are no longer applied to email subjects.

  • The empty diff output from an "octopus merge" is now explained in change notification emails.

  • Issue 1480: Proper error message is shown when registering an email address fails.

  • Issue 1692: Review comments are sorted before being added to notification emails.

  • Fix watching of All Comments on All-Projects

    If a user is watching All Comments on All-Projects this should apply to all projects.


  • Provide more descriptive message for NoSuchProjectException

  • On internal error due to receive timeout include the value of receive.timeout into the log message

  • Silence INFO/DEBUG output from apache.http

    This spammed the log when using OpenID, for each and every login.

  • Remove mysql_nextval script

    This function does not work on binary logging enabled servers, as MySQL is unable to execute the function on slaves without causing possible corruption. Drop the function since it was only created to help administrators, and is unsafe.

  • Issue 1312: Fix relative URL detection in submodules

    Relative submodules do not start with /. Instead they start with ../. Fix the Submodule Subscriptions engine to recognize relative submodules.

  • Issue 1622: Fix NPE in LDAP Helper class if username is null

  • Fix commit-msg hook failure with spaces in path

    If the project absolute path had any whitespace, the commit hook failed to complete because a script variable was not enclosed in double quotes.

  • Drop the trailing ".git" suffix of the name of new project

  • Prevent possible NPE when running change-merged hook

    It’s possible that the submitter is null. Add a check for this before invoking the change-merged hook with it.

  • Keep change open if its commit is pushed to another branch.

  • Fire GitReferenceUpdated event when BanCommit updates the refs/meta/reject-commits branch.

  • Fix GitWeb Caching

    GitWeb Caching was not working when its cgi file was executed from outside. The same approach will also work with vanilla GitWeb.

  • Fix infinite loops when walking project hierarchy

  • Fix resource leak in MarkdownFormatter

  • Query all external groups for internal group memberships

    When asking for the known groups a user belongs to they may belong to an internal group by way of membership in a non-internal group, such as LDAP. Cache in memory the complete list of any non-internal group UUIDs used as members of an internal group. These must get checked for membership before completing the known group data from the internal backend.

  • Handle sorting groups with no name to avoid NPE


    • Don’t suggest site init if schema version is newer than expected

    • Improve error messages in schema check

    • Suggest changing gerrit.config when JDK not found

    • Explicitly set a shell

    • Determine GERRIT_SITE from current working directory.

    • Fix restart for relative paths

    • Fix site path computation if . occurs in path

    • Whitespace fixes

  • Display the reason of an Init injection failure.

  • Issue 1821: Warn if cache.web_sessions.maxAge is to small

    Setting maxAge to a small value can result in the browser endlessly redirecting trying to setup a new valid session. Warn administrators that the value is set smaller than 5 minutes.

  • Issue 1821: Support cache.web_sessions.maxAge < 1 minute

  • Use SECONDS as default time unit for cache.web_sessions.maxAge

    DefaultCacheFactory already uses SECONDS as default time unit for cache.*.maxAge.

    Update the described default time unit for cache.*.maxAge in the documentation.

    Administrators may need to update their configuration to for the new default time unit.

  • Add pylint configuration for contributed Python scripts

  • Various fixes and improvements of the contrib/ script

    • Adapt options to Gerrit 2.6

    • Use change-url flag for ChangeId

    • Prevent exception for empty commit

    • Fix pylint errors

    • Call gerrit review instead of gerrit approve

    • Make the private key argument optional

    • Support alternative ssh executable, for example plink

    • Support custom review labels

    • Correctly handle empty patch ID

      If only one of the patch IDs is empty, it should not be considered a trivial rebase.

    • Use plain python instead of python2.6

      Windows installation only has python.exe

  • Correct MIME type of favicon.ico reference

    This is not a GIF, it is an "MS Windows icon resource". Some browsers may skip the image if the type is wrong.

  • Use <link rel="shortcut icon"> for favicon.ico reference

    IE looks for a two-word "shortcut icon" relationship. Other browsers interpret this as two relationships, one of which is "icon", so they can handle this syntax as well.


  • Remove servlet-api from WAR/lib

    It is wrong to include the servlet API in a WAR’s WEB-INF/lib directory. This confuses some servlet containers who refuse to load the Gerrit WAR. Instead package the Jetty runtime and the servlet API in a new WEB-INF/pgm-lib directory.

  • Issue 1822: Verify session matches container authentication header

    If the user alters their identity in the container invalidate the Gerrit user session and force a new one to begin.

  • Issue 1743: Move RPC auth token from Authorization header to X-Gerrit-Auth

    Servers that run with auth.type = HTTP or HTTP_LDAP are unable to use the web UI because the Authorization code supplied by the UI overrides the browser’s native Authorization header and causes the request to be blocked at the HTTP reverse proxy, before Gerrit even sees the request.

    Instead insert a unique token into X-Gerrit-Auth, leaving the HTTP standard Authorization header unspecified and available for use in HTTP reverse proxies.


The documentation index is restructured to make it easier to use for different kinds of users.

User Documentation

Developer And Maintainer Documentation