Getting the Source
Create a new client workspace:
git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
--recurse-submodules option is needed on
git clone to ensure that the
core plugins, which are included as git submodules, are also cloned.
Next setup the commit-hook. This is necessary to ensure that each commit has a
cd gerrit && ( cd .git/hooks ln -s ../../resources/com/google/gerrit/server/tools/root/hooks/commit-msg )
Switching between branches
git checkout without
--recurse-submodules to switch between
branches, submodule revisions are not altered, which can result in:
Incorrect or unneeded plugin revisions.
After you switch branches, ensure that you have the correct versions of the submodules.
If you store Eclipse or IntelliJ project files in the Gerrit source
directories, do not run
Run the following:
git submodule update git clean -ffd
For details, see Building with Bazel.
Running the acceptance tests
Gerrit contains acceptance tests that validate the Gerrit daemon via REST, SSH, and the Git protocol.
A new review site is created for each test and the Gerrit daemon is then started on that site. When the test is completed, the Gerrit daemon is shut down.
For instructions on running the acceptance tests with Bazel, see Running Unit Tests with Bazel.
This document describes how
e2e (load or functional) test
scenarios are implemented using
After you compile the project (above), run the Gerrit
command to create a test site:
export GERRIT_SITE=~/gerrit_testsite $(bazel info output_base)/external/local_jdk/bin/java \ -jar bazel-bin/gerrit.war init --batch --dev -d $GERRIT_SITE
You must use the same Java version that Bazel used for the build, which
is available at
This command takes two parameters:
--batchassigns default values to several Gerrit configuration options. To learn more about these options, see Configuration.
--devconfigures the Gerrit server to use the authentication option,
DEVELOPMENT_BECOME_ANY_ACCOUNT, which enables you to switch between different users to explore how Gerrit works. To learn more about setting up Gerrit for development, see Gerrit Code Review: Developer Setup.
After initializing the test site, Gerrit starts serving in the background. A web browser displays the Start page.
On the Start page, you can:
Log in as the account you created during the initialization process.
Register additional accounts.
To shut down the daemon, run:
Working with the Local Server
To create more accounts on your development instance:
Click 'become' in the upper right corner.
Select 'Switch User'.
Register a new account.
ssh protocol to clone from and push to the local server. For
example, to clone a repository that you’ve created through the admin
git clone ssh://username@localhost:29418/projectname
To use the
HTTP protocol, run:
git clone http://username@localhost:8080/projectname
The default password for user
secret. You can regenerate a
password in the UI under User Settings — HTTP credentials. The password can be
stored locally to avoid retyping it:
git config --global credential.helper store git pull
To create changes as users of Gerrit would, run:
git push origin HEAD:refs/for/master
Running the Daemon
The daemon can be launched directly from the build area, without copying to the test site:
$(bazel info output_base)/external/local_jdk/bin/java \ -jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE \ --console-log
To learn why using
When launching the daemon this way, the settings from the
To debug the Gerrit server of this test site:
Open a debug port (such as port 5005). To do so, insert the following code immediately after
-jarin the previous command. To learn how to attach IntelliJ, see Debugging a remote Gerrit server.
Running the Daemon honoring the [container] section settings
To run the Daemon and honor the
[container] section settings use the
$ cd $GERRIT_SITE $ bin/gerrit.sh run
To run the Daemon in debug mode use the
$ bin/gerrit.sh run --debug
The default debug port is
8000. To specify a different debug port use the
$ bin/gerrit.sh run --debug --debug-port=5005
--debug-address option also exists and is a synonym for the
$ bin/gerrit.sh run --debug --debug-address=5005
Note that, by default, the debugger will only accept connections from the localhost. To enable
debug connections from other host(s) provide also a host name or wildcard in the
$ bin/gerrit.sh run --debug --debug-address=*:5005
Debugging the Daemon startup requires starting the JVM in suspended debug mode. The JVM will await
for a debugger to attach before proceeding with the start. Use the
--suspend option for that
$ bin/gerrit.sh run --debug --suspend
Running the Daemon with Gerrit Inspector
Gerrit Inspector is an interactive scriptable environment you can use to inspect and modify the internal state of the system.
Gerrit Inspector appears on the system console whenever the system starts. Leaving the Inspector shuts down the Gerrit instance.
To troubleshoot, the Inspector enables interactive work as well as running of Python scripts.
To start the Inspector, add the '-s' option to the daemon start command:
$(bazel info output_base)/external/local_jdk/bin/java \ -jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE -s
To learn why using
Inspector examines Java libraries, loads the initialization scripts, and starts a command line prompt on the console:
Welcome to the Gerrit Inspector Enter help() to see the above again, EOF to quit and stop Gerrit Jython 2.5.2 (Release_2_5_2:7206, Mar 2 2011, 23:12:06) [OpenJDK 64-Bit Server VM (Sun Microsystems Inc.)] on java1.6.0 running for Gerrit 2.3-rc0-163-g01967ef >>>
When the Inspector is enabled, you can use Gerrit as usual and all interfaces (including HTTP and SSH) are available.
|When using the Inspector, be careful not to modify the internal state of the system.|
Setup for backend developers
To use the Eclipse IDE for development, see Eclipse Setup.
To configure the Eclipse workspace with Bazel, see Eclipse integration with Bazel.
Configuring IntelliJ IDEA
See IntelliJ Setup for details.
Setup for frontend developers
Part of Gerrit Code Review