opendev
/
gerrit
Code Issues Proposed changes

Use the new section title style in Asciidoctor. 

We previous use the section title style like:

Section level 1
===============

Section level 2
---------------

Which have a problem in Asciidoctor that the number of "="s or "-"s must match
the number of characters in the header exactly, as a result it's easy to make
mistakes while changing the titles. Asciidoctor provides a better style like:

= Section level 1

== Section level 2

So we switched to this style.

Also fixed a bug in replace_macros.py, which will not cause any problem in the
old style.

Change-Id: I811dd7238735d98f662767c17086152cd69aea02
This commit is contained in:
Yuxuan 'fishy' Wang 2013-12-20 12:55:51 -08:00
parent 9dc9639d30
commit 61698b14e0
131 changed files with 1330 additions and 2659 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
Documentation/access-control.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Access Controls
====================================
= Gerrit Code Review - Access Controls
Access controls in Gerrit are group based. Every user account is a
member of one or more groups, and access and privileges are granted
@ -7,8 +6,7 @@ to those groups. Access rights cannot be granted to individual
users.
System Groups
-------------
== System Groups
Gerrit comes with following system groups:
@ -26,8 +24,7 @@ if desired.
[[administrators]]
Administrators
~~~~~~~~~~~~~~
=== Administrators
This is the Gerrit "root" identity.
@ -45,8 +42,7 @@ other normal user would, without needing two different accounts.
[[anonymous_users]]
Anonymous Users
~~~~~~~~~~~~~~~
=== Anonymous Users
All users are automatically a member of this group. Users who are
not signed in are a member of only this group, and no others.
@ -61,8 +57,7 @@ identity for all other operations.
[[non-interactive_users]]
Non-Interactive Users
~~~~~~~~~~~~~~~~~~~~~
=== Non-Interactive Users
This is an internal user group, members of this group are not expected
to perform interactive operations on the Gerrit web front-end.
@ -77,8 +72,7 @@ resources are tight.
[[project_owners]]
Project Owners
~~~~~~~~~~~~~~
=== Project Owners
Access rights assigned to this group are always evaluated within the
context of a project to which the access rights apply. These rights
@ -95,8 +89,7 @@ newly created child projects.
[[change_owner]]
Change Owner
~~~~~~~~~~~~
=== Change Owner
Access rights assigned to this group are always evaluated within the
context of a change to which the access rights apply. These rights
@ -107,8 +100,7 @@ owner to vote on his change, but not actually cause it to become
approved or rejected.
[[registered_users]]
Registered Users
~~~~~~~~~~~~~~~~
=== Registered Users
All signed-in users are automatically a member of this group (and
also <<anonymous_users,'Anonymous Users'>>, see above).
@ -127,8 +119,7 @@ Registered users are always permitted to make and publish comments
on any change in any project they have `Read` access to.
Account Groups
--------------
== Account Groups
Account groups contain a list of zero or more user account members,
added individually by a group owner. Any user account listed as
@ -162,8 +153,7 @@ members of `Foo` have submit rights on a project, and the members of
[[ldap_groups]]
LDAP Groups
-----------
== LDAP Groups
LDAP groups are Account Groups that are maintained inside of your
LDAP instance. If you are using LDAP to manage your groups they will
@ -173,8 +163,7 @@ Access Control for a project. For example "ldap/foo-project" will
add the LDAP "foo-project" group to the access list.
Project Access Control Lists
----------------------------
== Project Access Control Lists
A system wide access control list affecting all projects is stored in
project "`All-Projects`". This inheritance can be configured
@ -283,8 +272,7 @@ would be needed:
|==============================================================
OpenID Authentication
~~~~~~~~~~~~~~~~~~~~~
=== OpenID Authentication
If the Gerrit instance is configured to use OpenID authentication,
an account's effective group membership will be restricted to only
@ -293,8 +281,7 @@ of its OpenID identities match one or more of the patterns listed
in the `auth.trustedOpenID` list from `gerrit.config`.
All Projects
~~~~~~~~~~~~
=== All Projects
Any access right granted to a group within `All-Projects`
is automatically inherited by every other project in the same
@ -313,8 +300,7 @@ group gives nearly the same level of access as membership in
permissions for every managed project including global capabilities.
Per-Project
~~~~~~~~~~~
=== Per-Project
The per-project ACL is evaluated before the global `All-Projects` ACL,
permitting some limited override capability to project owners. This
@ -323,8 +309,7 @@ granting 'DENY' within a specific project to deny a group access.
[[references]]
Special and magic references
----------------------------
== Special and magic references
The reference namespaces used in git are generally two, one for branches and
one for tags:
@ -339,8 +324,7 @@ special meaning.
[[references_special]]
Special references
~~~~~~~~~~~~~~~~~~
=== Special references
The special references have content that's either generated by Gerrit or
contains important project configuration that Gerrit needs. When making
@ -348,8 +332,7 @@ changes to these references, Gerrit will take extra precautions to verify the
contents compatibility at upload time.
refs/changes/*
^^^^^^^^^^^^^^
==== refs/changes/*
Under this namespace each uploaded patch set for every change gets a static
reference in their git. The format is convenient but still intended to scale to
@ -365,8 +348,7 @@ need the change number and patch set number.
You can also find these static references linked on the page of each change.
refs/meta/config
^^^^^^^^^^^^^^^^
==== refs/meta/config
This is where the Gerrit configuration of each project resides. This
branch contains several files of importance: +project.config+, +groups+ and
@ -374,15 +356,13 @@ branch contains several files of importance: +project.config+, +groups+ and
review process.
refs/meta/dashboards/*
^^^^^^^^^^^^^^^^^^^^^^
==== refs/meta/dashboards/*
There's a dedicated page where you can read more about
link:user-dashboards.html[User Dashboards].
refs/notes/review
^^^^^^^^^^^^^^^^^
==== refs/notes/review
Autogenerated copy of review notes for all changes in the git. Each log entry
on the refs/notes/review branch also references the patch set on which the
@ -390,14 +370,12 @@ review is made. This functionality is provided by the review-notes plugin.
[[references_magic]]
Magic references
~~~~~~~~~~~~~~~~
=== Magic references
These are references with added functionality to them compared to a regular
git push operation.
refs/for/<branch ref>
^^^^^^^^^^^^^^^^^^^^^
==== refs/for/<branch ref>
Most prominent is the `refs/for/<branch ref>` reference which is the reference
upon which we build the code review intercept before submitting a commit to
@ -407,15 +385,13 @@ Further documentation on how to push can be found on the
link:user-upload.html#push_create[Upload changes] page.
refs/publish/*
^^^^^^^^^^^^^^
==== refs/publish/*
`refs/publish/*` is an alternative name to `refs/for/*` when pushing new changes
and patch sets.
refs/drafts/*
^^^^^^^^^^^^^
==== refs/drafts/*
Push to `refs/drafts/*` creates a change like push to `refs/for/*`, except the
resulting change remains hidden from public review. You then have the option
@ -425,8 +401,7 @@ draft patch sets of a change into public patch sets for review.
[[access_categories]]
Access Categories
-----------------
== Access Categories
Gerrit has several permission categories that can be granted to groups
within projects, enabling functionality for that group's members.
@ -434,8 +409,7 @@ within projects, enabling functionality for that group's members.
[[category_abandon]]
Abandon
~~~~~~~
=== Abandon
This category controls whether users are allowed to abandon changes
to projects in Gerrit. It can give permission to abandon a specific
@ -447,8 +421,7 @@ ref.
[[category_create]]
Create Reference
~~~~~~~~~~~~~~~~
=== Create Reference
The create reference category controls whether it is possible to
create new references, branches or tags. This implies that the
@ -482,8 +455,7 @@ stale branches.
[[category_forge_author]]
Forge Author
~~~~~~~~~~~~
=== Forge Author
Normally Gerrit requires the author and the committer identity
lines in a Git commit object (or tagger line in an annotated tag) to
@ -503,8 +475,7 @@ is required.
[[category_forge_committer]]
Forge Committer
~~~~~~~~~~~~~~~
=== Forge Committer
Normally Gerrit requires the author and the committer identity
lines in a Git commit object (or tagger line in an annotated tag) to
@ -518,8 +489,7 @@ required when mirroring commits from an upstream project repository.
[[category_forge_server]]
Forge Server
~~~~~~~~~~~~
=== Forge Server
Normally Gerrit requires the author and the committer identity
lines in a Git commit object (or tagger line in an annotated tag) to
@ -535,8 +505,7 @@ Review server.
[[category_owner]]
Owner
~~~~~
=== Owner
The `Owner` category controls which groups can modify the project's
configuration. Users who are members of an owner group can:
@ -559,8 +528,7 @@ out more about this role.
[[category_push]]
Push
~~~~
=== Push
This category controls how users are allowed to upload new commits
to projects in Gerrit. It can either give permission to push
@ -571,8 +539,7 @@ permission is granted to.
[[category_push_direct]]
Direct Push
^^^^^^^^^^^
==== Direct Push
Any existing branch can be fast-forwarded to a new commit.
Creation of new branches is controlled by the
@ -595,8 +562,7 @@ reviews should not grant this category.
[[category_push_review]]
Upload To Code Review
^^^^^^^^^^^^^^^^^^^^^
==== Upload To Code Review
The `Push` access right granted on the namespace
`refs/for/refs/heads/BRANCH` permits the user to upload a non-merge
@ -620,8 +586,7 @@ The force option has no function when granted to a branch in the
[[category_push_merge]]
Push Merge Commits
~~~~~~~~~~~~~~~~~~
=== Push Merge Commits
The `Push Merge Commit` access right permits the user to upload merge
commits. It's an add-on to the <<category_push,Push>> access right, and
@ -639,8 +604,7 @@ of merge commits.
[[category_push_annotated]]
Push Annotated Tag
~~~~~~~~~~~~~~~~~~
=== Push Annotated Tag
This category permits users to push an annotated tag object into the
project's repository. Typically this would be done with a command line
@ -680,8 +644,7 @@ requires the same permission as deleting a branch.
[[category_push_signed]]
Push Signed Tag
~~~~~~~~~~~~~~~
=== Push Signed Tag
This category permits users to push a PGP signed tag object into the
project's repository. Typically this would be done with a command
@ -702,8 +665,7 @@ Tags must be signed (created with `git tag -s`), should exist in the
[[category_read]]
Read
~~~~
=== Read
The `Read` category controls visibility to the project's
changes, comments, code diffs, and Git access over SSH or HTTP.
@ -734,8 +696,7 @@ is already restricted to the correct set of users.
[[category_rebase]]
Rebase
~~~~~~
=== Rebase
This category permits users to rebase changes via the web UI by pushing
the `Rebase Change` button.
@ -749,8 +710,7 @@ patch set.
[[category_remove_reviewer]]
Remove Reviewer
~~~~~~~~~~~~~~~
=== Remove Reviewer
This category permits users to remove other users from the list of
reviewers on a change.
@ -764,8 +724,7 @@ reviewer list on a change.
[[category_review_labels]]
Review Labels
~~~~~~~~~~~~~
=== Review Labels
For every configured label `My-Name` in the project, there is a
corresponding permission `label-My-Name` with a range corresponding to
@ -779,8 +738,7 @@ defined globally or on a per-project basis.
[[category_submit]]
Submit
~~~~~~
=== Submit
This category permits users to push the `Submit Patch Set n` button
on the web UI.
@ -799,8 +757,7 @@ the caller needs to have the Submit permission on `refs/for/<ref>`
[[category_view_drafts]]
View Drafts
~~~~~~~~~~~
=== View Drafts
This category permits users to view draft changes uploaded by other
users.
@ -811,8 +768,7 @@ assigned).
[[category_publish_drafts]]
Publish Drafts
~~~~~~~~~~~~~~
=== Publish Drafts
This category permits users to publish draft changes uploaded by other
users.
@ -822,8 +778,7 @@ the `Publish Drafts` access right assigned).
[[category_delete_drafts]]
Delete Drafts
~~~~~~~~~~~~~
=== Delete Drafts
This category permits users to delete draft changes uploaded by other
users.
@ -833,8 +788,7 @@ the `Delete Drafts` access right assigned).
[[category_edit_topic_name]]
Edit Topic Name
~~~~~~~~~~~~~~~
=== Edit Topic Name
This category permits users to edit the topic name of a change that
is uploaded for review.
@ -848,8 +802,7 @@ by the 'Force Edit' flag. If this flag is not set the topic can only be
edited on open changes.
Examples of typical roles in a project
--------------------------------------
== Examples of typical roles in a project
Below follows a set of typical roles on a server and which access
rights these roles typically should be granted. You may see them as
@ -858,8 +811,7 @@ brand new Gerrit instance.
[[examples_contributor]]
Contributor
~~~~~~~~~~~
=== Contributor
This is the typical user on a public server. They are able to read
your project and upload new changes to it. They are able to give
@ -874,8 +826,7 @@ Suggested access rights to grant:
[[examples_developer]]
Developer
~~~~~~~~~
=== Developer
This is the typical core developer on a public server. They are able
to read the project, upload changes to a branch. They are allowed to
@ -910,8 +861,7 @@ Optional access rights to grant:
[[examples_cisystem]]
CI system
~~~~~~~~~
=== CI system
A typical Continuous Integration system should be able to download new changes
to build and then leave a verdict somehow.
@ -959,8 +909,7 @@ Optional access rights to grant:
[[examples_integrator]]
Integrator
~~~~~~~~~~
=== Integrator
Integrators are like developers but with some additional rights granted due
to their administrative role in a project. They can upload or push any commit
@ -978,8 +927,7 @@ Suggested access rights to grant:
[[examples_project-owner]]
Project owner
~~~~~~~~~~~~~
=== Project owner
The project owner is almost like an integrator but with additional destructive
power in the form of being able to delete branches. Optionally these users
@ -1002,8 +950,7 @@ Optional access right to grant:
[[examples_administrator]]
Administrator
~~~~~~~~~~~~~
=== Administrator
The administrator role is the most powerful role known in the Gerrit universe.
This role may grant itself (or others) any access right, and it already has
@ -1019,8 +966,7 @@ Suggested access rights to grant:
* <<examples_project-owner,Project owner rights>>
Enforcing site wide access policies
-----------------------------------
== Enforcing site wide access policies
By granting the <<category_owner,`Owner`>> access right on the `refs/*` to a
group, Gerrit administrators can delegate the responsibility of maintaining
@ -1045,8 +991,7 @@ non-blocked rules as they wish. This gives best of both worlds:
[[block]]
'BLOCK' access rule
~~~~~~~~~~~~~~~~~~~
=== 'BLOCK' access rule
The 'BLOCK' rule blocks a permission globally. An inherited 'BLOCK' rule cannot
be overridden in the inheriting project. Any 'ALLOW' rule, from a different
@ -1072,8 +1017,7 @@ The interpretation of the 'min..max' range in case of a blocking rule is: block
every vote from '-INFINITE..min' and 'max..INFINITE'. For the example above it
means that the range '-1..+1' is not affected by this block.
'BLOCK' and 'ALLOW' rules in the same access section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== 'BLOCK' and 'ALLOW' rules in the same access section
When an access section of a project contains a 'BLOCK' and an 'ALLOW' rule for
the same permission then this 'ALLOW' rule overrides the 'BLOCK' rule:
@ -1093,13 +1037,11 @@ different access section of the same project or in any access section in an
inheriting project cannot override a 'BLOCK' rule.
Examples
~~~~~~~~
=== Examples
The following examples show some possible use cases for the 'BLOCK' rules.
Make sure no one can update or delete a tag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== Make sure no one can update or delete a tag
This requirement is quite common in a corporate deployment where
reproducibility of a build must be guaranteed. To achieve that we block 'push'
@ -1123,8 +1065,7 @@ owners>> are allowed to create tags, we would extend the example above:
====
Let only a dedicated group vote in a special category
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== Let only a dedicated group vote in a special category
Assume there is a more restrictive process for submitting changes in stable
release branches which is manifested as a new voting category
@ -1141,8 +1082,7 @@ category. In the "`All-Projects`" we define the following rules:
====
[[global_capabilities]]
Global Capabilities
-------------------
== Global Capabilities
The global capabilities control actions that the administrators of
the server can perform which usually affect the entire
@ -1162,15 +1102,13 @@ Below you find a list of capabilities available:
[[capability_accessDatabase]]
Access Database
~~~~~~~~~~~~~~~
=== Access Database
Allow users to access the database using the `gsql` command.
[[capability_administrateServer]]
Administrate Server
~~~~~~~~~~~~~~~~~~~
=== Administrate Server
This is in effect the owner and administrator role of the Gerrit
instance. Any members of a group granted this capability will be
@ -1179,8 +1117,7 @@ capabilities granted to them automatically.
[[capability_createAccount]]
Create Account
~~~~~~~~~~~~~~
=== Create Account
Allow link:cmd-create-account.html[account creation over the ssh prompt].
This capability allows the granted group members to create non-interactive
@ -1190,8 +1127,7 @@ link:access-control.html#non-interactive_users['Non-Interactive users'] group.
[[capability_createGroup]]
Create Group
~~~~~~~~~~~~
=== Create Group
Allow group creation. Groups are used to grant users access to different
actions in projects. This capability allows the granted group members to
@ -1199,8 +1135,7 @@ either link:cmd-create-group.html[create new groups via ssh] or via the web UI.
[[capability_createProject]]
Create Project
~~~~~~~~~~~~~~
=== Create Project
Allow project creation. This capability allows the granted group to
either link:cmd-create-project.html[create new git projects via ssh]
@ -1208,8 +1143,7 @@ or via the web UI.
[[capability_emailReviewers]]
Email Reviewers
~~~~~~~~~~~~~~~
=== Email Reviewers
Allow or deny sending email to change reviewers and watchers. This can be used
to deny build bots from emailing reviewers and people who watch the change.
@ -1219,8 +1153,7 @@ is to allow emailing, if no explicit rule is matched.
[[capability_flushCaches]]
Flush Caches
~~~~~~~~~~~~
=== Flush Caches
Allow the flushing of Gerrit's caches. This capability allows the granted
group to link:cmd-flush-caches.html[flush some or all Gerrit caches via ssh].
@ -1231,16 +1164,14 @@ you need the <<capability_viewCaches,view caches capability>>.
[[capability_generateHttpPassword]]
Generate HTTP Password
~~~~~~~~~~~~~~~~~~~~~~
=== Generate HTTP Password
Allow the user to generate HTTP passwords for other users. Typically this would
be assigned to a non-interactive users group.
[[capability_kill]]
Kill Task
~~~~~~~~~
=== Kill Task
Allow the operation of the link:cmd-kill.html[kill command over ssh]. The
kill command ends tasks that currently occupy the Gerrit server, usually
@ -1249,8 +1180,7 @@ receive-pack.
[[capability_priority]]
Priority
~~~~~~~~
=== Priority
This capability allows users to use
link:config-gerrit.html#sshd.batchThreads[the thread pool reserved] for
@ -1278,8 +1208,7 @@ regardless if they also have the 'BATCH' option or not, they are in the
[[capability_queryLimit]]
Query Limit
~~~~~~~~~~~
=== Query Limit
Allow site administrators to configure the query limit for users to
be above the default hard-coded value of 500. Administrators can add
@ -1294,8 +1223,7 @@ command, but also to the web UI results pagination size.
[[capability_runAs]]
Run As
~~~~~~
=== Run As
Allow users to impersonate any other user with the `X-Gerrit-RunAs`
HTTP header on REST API calls, or the link:cmd-suexec.html[suexec]
@ -1315,16 +1243,14 @@ be explicitly granted.
[[capability_runGC]]
Run Garbage Collection
~~~~~~~~~~~~~~~~~~~~~~
=== Run Garbage Collection
Allow users to run the Git garbage collection for the repositories of
all projects.
[[capability_streamEvents]]
Stream Events
~~~~~~~~~~~~~
=== Stream Events
Allow performing streaming of Gerrit events. This capability
allows the granted group to
@ -1332,8 +1258,7 @@ link:cmd-stream-events.html[stream Gerrit events via ssh].
[[capability_viewCaches]]
View Caches
~~~~~~~~~~~
=== View Caches
Allow querying for status of Gerrit's internal caches. This capability allows
the granted group to
@ -1341,8 +1266,7 @@ link:cmd-show-caches.html[look at some or all Gerrit caches via ssh].
[[capability_viewConnections]]
View Connections
~~~~~~~~~~~~~~~~
=== View Connections
Allow querying for status of Gerrit's current client connections. This
capability allows the granted group to
@ -1350,8 +1274,7 @@ link:cmd-show-connections.html[look at Gerrit's current connections via ssh].
[[capability_viewQueue]]
View Queue
~~~~~~~~~~
=== View Queue
Allow querying for status of Gerrit's internal task queue. This capability
allows the granted group to

24
Documentation/cmd-apropos.txt
View File

@ -1,34 +1,27 @@
gerrit apropos
==============
= gerrit apropos
NAME
----
== NAME
gerrit apropos - Search Gerrit documentation index
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit apropos'
<query>
--
DESCRIPTION
-----------
== DESCRIPTION
Queries the documentation index and returns results with the title and URL
from the matched documents.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
Note: this feature is only available if documentation index was built.
EXAMPLES
--------
== EXAMPLES
=====
$ ssh -p 29418 review.example.com gerrit apropos capabilities
@ -54,8 +47,7 @@ $ ssh -p 29418 review.example.com gerrit apropos capabilities
http://localhost:8080/Documentation/rest-api-access.html
=====
SEE ALSO
--------
== SEE ALSO
* link:access-control.html[Access Controls]

24
Documentation/cmd-ban-commit.txt
View File

@ -1,12 +1,9 @@
gerrit ban-commit
=================
= gerrit ban-commit
NAME
----
== NAME
gerrit ban-commit - Bans a commit from a project's repository.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit ban-commit'
[--reason <REASON>]
@ -14,8 +11,7 @@ SYNOPSIS
<COMMIT> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Marks a commit as banned for the specified repository. If a commit is
banned Gerrit rejects every push that includes this commit with
link:error-contains-banned-commit.html[contains banned commit ...].
@ -25,17 +21,14 @@ This command just marks the commit as banned, but it does not remove
the commit from the history of any central branch. This needs to be
done manually.
ACCESS
------
== ACCESS
Caller must be owner of the project or be a member of the privileged
'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<PROJECT>::
Required; name of the project for which the commit should be
banned.
@ -46,8 +39,7 @@ OPTIONS
--reason::
Reason for banning the commit.
EXAMPLES
--------
== EXAMPLES
Ban commit `421919d015c062fd28901fe144a78a555d0b5984` from project
`myproject`:

15
Documentation/cmd-cherry-pick.txt
View File

@ -1,20 +1,16 @@
gerrit-cherry-pick
==================
= gerrit-cherry-pick
NAME
----
== NAME
gerrit-cherry-pick - Download and cherry pick one or more changes
SYNOPSIS
--------
== SYNOPSIS
--
'gerrit-cherry-pick' <remote> <changeid>...
'gerrit-cherry-pick' --continue | --skip | --abort
'gerrit-cherry-pick' --close <remote>
--
DESCRIPTION
-----------
== DESCRIPTION
Downloads the listed changes specified on the command line and
proceeds to cherry-pick them (rewriting commit SHA-1s as it goes)
onto the current branch.
@ -32,8 +28,7 @@ existing changes post cherry-pick is better handled simply by
ensuring link:user-changeid.html[Change-Id lines] are present in
each commit message.
OBTAINING
---------
== OBTAINING
To obtain the 'gerrit-cherry-pick' script use scp, curl or wget to
copy it to your local system:

24
Documentation/cmd-create-account.txt
View File

@ -1,12 +1,9 @@
gerrit create-account
=====================
= gerrit create-account
NAME
----
== NAME
gerrit create-account - Create a new user account.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit create-account'
[--group <GROUP>]
@ -17,8 +14,7 @@ SYNOPSIS
<USERNAME>
--
DESCRIPTION
-----------
== DESCRIPTION
Creates a new internal-only user account.
If the account is created without an email address, it may only be
@ -33,18 +29,15 @@ If LDAP authentication is being used, the user account is created
without checking the LDAP directory. Consequently users can be
created in Gerrit that do not exist in the underlying LDAP directory.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_createAccount[the 'Create Account' global capability].
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<USERNAME>::
Required; SSH username of the user account.
@ -70,8 +63,7 @@ This most likely requires double quoting the value, for example
--http-password::
HTTP password for the user account.
EXAMPLES
--------
== EXAMPLES
Create a new batch/role access user account called `watcher` in
the 'Non-Interactive Users' group.

24
Documentation/cmd-create-branch.txt
View File

@ -1,12 +1,9 @@
gerrit create-branch
====================
= gerrit create-branch
NAME
----
== NAME
gerrit create-branch - Create a new branch
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit create-branch'
<PROJECT>
@ -14,24 +11,20 @@ SYNOPSIS
<REVISION>
--
DESCRIPTION
-----------
== DESCRIPTION
Creates a new branch for a project.
ACCESS
------
== ACCESS
Caller should have link:access-control.html#category_create[Create Reference]
permission on the project.
Administrators do not automatically have permission to create branches. It must
be granted via the Create Reference permission.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<PROJECT>::
Required; name of the project.
@ -41,8 +34,7 @@ OPTIONS
<REVISION>::
Required; base revision of the new branch.
EXAMPLES
--------
== EXAMPLES
Create a new branch called 'newbranch' from the 'master' branch of
the project 'myproject'.

24
Documentation/cmd-create-group.txt
View File

@ -1,12 +1,9 @@
gerrit create-group
===================
= gerrit create-group
NAME
----
== NAME
gerrit create-group - Create a new account group.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit create-group'
[--owner <GROUP> | -o <GROUP>]
@ -17,8 +14,7 @@ SYNOPSIS
<GROUP>
--
DESCRIPTION
-----------
== DESCRIPTION
Creates a new account group. The group creating user (the user that
fired the create-group command) is not automatically added to
the created group. In case the creating user wants to be a member of
@ -26,18 +22,15 @@ the group he/she must list itself in the --member option. This is
slightly different from Gerrit's Web UI where the creating user automatically
becomes a member of the newly created group.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_createGroup[the 'Create Group' global capability].
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<GROUP>::
Required; name of the new group.
@ -69,8 +62,7 @@ to the group.
--visible-to-all::
If specified, the group members will be visible to all users.
EXAMPLES
--------
== EXAMPLES
Create a new account group called `gerritdev` with two initial members
`developer1` and `developer2`. The group should be owned by itself:

30
Documentation/cmd-create-project.txt
View File

@ -1,12 +1,9 @@
gerrit create-project
=====================
= gerrit create-project
NAME
----
== NAME
gerrit create-project - Create a new hosted project
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit create-project'
[--owner <GROUP> ... | -o <GROUP> ...]
@ -25,8 +22,7 @@ SYNOPSIS
{ <NAME> | --name <NAME> }
--
DESCRIPTION
-----------
== DESCRIPTION
Creates a new bare Git repository under `gerrit.basePath`, using
the project name supplied. The newly created repository is empty
(has no commits), but is registered in the Gerrit database so that
@ -38,18 +34,15 @@ the configured remote systems over SSH and uses command line git
on the remote system to create the empty repository.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_createProject[the 'Create Project' global capability].
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<NAME>::
Required; name of the new project to create. If name ends
with `.git` the suffix will be automatically removed.
@ -160,8 +153,7 @@ Change Submit Actions].
Common unit suffixes of 'k', 'm', or 'g' are supported.
EXAMPLES
--------
== EXAMPLES
Create a new project called `tools/gerrit`:
====
@ -179,8 +171,7 @@ shell needs double quotes around the value to ensure the single quotes
are passed through SSH as-is to the remote Gerrit server, which uses
the single quotes to delimit the value.
REPLICATION
-----------
== REPLICATION
If the replication plugin is installed, the plugin will attempt to
perform remote repository creation by a Bourne shell script:
@ -197,8 +188,7 @@ A custom extension or plugin may also be developed to implement the
NewProjectCreatedListener extension point and handle custom logic
for remote repository creation.
SEE ALSO
--------
== SEE ALSO
* link:project-setup.html[Project Setup]

27
Documentation/cmd-flush-caches.txt
View File

@ -1,20 +1,16 @@
gerrit flush-caches
===================
= gerrit flush-caches
NAME
----
== NAME
gerrit flush-caches - Flush some/all server caches from memory
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit flush-caches' --all
'ssh' -p <port> <host> 'gerrit flush-caches' --list
'ssh' -p <port> <host> 'gerrit flush-caches' --cache <NAME> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Clear an in-memory cache, forcing Gerrit to reconsult the ground
truth when it needs the information again.
@ -24,18 +20,15 @@ the Gerrit web interface.
If no options are supplied, defaults to `--all`.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or in a group that have been granted
link:access-control.html#capability_flushCaches[the 'Flush Caches' global capability].
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
--all::
Flush all known caches. This is like applying a big hammer,
it will force everything out, potentially more than was
@ -53,8 +46,7 @@ OPTIONS
than once to flush multiple caches in a single command
execution.
EXAMPLES
--------
== EXAMPLES
List caches available for flushing:
====
@ -95,8 +87,7 @@ Flush "web_sessions", forcing all users to sign-in again:
$ ssh -p 29418 review.example.com gerrit flush-caches --cache web_sessions
====
SEE ALSO
--------
== SEE ALSO
* link:cmd-show-caches.html[gerrit show-caches]
* link:config-gerrit.html#cache[Cache Configuration]

24
Documentation/cmd-gc.txt
View File

@ -1,12 +1,9 @@
gerrit gc
=========
= gerrit gc
NAME
----
== NAME
gerrit gc - Run the Git garbage collection
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit gc'
[--all]
@ -14,8 +11,7 @@ SYNOPSIS
<NAME> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Runs the Git garbage collection for the specified projects.
A Gerrit system administrator can define the default parameters that
@ -28,19 +24,16 @@ configuration on repository level it is possible to specify
repository specific parameters for the garbage collection in the Git
repository configuration of every project.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted the
link:access-control.html#capability_runGC[Run Garbage Collection]
global capability.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<NAME>::
Name of the projects for which the Git garbage collection should be run.
@ -51,8 +44,7 @@ OPTIONS
--show-progress::
If specified progress information is shown.
EXAMPLES
--------
== EXAMPLES
Run the Git garbage collection for the projects 'myProject' and
'yourProject':

24
Documentation/cmd-gsql.txt
View File

@ -1,26 +1,21 @@
gerrit gsql
===========
= gerrit gsql
NAME
----
== NAME
gerrit gsql - Administrative interface to active database
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit gsql'
[--format {PRETTY | JSON | JSON_SINGLE}]
[-c QUERY]
--
DESCRIPTION
-----------
== DESCRIPTION
Provides interactive query support directly against the underlying
SQL database used by the host Gerrit server. All SQL statements
are supported, including SELECT, UPDATE, INSERT, DELETE and ALTER.
OPTIONS
-------
== OPTIONS
--format::
Set the format records are output in. In PRETTY (the
default) records are displayed in a tabular output suitable
@ -33,19 +28,16 @@ OPTIONS
-c::
Execute the single query statement supplied, and then exit.
ACCESS
------
== ACCESS
Caller must have been granted the
link:access-control.html#capability_accessDatabase[Access Database]
global capability.
SCRIPTING
---------
== SCRIPTING
Intended for interactive use only, unless format is JSON, or
JSON_SINGLE.
EXAMPLES
--------
== EXAMPLES
To manually correct a user's SSH user name:
====

18
Documentation/cmd-hook-commit-msg.txt
View File

@ -1,15 +1,12 @@
commit-msg Hook
===============
= commit-msg Hook
NAME
----
== NAME
commit-msg - Edit commit messages to insert a `Change-Id` tag.
DESCRIPTION
-----------
== DESCRIPTION
A Git hook automatically invoked by `git commit`, and most other
@ -58,8 +55,7 @@ change viewed on the web.
The `Change-Id` will not be added if `gerrit.createChangeId` is set
to `false` in the git config.
OBTAINING
---------
== OBTAINING
To obtain the `commit-msg` script use `scp`, `wget` or `curl` to download
@ -88,16 +84,14 @@ Make sure the hook file is executable:
$ chmod u+x ~/duhproject/.git/hooks/commit-msg
====
SEE ALSO
--------
== SEE ALSO
* link:user-changeid.html[Change-Id Lines]
* link:http://www.kernel.org/pub/software/scm/git/docs/git-commit.html[git-commit(1)]
* link:http://www.kernel.org/pub/software/scm/git/docs/githooks.html[githooks(5)]
IMPLEMENTATION
--------------
== IMPLEMENTATION
The hook generates unique `Change-Id` lines by creating a virtual

18
Documentation/cmd-index.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review - Command Line Tools
=======================================
= Gerrit Code Review - Command Line Tools
Client
------
== Client
Client commands and hooks can be downloaded via scp, wget or curl
from Gerrit's daemon, and then executed on the client system.
@ -18,14 +16,12 @@ To download a client command or hook, use scp or an http client:
For more details on how to determine the correct SSH port number,
see link:user-upload.html#test_ssh[Testing Your SSH Connection].
[[client_commands]]Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== [[client_commands]]Commands
link:cmd-cherry-pick.html[gerrit-cherry-pick]::
Download and cherry-pick one or more changes (commits).
[[client_hooks]]Hooks
~~~~~~~~~~~~~~~~~~~~~
=== [[client_hooks]]Hooks
Client hooks can be installed into a local Git repository, improving
the developer experience when working with a Gerrit Code Review
@ -35,8 +31,7 @@ link:cmd-hook-commit-msg.html[commit-msg]::
Automatically generate `Change-Id: ` tags in commit messages.
Server
------
== Server
Aside from the standard Git server side actions, Gerrit supports
several other commands over its internal SSH daemon. As Gerrit does
@ -48,8 +43,7 @@ from an ssh client, for example:
For more details on how to determine the correct SSH port number,
see link:user-upload.html#test_ssh[Testing Your SSH Connection].
[[user_commands]]User Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== [[user_commands]]User Commands
link:cmd-apropos.html[gerrit apropos]::
Search Gerrit documentation index.

18
Documentation/cmd-kill.txt
View File

@ -1,29 +1,23 @@
kill
====
= kill
NAME
----
== NAME
kill - Cancel or abort a background task
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'kill' <ID> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Cancels a scheduled task from the queue. If the task has already
been started, requests for the task to cancel as soon as it reaches
its next cancellation point (which is usually blocking IO).
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted link:access-control.html#capability_kill[the 'Kill Task' global capability].
SCRIPTING
---------
== SCRIPTING
Intended for interactive use only.
GERRIT

24
Documentation/cmd-ls-groups.txt
View File

@ -1,12 +1,9 @@
gerrit ls-groups
================
= gerrit ls-groups
NAME
----
== NAME
gerrit ls-groups - List groups visible to caller
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit ls-groups'
[--project <NAME> | -p <NAME>]
@ -18,20 +15,17 @@ SYNOPSIS
[--verbose | -v]
--
DESCRIPTION
-----------
== DESCRIPTION
Displays the list of group names, one per line, that are visible to
the account of the calling user.
If the caller is a member of the privileged 'Administrators' group,
all groups are listed.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
All non-printable characters (ASCII value 31 or less) are escaped
@ -40,8 +34,7 @@ employing standard sequences like `\n` and `\t`, and `\xNN` for all
others. In shell scripts, the `printf` command can be used to unescape
the output.
OPTIONS
-------
== OPTIONS
--project::
-p::
Name of the project for which the groups should be listed. Only
@ -100,8 +93,7 @@ This option can't be used together with the '--project' option.
If a group has been "orphaned", i.e. its owner group UUID refers to a
nonexistent group, the owner group name field will read `n/a`.
EXAMPLES
--------
== EXAMPLES
List visible groups:
=====

21
Documentation/cmd-ls-members.txt
View File

@ -1,29 +1,24 @@
gerrit ls-members
================
NAME
----
== NAME
gerrit ls-members - Show members of a given group
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit ls-members GROUPNAME'
[--recursive]
--
DESCRIPTION
-----------
== DESCRIPTION
Displays the members of the given group, one per line, so long as the given
group is visible to the user. The users' id, username, full name and email are
shown tab-separated.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts. Output is either an error
message or a heading followed by zero or more lines, one for each member of the
group. If any field is not set, or if the field is the user's full name and the
@ -35,15 +30,13 @@ employing standard sequences like `\n` and `\t`, and `\xNN` for all
others. In shell scripts, the `printf` command can be used to unescape
the output.
OPTIONS
-------
== OPTIONS
--recursive::
If a member of the group is itself a group, the sub-group's
members are included in the list. Otherwise members of any sub-group
are not shown and no indication is given that a sub-group is present
EXAMPLES
--------
== EXAMPLES
List members of the Administrators group:
=====

30
Documentation/cmd-ls-projects.txt
View File

@ -1,12 +1,9 @@
gerrit ls-projects
==================
= gerrit ls-projects
NAME
----
== NAME
gerrit ls-projects - List projects visible to caller
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit ls-projects'
[--show-branch <BRANCH> ...]
@ -19,24 +16,20 @@ SYNOPSIS
[--has-acl-for GROUP]
--
DESCRIPTION
-----------
== DESCRIPTION
Displays the list of project names, one per line, that the
calling user account has been granted 'READ' access to.
If the caller is a member of the privileged 'Administrators'
group, all projects are listed.
ACCESS
------
== ACCESS
Any user who has configured an SSH key, or by an user over HTTP.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
--show-branch::
-b::
Branch for which the command will display the sha of each project.
@ -100,8 +93,7 @@ used to unescape the output.
+
With this option you can find out on which projects a group is used.
HTTP
----
== HTTP
This command is also available over HTTP, as `/projects/` for
anonymous access and `/a/projects/` for authenticated access.
Named options are available as query parameters. Results can
@ -118,8 +110,7 @@ to prevent a browser from executing the response in a script tag.
Output will be gzip compressed if `Accept-Encoding: gzip` was used
by the client in the request headers.
EXAMPLES
--------
== EXAMPLES
List visible projects:
=====
@ -147,8 +138,7 @@ Clone any project visible to the user:
done
====
SEE ALSO
--------
== SEE ALSO
* link:access-control.html[Access Controls]

21
Documentation/cmd-ls-user-refs.txt
View File

@ -1,12 +1,9 @@
gerrit ls-user-refs
===================
= gerrit ls-user-refs
NAME
----
== NAME
gerrit ls-user-refs - List refs visible to a specific user
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit ls-user-refs'
[--project PROJECT> | -p <PROJECT>]
@ -14,8 +11,7 @@ SYNOPSIS
[--only-refs-heads]
--
DESCRIPTION
-----------
== DESCRIPTION
Displays all refs that the specified user can see.
Allows an administrator to query which refs are visible for
@ -24,12 +20,10 @@ user cannot access certain refs and also to help admins
verify that certain secret refs are not exposed to the wrong
groups.
ACCESS
------
== ACCESS
Administrators
OPTIONS
-------
== OPTIONS
--project::
-p::
Required; Name of the project for which the refs should be listed.
@ -43,8 +37,7 @@ OPTIONS
--only-refs-heads::
Only list the refs found under refs/heads/*
EXAMPLES
--------
== EXAMPLES
List visible refs for the user "mr.developer" in project "gerrit"
=====

24
Documentation/cmd-plugin-enable.txt
View File

@ -1,39 +1,31 @@
plugin enable
=============
= plugin enable
NAME
----
== NAME
plugin enable - Enable plugins.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit plugin enable'
<NAME> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Enable plugins currently disabled. The plugins will be enabled by renaming
the plugin jars in the site path's `plugins` directory from
`<plugin-jar-name>.disabled` to `<plugin-jar-name>`.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<NAME>::
Name of the plugin that should be enabled. Multiple names of
plugins that should be enabled may be specified.
EXAMPLES
--------
== EXAMPLES
Enable a plugin:
====

24
Documentation/cmd-plugin-install.txt
View File

@ -1,35 +1,28 @@
plugin install
==============
= plugin install
NAME
----
== NAME
plugin install - Install/Add a plugin.
plugin add - Install/Add a plugin.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit plugin install | add'
[--name <NAME> | -n <NAME>]
- | <URL> | <PATH>
--
DESCRIPTION
-----------
== DESCRIPTION
Install/Add a plugin. The plugin will be copied into the site path's
`plugins` directory.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
-::
Plugin jar or js as piped input.
@ -46,8 +39,7 @@ OPTIONS
provides its own name in the MANIFEST file, then the plugin name from the
MANIFEST file has precedence over this option.
EXAMPLES
--------
== EXAMPLES
Install a plugin from an absolute file path on the server's host:
====

21
Documentation/cmd-plugin-ls.txt
View File

@ -1,32 +1,25 @@
plugin ls
=========
= plugin ls
NAME
----
== NAME
plugin ls - List the installed plugins.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit plugin ls'
[--all | -a]
[--format {text | json | json_compact}]
--
DESCRIPTION
-----------
== DESCRIPTION
List the installed plugins and show their version and status.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
--all::
-a::
List all plugins, including disabled plugins.

24
Documentation/cmd-plugin-reload.txt
View File

@ -1,19 +1,15 @@
plugin reload
=============
= plugin reload
NAME
----
== NAME
plugin reload - Reload/Restart plugins.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit plugin reload'
<NAME> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Reload/Restart plugins.
Whether a plugin is reloaded or restarted is defined by the plugin's
@ -22,22 +18,18 @@ link:dev-plugins.html#reload_method[reload method].
E.g. a plugin needs to be reloaded if its configuration is modified to
make the new configuration data become active.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<NAME>::
Name of the plugin that should be reloaded. Multiple names of
plugins that should be reloaded may be specified.
EXAMPLES
--------
== EXAMPLES
Reload a plugin:
====

24
Documentation/cmd-plugin-remove.txt
View File

@ -1,40 +1,32 @@
plugin remove
=============
= plugin remove
NAME
----
== NAME
plugin remove - Disable plugins.
plugin rm - Disable plugins.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit plugin remove | rm'
<NAME> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Disable plugins. The plugins will be disabled by renaming the plugin
jars in the site path's `plugins` directory to `<plugin-jar-name>.disabled`.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<NAME>::
Name of the plugin that should be disabled. Multiple names of
plugins that should be disabled may be specified.
EXAMPLES
--------
== EXAMPLES
Disable a plugin:
====

30
Documentation/cmd-query.txt
View File

@ -1,12 +1,9 @@
gerrit query
============
= gerrit query
NAME
----
== NAME
gerrit query - Query the change database
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit query'
[--format {TEXT | JSON}]
@ -24,8 +21,7 @@ SYNOPSIS
[resume_sortkey:<sortKey>]
--
DESCRIPTION
-----------
== DESCRIPTION
Queries the change database and returns results describing changes
that match the input query. More recently updated changes appear
@ -50,8 +46,7 @@ Query operators may quote values using matched curly braces
levels of shell quoting (caller shell invoking SSH, and the SSH
command line parser in the server).
OPTIONS
-------
== OPTIONS
--format::
Formatting method for the results. `TEXT` is the default,
presenting a human readable display. `JSON` returns
@ -112,16 +107,13 @@ resume_sortkey:<sortKey>::
resume a prior query. This is actually a query operator,
and not a command line option.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
Find the 2 most recent open changes in the tools/gerrit project:
====
@ -140,8 +132,7 @@ Resume the same query and obtain the final results:
====
SCHEMA
------
== SCHEMA
The JSON messages consist of nested objects referencing the
link:json.html#change[change],
link:json.html#patchSet[patchset],
@ -151,8 +142,7 @@ involved, and other attributes as appropriate.
Note that any field may be missing in the JSON messages, so consumers
of this JSON stream should deal with that appropriately.
SEE ALSO
--------
== SEE ALSO
* link:user-search.html[Query Operators]
* link:json.html[JSON Data Formats]

24
Documentation/cmd-receive-pack.txt
View File

@ -1,12 +1,9 @@
git-receive-pack
================
= git-receive-pack
NAME
----
== NAME
git-receive-pack - Receive what is pushed into the repository
SYNOPSIS
--------
== SYNOPSIS
--
'git receive-pack'
[--reviewer <address> | --re <address>]
@ -14,16 +11,14 @@ SYNOPSIS
<project>
--
DESCRIPTION
-----------
== DESCRIPTION
Invoked by 'git push' and updates the project's repository with
the information fed from the 'git push' end.
End users can supply options to this command by passing them through
to 'git push', which will relay them automatically.
OPTIONS
-------
== OPTIONS
<project>::
The remote repository that will receive the pushed objects,
@ -40,12 +35,10 @@ OPTIONS
Carbon-copy <address> on the created or updated changes.
Deprecated, use `refs/for/branch%cc=address` instead.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
EXAMPLES
--------
== EXAMPLES
Send a review for a change on the master branch to charlie@example.com:
=====
@ -81,8 +74,7 @@ alice and bob is much easier:
git push charlie
====
SEE ALSO
--------
== SEE ALSO
* link:user-upload.html[Uploading Changes]

24
Documentation/cmd-rename-group.txt
View File

@ -1,41 +1,33 @@
gerrit rename-group
===================
= gerrit rename-group
NAME
----
== NAME
gerrit rename-group - Rename an account group.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit rename-group'
<GROUP>
<NEWNAME>
--
DESCRIPTION
-----------
== DESCRIPTION
Renames an account group.
ACCESS
------
== ACCESS
Caller must be a member of the group owning the group to be renamed
or be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<GROUP>::
Required; name of the group to be renamed.
<NEWNAME>::
Required; new name of the group.
EXAMPLES
--------
== EXAMPLES
Rename the group "MyGroup" to "MyCommitters".
====

24
Documentation/cmd-review.txt
View File

@ -1,12 +1,10 @@
gerrit review
==============
NAME
----
== NAME
gerrit review - Verify, approve and/or submit one or more patch sets
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit review'
[--project <PROJECT> | -p <PROJECT>]
@ -22,8 +20,7 @@ SYNOPSIS
{COMMIT | CHANGEID,PATCHSET}...
--
DESCRIPTION
-----------
== DESCRIPTION
Updates the current user's approval status of the specified patch
sets and/or submits them for merging, sending out email
notifications and updating the database.
@ -40,8 +37,7 @@ may be used to limit where Gerrit searches for changes to only the specified
branch.
OPTIONS
-------
== OPTIONS
--project::
-p::
@ -113,16 +109,13 @@ OPTIONS
or invalid value) and votes that are not permitted for the user are
silently ignored.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
Approve the change with commit c0ff33 as "Verified +1"
=====
@ -157,8 +150,7 @@ Abandon an active change:
$ ssh -p 29418 review.example.com gerrit review --abandon c0ff33
====
SEE ALSO
--------
== SEE ALSO
* link:access-control.html[Access Controls]

24
Documentation/cmd-set-account.txt
View File

@ -1,12 +1,9 @@
gerrit set-account
==================
= gerrit set-account
NAME
----
== NAME
gerrit set-account - Change an account's settings.
SYNOPSIS
--------
== SYNOPSIS
--
set-account [--full-name <FULLNAME>] [--active|--inactive] \
[--add-email <EMAIL>] [--delete-email <EMAIL> | ALL] \
@ -15,8 +12,7 @@ set-account [--full-name <FULLNAME>] [--active|--inactive] \
[--http-password <PASSWORD>] <USER>
--
DESCRIPTION
-----------
== DESCRIPTION
Modifies a given user's settings. This command can be useful to
deactivate an account, set HTTP password, add/delete ssh keys without
going through the UI.
@ -24,16 +20,13 @@ going through the UI.
It also allows managing email addresses, which bypasses the
verification step we force within the UI.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<USER>::
Required; Full name, email-address, SSH username or account id.
@ -84,8 +77,7 @@ This most likely requires double quoting the value, for example
--http-password::
Set the HTTP password for the user account.
EXAMPLES
--------
== EXAMPLES
Add an email and SSH key to `watcher`'s account:
====

24
Documentation/cmd-set-members.txt
View File

@ -1,12 +1,9 @@
gerrit set-members
==================
= gerrit set-members
NAME
----
== NAME
gerrit set-members - Set group members
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit set-members'
[--add USER ...]
@ -17,12 +14,10 @@ SYNOPSIS
<GROUP> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Set the group members for the specified groups.
OPTIONS
-------
== OPTIONS
<GROUP>::
Required; name of the group for which the members should be set.
The members for multiple groups can be set at once by specifying
@ -52,16 +47,13 @@ OPTIONS
The `set-members` command is processing the options in the following
order: `--remove`, `--exclude`, `--add`, `--include`
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
Add alice and bob, but remove eve from the groups my-committers and
my-verifiers.

27
Documentation/cmd-set-project-parent.txt
View File

@ -1,12 +1,9 @@
gerrit set-project-parent
=========================
= gerrit set-project-parent
NAME
----
== NAME
gerrit set-project-parent - Change the project permissions are inherited from.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit set-project-parent'
[--parent <NAME>]
@ -15,23 +12,19 @@ SYNOPSIS
<NAME> ...
--
DESCRIPTION
-----------
== DESCRIPTION
Changes the project that permissions are inherited through.
Every project inherits permissions from another project, by
default this is `All-Projects`. This command sets
the project to inherit through another one.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
--parent::
Name of the parent to inherit through. If not specified,
the parent is set back to the default `All-Projects`.
@ -49,8 +42,7 @@ OPTIONS
specifying the --exclude option multiple times. Excluding a
project that is not a child project has no effect.
EXAMPLES
--------
== EXAMPLES
Configure `kernel/omap` to inherit permissions from `kernel/common`:
====
@ -64,8 +56,7 @@ Reparent all children of `myParent` to `myOtherParent`:
--children-of myParent --parent myOtherParent
====
SEE ALSO
--------
== SEE ALSO
* link:access-control.html[Access Controls]

24
Documentation/cmd-set-project.txt
View File

@ -1,12 +1,9 @@
gerrit set-project
==================
= gerrit set-project
NAME
----
== NAME
gerrit set-project - Change a project's settings.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit set-project'
[--description <DESC> | -d <DESC>]
@ -20,24 +17,20 @@ SYNOPSIS
<NAME>
--
DESCRIPTION
-----------
== DESCRIPTION
Modifies a given project's settings. This command can be useful to
batch change projects.
The command is argument-safe, that is, if no argument is given the
previous settings are kept intact.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
OPTIONS
-------
== OPTIONS
<NAME>::
Required; name of the project to edit. If name ends
with `.git` the suffix will be automatically removed.
@ -105,8 +98,7 @@ is granted, but all modification operations are disabled.
+
Common unit suffixes of 'k', 'm', or 'g' are supported.
EXAMPLES
--------
== EXAMPLES
Change project `example` to be hidden, require change id, don't use content merge
and use 'merge if necessary' as merge strategy:

24
Documentation/cmd-set-reviewers.txt
View File

@ -1,12 +1,9 @@
gerrit set-reviewers
====================
= gerrit set-reviewers
NAME
----
== NAME
gerrit set-reviewers - Add or remove reviewers to a change
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit set-reviewers'
[--project <PROJECT> | -p <PROJECT>]
@ -16,8 +13,7 @@ SYNOPSIS
{COMMIT | CHANGE-ID}...
--
DESCRIPTION
-----------
== DESCRIPTION
Adds or removes reviewers to the specified change, sending email
notifications when changes are made.
@ -26,8 +22,7 @@ such as 'Iac6b2ac2'. They may also be specified by numeric change
identifiers, such as '8242' or by complete or abbreviated commit
SHA-1s.
OPTIONS
-------
== OPTIONS
--project::
-p::
@ -51,16 +46,13 @@ OPTIONS
-h::
Display site-specific usage information
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
Add reviewers alice and bob, but remove eve from change Iac6b2ac2.
=====

24
Documentation/cmd-show-caches.txt
View File

@ -1,22 +1,18 @@
gerrit show-caches
===================
NAME
----
== NAME
gerrit show-caches - Display current cache statistics
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit show-caches' [--gc] [--show-jvm]
--
DESCRIPTION
-----------
== DESCRIPTION
Display statistics about the size and hit ratio of in-memory caches.
OPTIONS
-------
== OPTIONS
--gc::
Request Java garbage collection before displaying information
about the Java memory heap.
@ -30,18 +26,15 @@ OPTIONS
-w::
Width of the output table.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_viewCaches[the 'View Caches' global capability].
SCRIPTING
---------
== SCRIPTING
Intended for interactive use only.
EXAMPLES
--------
== EXAMPLES
====
$ ssh -p 29418 review.example.com gerrit show-caches
@ -74,8 +67,7 @@ EXAMPLES
0 open files, 6 cpus available, 23 threads
====
SEE ALSO
--------
== SEE ALSO
* link:cmd-flush-caches.html[gerrit flush-caches]
* link:config-gerrit.html#cache[Cache Configuration]

27
Documentation/cmd-show-connections.txt
View File

@ -1,34 +1,27 @@
gerrit show-connections
=======================
= gerrit show-connections
NAME
----
== NAME
gerrit show-connections - Display active client SSH connections
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit show-connections' [--numeric | -n]
--
DESCRIPTION
-----------
== DESCRIPTION
Presents a table of the active SSH connections, the users who
are currently connected to the internal server and performing
an activity.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_viewConnections[the 'View Connections' global capability].
SCRIPTING
---------
== SCRIPTING
Intended for interactive use only.
OPTIONS
-------
== OPTIONS
--numeric::
-n::
Show client hostnames as IP addresses instead of DNS hostname.
@ -38,8 +31,7 @@ OPTIONS
Do not format the output to the terminal width (default of
80 columns).
DISPLAY
-------
== DISPLAY
Session::
Unique session identifier on this server. Session
@ -65,8 +57,7 @@ Remote Host::
Reverse lookup hostname, or if -n option is used, the remote
IP address.
EXAMPLES
--------
== EXAMPLES
With reverse DNS lookup (default):
====

27
Documentation/cmd-show-queue.txt
View File

@ -1,19 +1,15 @@
gerrit show-queue
=================
= gerrit show-queue
NAME
----
== NAME
gerrit show-queue - Display the background work queues, including replication
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit show-queue'
'ssh' -p <port> <host> 'ps'
--
DESCRIPTION
-----------
== DESCRIPTION
Presents a table of the pending activity the Gerrit daemon
is currently performing, or will perform in the near future.
Gerrit contains an internal scheduler, similar to cron, that it
@ -23,8 +19,7 @@ Tasks that are completed or canceled exit the queue very quickly
once they enter this state, but it can be possible to observe tasks
in these states.
ACCESS
------
== ACCESS
End-users may see a task in the queue only if they can also see
the project the task is associated with. Tasks operating on other
projects, or that do not have a specific project are hidden.
@ -34,19 +29,16 @@ granted
link:access-control.html#capability_viewQueue[the 'View Queue' capability]
can see all queue entries.
SCRIPTING
---------
== SCRIPTING
Intended for interactive use only.
OPTIONS
-------
== OPTIONS
--wide::
-w::
Do not format the output to the terminal width (default of
80 columns).
DISPLAY
-------
== DISPLAY
Task::
Unique task identifier on this server. May be passed into
@ -71,8 +63,7 @@ Command::
Short text description of the task that will be performed
at the given time.
EXAMPLES
--------
== EXAMPLES
The following queue contains two tasks scheduled to replicate the
`tools/gerrit.git` project to two different remote systems, `dst1`

60
Documentation/cmd-stream-events.txt
View File

@ -1,18 +1,14 @@
gerrit stream-events
====================
= gerrit stream-events
NAME
----
== NAME
gerrit stream-events - Monitor events occurring in real time
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit stream-events'
--
DESCRIPTION
-----------
== DESCRIPTION
Provides a portal into the major events occurring on the server,
outputting activity data in real-time to the client. Events are
@ -22,18 +18,15 @@ the project repository.
Event output is in JSON, one event per line.
ACCESS
------
== ACCESS
Caller must be a member of the privileged 'Administrators' group,
or have been granted
link:access-control.html#capability_streamEvents[the 'Stream Events' global capability].
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
====
$ ssh -p 29418 review.example.com gerrit stream-events
@ -41,8 +34,7 @@ EXAMPLES
{"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
====
SCHEMA
------
== SCHEMA
The JSON messages consist of nested objects referencing the *change*,
*patchSet*, *account* involved, and other attributes as appropriate.
The currently supported message types are *patchset-created*,
@ -54,10 +46,8 @@ Note that any field may be missing in the JSON messages, so consumers of
this JSON stream should deal with that appropriately.
[[events]]
Events
~~~~~~
Patchset Created
^^^^^^^^^^^^^^^^
=== Events
==== Patchset Created
type:: "patchset-created"
change:: link:json.html#change[change attribute]
@ -66,8 +56,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
uploader:: link:json.html#account[account attribute]
Draft Published
^^^^^^^^^^^^^^^
==== Draft Published
type:: "draft-published"
change:: link:json.html#change[change attribute]
@ -76,8 +65,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
uploader:: link:json.html#account[account attribute]
Change Abandoned
^^^^^^^^^^^^^^^^
==== Change Abandoned
type:: "change-abandoned"
change:: link:json.html#change[change attribute]
@ -88,8 +76,7 @@ abandoner:: link:json.html#account[account attribute]
reason:: Reason for abandoning the change.
Change Restored
^^^^^^^^^^^^^^^
==== Change Restored
type:: "change-restored"
change:: link:json.html#change[change attribute]
@ -100,8 +87,7 @@ restorer:: link:json.html#account[account attribute]
reason:: Reason for restoring the change.
Change Merged
^^^^^^^^^^^^^
==== Change Merged
type:: "change-merged"
change:: link:json.html#change[change attribute]
@ -110,8 +96,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
submitter:: link:json.html#account[account attribute]
Merge Failed
^^^^^^^^^^^^
==== Merge Failed
type:: "merge-failed"
change:: link:json.html#change[change attribute]
@ -122,8 +107,7 @@ submitter:: link:json.html#account[account attribute]
reason:: Reason that the merge failed.
Comment Added
^^^^^^^^^^^^^
==== Comment Added
type:: "comment-added"
change:: link:json.html#change[change attribute]
@ -136,16 +120,14 @@ approvals:: All link:json.html#approval[approval attributes] granted.
comment:: Comment text author had written
Ref Updated
^^^^^^^^^^^
==== Ref Updated
type:: "ref-updated"
submitter:: link:json.html#account[account attribute]
refUpdate:: link:json.html#refUpdate[refUpdate attribute]
Reviewer Added
^^^^^^^^^^^^^^
==== Reviewer Added
type:: "reviewer-added"
change:: link:json.html#change[change attribute]
@ -154,8 +136,7 @@ patchSet:: link:json.html#patchSet[patchSet attribute]
reviewer:: link:json.html#account[account attribute]
Topic Changed
^^^^^^^^^^^^^
==== Topic Changed
type:: "topic-changed"
change:: link:json.html#change[change attribute]
@ -164,8 +145,7 @@ changer:: link:json.html#account[account attribute]
oldTopic:: Topic name before it was changed.
SEE ALSO
--------
== SEE ALSO
* link:json.html[JSON Data Formats]
* link:access-control.html[Access Controls]

24
Documentation/cmd-suexec.txt
View File

@ -1,12 +1,9 @@
suexec
======
= suexec
NAME
----
== NAME
suexec - Execute a command as any registered user account
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port>
-i SITE_PATH/etc/ssh_host_rsa_key
@ -18,8 +15,7 @@ SYNOPSIS
[COMMAND]
--
DESCRIPTION
-----------
== DESCRIPTION
The suexec command permits executing any other command as any other
registered user account.
@ -28,8 +24,7 @@ or any user granted granted the link:access-control.html#capability_runAs[Run As
capability. The run as capability is permitted to be used only if
link:config-gerrit.html[auth.enableRunAs] is true.
OPTIONS
-------
== OPTIONS
--as::
Email address of the user you want to impersonate.
@ -41,18 +36,15 @@ OPTIONS
COMMAND::
Gerrit command you want to run.
ACCESS
------
== ACCESS
Caller must be the magic user Gerrit Code Review using the SSH
daemon's host key, or a key on this daemon's peer host key ring,
or a user granted the Run As capability.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
Approve the change with commit c0ff33 as "Verified +1" as user bob@example.com
=====

24
Documentation/cmd-test-submit-rule.txt
View File

@ -1,12 +1,9 @@
gerrit test-submit rule
=======================
= gerrit test-submit rule
NAME
----
== NAME
gerrit test-submit rule - Test prolog submit rules with a chosen changeset.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit test-submit rule'
[-s]
@ -14,24 +11,20 @@ SYNOPSIS
CHANGE
--
DESCRIPTION
-----------
== DESCRIPTION
Provides a way to test prolog link:prolog-cookbook.html[submit rules].
OPTIONS
-------
== OPTIONS
-s::
Reads a rules.pl file from stdin instead of rules.pl in refs/meta/config.
--no-filters::
Don't run the submit_filter/2 from the parent projects of the specified change.
ACCESS
------
== ACCESS
Can be used by anyone that has permission to read the specified changeset.
EXAMPLES
--------
== EXAMPLES
Test submit_rule from stdin and return the results as JSON.
====
@ -60,8 +53,7 @@ Test the active submit_rule from the refs/meta/config branch, ignoring filters i
]
====
SCRIPTING
---------
== SCRIPTING
Can be used either interactively for testing new prolog submit rules, or from a script to check the submit status of a change.
GERRIT

24
Documentation/cmd-test-submit-type.txt
View File

@ -1,12 +1,9 @@
gerrit test-submit type
=======================
= gerrit test-submit type
NAME
----
== NAME
gerrit test-submit type - Test prolog submit type with a chosen change.
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit test-submit type'
[-s]
@ -14,24 +11,20 @@ SYNOPSIS
CHANGE
--
DESCRIPTION
-----------
== DESCRIPTION
Provides a way to test prolog submit type.
OPTIONS
-------
== OPTIONS
-s::
Reads a rules.pl file from stdin instead of rules.pl in refs/meta/config.
--no-filters::
Don't run the submit_type_filter/2 from the parent projects of the specified change.
ACCESS
------
== ACCESS
Can be used by anyone that has permission to read the specified change.
EXAMPLES
--------
== EXAMPLES
Test submit_type from stdin and return the submit type.
====
@ -45,8 +38,7 @@ Test the active submit_type from the refs/meta/config branch, ignoring filters i
"MERGE_IF_NECESSARY"
====
SCRIPTING
---------
== SCRIPTING
Can be used either interactively for testing new prolog submit type, or from a script to check the submit type of a change.
GERRIT

21
Documentation/cmd-version.txt
View File

@ -1,18 +1,14 @@
gerrit version
==============
= gerrit version
NAME
----
== NAME
gerrit version - Show the version of the currently executing Gerrit server
SYNOPSIS
--------
== SYNOPSIS
--
'ssh' -p <port> <host> 'gerrit version'
--
DESCRIPTION
-----------
== DESCRIPTION
Displays a one-line response with the string `gerrit version` followed
by the currently executing version of Gerrit.
@ -28,16 +24,13 @@ the seven-character abbreviated SHA-1 of the commit. See the `git
describe` documentation for details on how `<tagname>` is chosen and how
`<n>` is computed.
ACCESS
------
== ACCESS
Any user who has configured an SSH key.
SCRIPTING
---------
== SCRIPTING
This command is intended to be used in scripts.
EXAMPLES
--------
== EXAMPLES
=====
$ ssh -p 29418 review.example.com gerrit version

18
Documentation/config-auto-site-initialization.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review - Automatic Site Initialization on Startup
=============================================================
= Gerrit Code Review - Automatic Site Initialization on Startup
Description
-----------
== Description
Gerrit supports automatic site initialization on server startup
when Gerrit runs in a servlet container. Both creation of a new site
@ -16,8 +14,7 @@ the init from their local machine prior to deploying Gerrit on such a
server. It may also make deployment and testing in a local servlet
container faster to setup as the init step could be skipped.
Gerrit Configuration
--------------------
== Gerrit Configuration
The site initialization will be performed only if the `gerrit.init`
system property exists (the value of the property is not used, only the
@ -40,8 +37,7 @@ if defined, will be used to determine the site path. The database
connectivity, also for this case, is defined by the `jdbc/ReviewDb`
JNDI property.
Example 1
~~~~~~~~~
=== Example 1
Prepare Tomcat so that a site is initialized at a given path using
the H2 database (if the site doesn't exist yet) or using whatever
@ -52,8 +48,7 @@ database is defined in `etc/gerrit.config` of that site:
$ catalina.sh start
----
Example 2
~~~~~~~~~
=== Example 2
Prepare Tomcat so that an existing site with the path defined in the
`system_config` table is initialized (upgraded) on Gerrit startup. The
@ -65,8 +60,7 @@ Tomcat:
$ catalina.sh start
----
Example 3
~~~~~~~~~
=== Example 3
Assuming the database schema doesn't exist in the database defined
via the `jdbc/ReviewDb` JNDI property, initialize a new site using that

3
Documentation/config-cla.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Contributor Agreements
===========================================
= Gerrit Code Review - Contributor Agreements
Users can be required to sign one or more contributor agreements before
being able to submit a change in a project.

12
Documentation/config-contact.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Contact Information
========================================
= Gerrit Code Review - Contact Information
To help ensure contributor privacy, but still support gathering of
contributor agreements as necessary, Gerrit encrypts all offline
@ -12,8 +11,7 @@ and the `contactstore.url` setting in `gerrit.config` is not set,
Gerrit will not collect contact information from users.
Setup
-----
== Setup
Ensure Bouncy Castle Crypto API is available in the web application's
CLASSPATH (e.g. in `'JETTY_HOME'/lib/plus` for Jetty). Gerrit needs
@ -85,8 +83,7 @@ URL (in `contactstore.url`), and if needed, APPSEC value (in
====
Contact Store Protocol
----------------------
== Contact Store Protocol
To implement a new contact store, the following details are useful.
@ -135,8 +132,7 @@ Using `https://` for the store URL is *highly* encouraged, as it
prevents man-in-the-middle attacks from reading the shared secret
APPSEC token, or messing with the data field.
Data Format
~~~~~~~~~~~
=== Data Format
Once decrypted the `data` field looks something like the following:

132
Documentation/config-gerrit.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review - Configuration
==================================
= Gerrit Code Review - Configuration
File `etc/gerrit.config`
------------------------
== File `etc/gerrit.config`
The optional file `'$site_path'/etc/gerrit.config` is a Git-style
config file that controls many host specific settings for Gerrit.
@ -22,8 +20,7 @@ Sample `etc/gerrit.config`:
----
[[accounts]]
Section accounts
~~~~~~~~~~~~~~~~
=== Section accounts
[[accounts.visibility]]accounts.visibility::
+
@ -44,8 +41,7 @@ If `NONE`, no users other than the current user are visible.
Default is `ALL`.
[[addreviewer]]
Section addreviewer
~~~~~~~~~~~~~~~~~~~
=== Section addreviewer
[[addreviewer.maxWithoutConfirmation]]addreviewer.maxWithoutConfirmation::
+
@ -72,8 +68,7 @@ be added at once by adding a group as reviewer.
Default is 20.
[[auth]]
Section auth
~~~~~~~~~~~~
=== Section auth
See also link:config-sso.html[SSO configuration].
@ -468,8 +463,7 @@ editing gerrit.config and restarting the server.
Default is true.
[[cache]]
Section cache
~~~~~~~~~~~~~
=== Section cache
[[cache.directory]]cache.directory::
+
@ -546,8 +540,7 @@ Default is 128 MiB per cache.
+
If 0, disk storage for the cache is disabled.
[[cache_names]]Standard Caches
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== [[cache_names]]Standard Caches
cache `"accounts"`::
+
@ -709,8 +702,7 @@ this cache is approximately 346 bytes.
See also link:cmd-flush-caches.html[gerrit flush-caches].
[[cache_options]]Cache Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== [[cache_options]]Cache Options
[[cache.diff_intraline.maxIdleWorkers]]cache.diff_intraline.maxIdleWorkers::
+
@ -772,8 +764,7 @@ link:cmd-flush-caches.html[gerrit flush-caches].
Default is 5 minutes.
[[change]]
Section change
~~~~~~~~~~~~~~
=== Section change
[[change.largeChange]]change.largeChange::
+
@ -806,8 +797,7 @@ If 0 the update polling is disabled.
Default is 30 seconds.
[[changeMerge]]
Section changeMerge
~~~~~~~~~~~~~~~~~~~
=== Section changeMerge
[[changeMerge.checkFrequency]]changeMerge.checkFrequency::
+
@ -827,8 +817,7 @@ changes is updated.
Default is 1.
[[commentlink]]
Section commentlink
~~~~~~~~~~~~~~~~~~~
=== Section commentlink
Comment links are find/replace strings applied to change descriptions,
patch comments, in-line code comments and approval category value descriptions
@ -916,8 +905,7 @@ link:rest-api-projects.html#get-config[REST API].
[[contactstore]]
Section contactstore
~~~~~~~~~~~~~~~~~~~~
=== Section contactstore
[[contactstore.url]]contactstore.url::
+
@ -933,8 +921,7 @@ Shared secret of the web based contact store.
[[container]]
Section container
~~~~~~~~~~~~~~~~~
=== Section container
These settings are applied only if Gerrit is started as the container
process through Gerrit's 'gerrit.sh' rc.d compatible wrapper script.
@ -990,8 +977,7 @@ If not set, defaults to '$site_path/bin/gerrit.war', or to
[[core]]
Section core
~~~~~~~~~~~~
=== Section core
[[core.packedGitWindowSize]]core.packedGitWindowSize::
+
@ -1098,8 +1084,7 @@ conflicts.
Default is false, but in a future release may default to true.
[[database]]
Section database
~~~~~~~~~~~~~~~~
=== Section database
The database section configures where Gerrit stores its metadata
records about user accounts and change reviews.
@ -1237,8 +1222,7 @@ This setting only applies if
<<database.connectionPool,database.connectionPool>> is true.
[[download]]
Section download
~~~~~~~~~~~~~~~~
=== Section download
----
[download]
@ -1319,8 +1303,7 @@ If `download.scheme` is not specified, SSH, HTTP and Anonymous HTTP
downloads are allowed.
[[gerrit]]
Section gerrit
~~~~~~~~~~~~~~
=== Section gerrit
[[gerrit.basePath]]gerrit.basePath::
+
@ -1406,8 +1389,7 @@ Default change screen UI to direct users to. Valid values are
`OLD_UI` and `CHANGE_SCREEN2`. Default is `CHANGE_SCREEN2`.
[[gitweb]]
Section gitweb
~~~~~~~~~~~~~~
=== Section gitweb
Gerrit can forward requests to either an internally managed gitweb
(which allows Gerrit to enforce some access controls), or to an
@ -1539,8 +1521,7 @@ the links to draft patch sets from the change review screen.
Valid values are "true" and "false," default is "true".
[[groups]]
Section groups
~~~~~~~~~~~~~~
=== Section groups
[[groups.newGroupsVisibleToAll]]groups.newGroupsVisibleToAll::
+
@ -1550,8 +1531,7 @@ all registered users.
By default, false.
[[hooks]]
Section hooks
~~~~~~~~~~~~~
=== Section hooks
See also link:config-hooks.html[Hooks].
@ -1625,8 +1605,7 @@ Optional timeout value in seconds for synchronous hooks, if not specified
then 30 seconds will be used.
[[http]]
Section http
~~~~~~~~~~~~
=== Section http
[[http.proxy]]http.proxy::
+
@ -1648,8 +1627,7 @@ appear in the http.proxy property above.
[[httpd]]
Section httpd
~~~~~~~~~~~~~
=== Section httpd
The httpd section configures the embedded servlet container.
@ -1882,8 +1860,7 @@ If the file doesn't exist or can't be read the default robots.txt file
bundled with the .war will be used instead.
[[index]]
Section index
~~~~~~~~~~~~~
=== Section index
The index section configures the secondary index.
@ -1908,8 +1885,7 @@ using the link:pgm-reindex.html[reindex program] before restarting the
Gerrit server.
[[ldap]]
Section ldap
~~~~~~~~~~~~
=== Section ldap
LDAP integration is only enabled if `auth.type` is set to
`HTTP_LDAP`, `LDAP` or `CLIENT_SSL_CERT_LDAP`. See above for a
@ -2196,8 +2172,7 @@ must have the DWORD value `allowtgtsessionkey` set to 1 and the account must not
have local administrator privileges.
[[mimetype]]
Section mimetype
~~~~~~~~~~~~~~~~
=== Section mimetype
[[mimetype.name.safe]]mimetype.<name>.safe::
+
@ -2226,8 +2201,7 @@ Common examples:
[[pack]]
Section pack
~~~~~~~~~~~~
=== Section pack
Global settings controlling how Gerrit Code Review creates pack
streams for Git clients running clone, fetch, or pull. Most of these
@ -2253,8 +2227,7 @@ By default, 1.
[[plugins]]
Section plugins
~~~~~~~~~~~~~~~
=== Section plugins
[[plugins.checkFrequency]]plugins.checkFrequency::
+
@ -2270,8 +2243,7 @@ Default is 1 minute.
[[receive]]
Section receive
~~~~~~~~~~~~~~~
=== Section receive
This section is used to set who can execute the 'receive-pack' and
to limit the maximum Git object size that 'receive-pack' will accept.
@ -2373,8 +2345,7 @@ is assumed.
[[repository]]
Section repository
~~~~~~~~~~~~~~~~~~
=== Section repository
Repositories in this sense are the same as projects.
@ -2405,8 +2376,7 @@ groups are allowed. Each on its own line. Groups which don't exist
in the database are ignored.
[[rules]]
Section rules
~~~~~~~~~~~~~
=== Section rules
[[rules.enable]]rules.enable::
+
@ -2417,8 +2387,7 @@ only the default internal rules will be used.
Default is true, to execute project specific rules.
[[sendemail]]
Section sendemail
~~~~~~~~~~~~~~~~~
=== Section sendemail
[[sendemail.enable]]sendemail.enable::
+
@ -2547,8 +2516,7 @@ By default, unset, so no Expiry-Date header is generated.
[[site]]
Section site
~~~~~~~~~~~~
=== Section site
[[site.checkUserAgent]]site.checkUserAgent::
+
@ -2571,8 +2539,7 @@ and text results for changes. If false, the URL is disabled and
returns 404 to clients. Default is true, enabling `/query`.
[[ssh-alias]]
Section ssh-alias
~~~~~~~~~~~~~~~~~
=== Section ssh-alias
Variables in section ssh-alias permit the site administrator to alias
another command from Gerrit or a plugin into the `gerrit` command
@ -2584,8 +2551,7 @@ namespace. To alias `replication start` to `gerrit replicate`:
----
[[sshd]]
Section sshd
~~~~~~~~~~~~
=== Section sshd
[[sshd.backend]]sshd.backend::
+
@ -2797,8 +2763,7 @@ programmatic configuration.
By default, true.
[[suggest]]
Section suggest
~~~~~~~~~~~~~~~
=== Section suggest
[[suggest.accounts]]suggest.accounts::
+
@ -2825,8 +2790,7 @@ are provided. If set to 0, suggestions are always provided.
By default 0.
[[theme]]
Section theme
~~~~~~~~~~~~~
=== Section theme
[[theme.backgroundColor]]theme.backgroundColor::
+
@ -2924,8 +2888,7 @@ As example, here is the theme configuration to have the old green look:
----
[[trackingid]]
Section trackingid
~~~~~~~~~~~~~~~~~~
=== Section trackingid
Tagged footer lines containing references to external
tracking systems, parsed out of the commit message and
@ -2978,8 +2941,7 @@ It is possible to have several trackingid entries for the same
tracking system.
[[transfer]]
Section transfer
~~~~~~~~~~~~~~~~
=== Section transfer
[[transfer.timeout]]transfer.timeout::
+
@ -2997,8 +2959,7 @@ Defaults to 0 seconds, wait indefinitely.
[[upload]]
Section upload
~~~~~~~~~~~~~~
=== Section upload
Sets the group of users allowed to execute 'upload-pack' on the
server, 'upload-pack' is what runs on the server during a user's
@ -3020,8 +2981,7 @@ If no groups are added, any user will be allowed to execute
[[user]]
Section user
~~~~~~~~~~~~
=== Section user
[[user.name]]user.name::
+
@ -3048,8 +3008,7 @@ notifications if the full name of the user is not set.
By default "Anonymous Coward" is used.
File `etc/secure.config`
------------------------
== File `etc/secure.config`
The optional file `'$site_path'/etc/secure.config` overrides (or
supplements) the settings supplied by `'$site_path'/etc/gerrit.config`.
The file should be readable only by the daemon process and can be
@ -3079,8 +3038,7 @@ Sample `etc/secure.config`:
password = s3kr3t
----
File `etc/peer_keys`
--------------------
== File `etc/peer_keys`
The optional file `'$site_path'/etc/peer_keys` controls who can
login as the 'Gerrit Code Review' user, required for the link:cmd-suexec.html[suexec]
@ -3089,8 +3047,7 @@ command.
The format is one Base-64 encoded public key per line.
Database system_config
----------------------
== Database system_config
Several columns in the `system_config` table within the metadata
database may be set to control how Gerrit behaves.
@ -3100,8 +3057,7 @@ The contents of the `system_config` table are cached at startup
by Gerrit. If you modify any columns in this table, Gerrit needs
to be restarted before it will use the new values.
Configurable Parameters
~~~~~~~~~~~~~~~~~~~~~~~
=== Configurable Parameters
site_path::
+

54
Documentation/config-gitweb.txt
View File

@ -1,12 +1,10 @@
Gitweb Integration
------------------
== Gitweb Integration
Gerrit Code Review can manage and generate hyperlinks to gitweb,
allowing users to jump from Gerrit content to the same information,
but shown by gitweb.
Internal/Managed gitweb
~~~~~~~~~~~~~~~~~~~~~~~
=== Internal/Managed gitweb
In the internal configuration, Gerrit inspects the request, enforces
its project level access controls, and directly executes `gitweb.cgi`
@ -37,16 +35,14 @@ To enable this feature, set both: `gitweb.cgi` and `gitweb.url`.
After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
be restarted and clients must reload the host page to see the change.
Configuration
^^^^^^^^^^^^^
==== Configuration
Most of the gitweb configuration file is handled automatically
by Gerrit Code Review. Site specific overrides can be placed in
`'$site_path'/etc/gitweb_config.perl`, as this file is loaded as
part of the generated configuration file.
Logo and CSS
^^^^^^^^^^^^
==== Logo and CSS
If the package-manager installed CGI (`/usr/lib/cgi-bin/gitweb.cgi`)
is being used, the stock CSS and logo files will be served from
@ -56,8 +52,7 @@ Otherwise, Gerrit expects `gitweb.css` and `git-logo.png` to be found
in the same directory as the CGI script itself. This matches with
the default source code distribution, and most custom installations.
Access Control
^^^^^^^^^^^^^^
==== Access Control
Access controls for internally managed gitweb page views are enforced
using the standard project READ +1 permission.
@ -68,19 +63,16 @@ refs/meta/config, refs/meta/dashboards/*, etc.). If you have exclusive read
permissions for any references, make sure to include all parties that should be
able to read the gitweb info for any of the branches in that project.
External/Unmanaged gitweb
~~~~~~~~~~~~~~~~~~~~~~~~~
=== External/Unmanaged gitweb
For the external configuration, gitweb runs under the control of an
external web server, and Gerrit access controls are not enforced. Gerrit
provides configuration parameters for integration with GitWeb.
[[linuxGitWeb]]
Linux Installation
^^^^^^^^^^^^^^^^^^
==== Linux Installation
Install GitWeb
++++++++++++++
===== Install GitWeb
On Ubuntu:
@ -94,8 +86,7 @@ With Yum:
$ yum install gitweb
====
Configure GitWeb
++++++++++++++++
===== Configure GitWeb
Update `/etc/gitweb.conf`, add the public GIT repositories:
@ -126,11 +117,9 @@ $logo = "git-logo.png";
$favicon = "git-favicon.png";
----
Configure & Restart Apache Web Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== Configure & Restart Apache Web Server
Configure Apache
++++++++++++++++
===== Configure Apache
Link gitweb to `/var/www/gitweb`, check `/etc/gitweb.conf` if unsure of paths:
@ -159,8 +148,7 @@ AllowOverride None
*NOTE* This may have already been added by yum/apt-get. If that's the case, leave as
is.
Restart the Apache Web Server
+++++++++++++++++++++++++++++
===== Restart the Apache Web Server
====
$ sudo /etc/init.d/apache2 restart
@ -171,8 +159,7 @@ Now you should be able to view your repository projects online:
link:http://localhost/gitweb[http://localhost/gitweb]
[[WindowsGitWeb]]
Windows Installation
^^^^^^^^^^^^^^^^^^^^
==== Windows Installation
Instructions are available for installing the GitWeb module distributed with
MsysGit:
@ -220,8 +207,7 @@ contents: `bin/` `lib/` `site/`
copy the contents of lib into `msysgit/lib/perl5/5.8.8` and overwrite existing files.
Enable GitWeb Integration
^^^^^^^^^^^^^^^^^^^^^^^^^
==== Enable GitWeb Integration
To enable the external gitweb integration, set
link:config-gerrit.html#gitweb.url[gitweb.url] with the URL of your
@ -258,23 +244,20 @@ specified for all of the `project`, `revision`, `branch`, `roottree`,
`file`, and `filehistory` settings, otherwise the configuration will
not be used.
Access Control
++++++++++++++
===== Access Control
Gitweb access controls can be implemented using standard web server
access controls. This isn't typically integrated with Gerrit's own
access controls. Caution must be taken to ensure the controls are
consistent if access needs to be restricted.
Caching Gitweb
++++++++++++++
===== Caching Gitweb
If your repository set is large and you are expecting a lot
of users, you may want to look at the caching forks used by
high-traffic sites like kernel.org or repo.or.cz.
Alternatives to gitweb
~~~~~~~~~~~~~~~~~~~~~~
=== Alternatives to gitweb
There are other alternatives to gitweb that can also be used with
Gerrit, such as cgit.
@ -282,8 +265,7 @@ cgit can be used by specifying `gitweb.type` to be 'cgit'.
It is also possible to define custom patterns.
See Also
~~~~~~~~
=== See Also
* link:config-gerrit.html#gitweb[Section gitweb]
* link:http://hjemli.net/git/cgit/[cgit]

51
Documentation/config-hooks.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Hooks
==========================
= Gerrit Code Review - Hooks
Gerrit does not run any of the standard git hooks in the
repositories it works with, but it does have its own hook mechanism
@ -17,11 +16,9 @@ the outcome of any given change. Because of the fact the hooks are
run in the background after the activity, a hook might not be notified
about an event if the server is shutdown before the hook can be invoked.
Supported Hooks
---------------
== Supported Hooks
ref-update
~~~~~~~~~~
=== ref-update
This is called when a push request is received by Gerrit. It allows
a push to be rejected before it is committed to the Gerrit repository.
@ -38,8 +35,7 @@ for configuration details.
ref-update --project <project name> --refname <refname> --uploader <uploader> --oldrev <sha1> --newrev <sha1>
====
patchset-created
~~~~~~~~~~~~~~~~
=== patchset-created
This is called whenever a patchset is created (this includes new
changes and drafts).
@ -48,8 +44,7 @@ changes and drafts).
patchset-created --change <change id> --is-draft <boolean> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
====
draft-published
~~~~~~~~~~~~~~~
=== draft-published
This is called whenever a draft change is published.
@ -57,8 +52,7 @@ This is called whenever a draft change is published.
draft-published --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
====
comment-added
~~~~~~~~~~~~~
=== comment-added
This is called whenever a comment is added to a change.
@ -66,8 +60,7 @@ This is called whenever a comment is added to a change.
comment-added --change <change id> --is-draft <boolean> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --author <comment author> --commit <commit> --comment <comment> [--<approval category id> <score> --<approval category id> <score> ...]
====
change-merged
~~~~~~~~~~~~~
=== change-merged
Called whenever a change has been merged.
@ -75,8 +68,7 @@ Called whenever a change has been merged.
change-merged --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1>
====
merge-failed
~~~~~~~~~~~~
=== merge-failed
Called whenever a change has failed to merge.
@ -84,8 +76,7 @@ Called whenever a change has failed to merge.
merge-failed --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --reason <reason>
====
change-abandoned
~~~~~~~~~~~~~~~~
=== change-abandoned
Called whenever a change has been abandoned.
@ -93,8 +84,7 @@ Called whenever a change has been abandoned.
change-abandoned --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --abandoner <abandoner> --commit <sha1> --reason <reason>
====
change-restored
~~~~~~~~~~~~~~~
=== change-restored
Called whenever a change has been restored.
@ -102,8 +92,7 @@ Called whenever a change has been restored.
change-restored --change <change id> --change-url <change url> --project <project name> --branch <branch> --topic <topic> --restorer <restorer> --commit <sha1> --reason <reason>
====
ref-updated
~~~~~~~~~~~
=== ref-updated
Called whenever a ref has been updated.
@ -111,8 +100,7 @@ Called whenever a ref has been updated.
ref-updated --oldrev <old rev> --newrev <new rev> --refname <ref name> --project <project name> --submitter <submitter>
====
reviewer-added
~~~~~~~~~~~~~~
=== reviewer-added
Called whenever a reviewer is added to a change.
@ -120,8 +108,7 @@ Called whenever a reviewer is added to a change.
reviewer-added --change <change id> --change-url <change url> --project <project name> --branch <branch> --reviewer <reviewer>
====
topic-changed
~~~~~~~~~~~~~
=== topic-changed
Called whenever a change's topic is changed from the Web UI or via the REST API.
@ -129,8 +116,7 @@ Called whenever a change's topic is changed from the Web UI or via the REST API.
topic-changed --change <change id> --project <project name> --branch <branch> --changer <changer> --old-topic <old topic> --new-topic <new topic>
====
cla-signed
~~~~~~~~~~
=== cla-signed
Called whenever a user signs a contributor license agreement.
@ -139,8 +125,7 @@ Called whenever a user signs a contributor license agreement.
====
Configuration Settings
----------------------
== Configuration Settings
It is possible to change where Gerrit looks for hooks, and what
filenames it looks for, by adding a [hooks] section in gerrit.config.
@ -152,8 +137,7 @@ hooks.draftPublishedHook, hooks.commentAddedHook, hooks.changeMergedHook,
hooks.changeAbandonedHook, hooks.changeRestoredHook, hooks.refUpdatedHook,
hooks.refUpdateHook, hooks.reviewerAddedHook and hooks.claSignedHook.
Missing Change URLs
-------------------
== Missing Change URLs
If link:config-gerrit.html#gerrit.canonicalWebUrl[gerrit.canonicalWebUrl]
is not set in `gerrit.config` the `--change-url` flag may not be
@ -161,8 +145,7 @@ passed to all hooks. Hooks started out of an SSH context (for example
the patchset-created hook) don't know the server's web URL, unless
this variable is configured.
See Also
--------
== See Also
* link:config-gerrit.html#hooks[Section hooks]

45
Documentation/config-labels.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Review Labels
==================================
= Gerrit Code Review - Review Labels
As part of the code review process, reviewers score each change with
values for each label configured for the project. The label values that
@ -10,8 +9,7 @@ groups within projects, enabling functionality for that group's members.
[[label_Code-Review]]
Label: Code-Review
------------------
== Label: Code-Review
The code review label is the second of two default labels that is
configured upon the creation of a Gerrit instance. It may have any
@ -83,8 +81,7 @@ value if present blocks a submit, while the highest positive value is
required to enable submit.
[[label_Verified]]
Label: Verified
---------------
== Label: Verified
The Verified label was originally invented by the Android Open Source
Project to mean 'compiles, passes basic unit tests'. Some CI tools
@ -131,8 +128,7 @@ behavior.
[[label_custom]]
Your Label Here
---------------
== Your Label Here
Site administrators and project owners can also define their own labels.
@ -159,16 +155,14 @@ with inherited labels appearing first, providing some layout control to
the administrator.
[[label_name]]
`label.Label-Name`
~~~~~~~~~~~~~~~~~~
=== `label.Label-Name`
The name for a label, consisting only of alphanumeric characters and
`-`.
[[label_value]]
`label.Label-Name.value`
~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.value`
A multi-valued key whose values are of the form `"<#> Value description
text"`. The `<#>` may be any positive or negative number with an
@ -176,8 +170,7 @@ optional leading `+`.
[[label_abbreviation]]
`label.Label-Name.abbreviation`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.abbreviation`
An abbreviated name for a label shown as a compact column header, for
example on project dashboards. Defaults to all the uppercase characters
@ -185,8 +178,7 @@ in the label name, e.g. `Label-Name` is abbreviated by default as `LN`.
[[label_function]]
`label.Label-Name.function`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.function`
The name of a function for evaluating multiple votes for a label. This
function is only applied if the default submit rule is used for a label.
@ -221,15 +213,13 @@ determining whether a change is submittable.
[[label_copyMinScore]]
`label.Label-Name.copyMinScore`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.copyMinScore`
If true, the lowest possible negative value for the label is copied
forward when a new patch set is uploaded.
[[label_copyMaxScore]]
`label.Label-Name.copyMaxScore`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.copyMaxScore`
If true, the highest possible positive value for the label is copied
forward when a new patch set is uploaded. This can be used to enable
@ -237,8 +227,7 @@ sticky approvals, reducing turn-around for trivial cleanups prior to
submitting a change.
[[label_copyAllScoresOnTrivialRebase]]
`label.Label-Name.copyAllScoresOnTrivialRebase`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.copyAllScoresOnTrivialRebase`
If true, all scores for the label are copied forward when a new patch
set is uploaded that is a trivial rebase. A new patch set is considered
@ -249,8 +238,7 @@ This can be used to enable sticky approvals, reducing turn-around for
trivial rebases prior to submitting a change. Defaults to false.
[[label_copyAllScoresIfNoCodeChange]]
`label.Label-Name.copyAllScoresIfNoCodeChange`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.copyAllScoresIfNoCodeChange`
If true, all scores for the label are copied forward when a new patch
set is uploaded that has the same parent commit as the previous patch
@ -261,16 +249,14 @@ if only the commit message is changed prior to submitting a change.
Defaults to false.
[[label_canOverride]]
`label.Label-Name.canOverride`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.canOverride`
If false, the label cannot be overridden by child projects. Any
configuration for this label in child projects will be ignored. Defaults
to true.
[[label_branch]]
`label.Label-Name.branch`
~~~~~~~~~~~~~~~~~~~~~~~~~
=== `label.Label-Name.branch`
By default a given project's label applicable scope is all changes
on all branches of this project and its child projects.
@ -294,8 +280,7 @@ assign permissions for that label on a branch, but this permission is then
ignored if the label doesn't apply for that branch.
[[label_example]]
Example
~~~~~~~
=== Example
To define a new 3-valued category that behaves exactly like `Verified`,
but has different names/labels:

9
Documentation/config-login-register.txt
View File

@ -1,6 +1,5 @@
[[usersetup]]
Initial Login
-------------
== Initial Login
It's time to exit the gerrit2 account as you now have Gerrit running on your
host and setup your first workspace.
@ -21,8 +20,7 @@ If you have the files, you may skip the key generating step.
If you don't see the files in your listing, your will have to generate rsa
keys for your ssh sessions:
SSH key generation
~~~~~~~~~~~~~~~~~~
=== SSH key generation
*Please don't generate new keys if you already have a valid keypair!*
*They will be overwritten!*
@ -53,8 +51,7 @@ SSH key generation
user@host:~$
----
Registering your key in Gerrit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Registering your key in Gerrit
Open a browser and enter the canonical url of your Gerrit server. You can
find the url in the settings file.

66
Documentation/config-mail.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Mail Templates
===================================
= Gerrit Code Review - Mail Templates
Gerrit uses velocity templates for the bulk of the standard mails it sends out.
There are builtin default templates which are used if they are not overridden.
@ -7,8 +6,7 @@ These defaults are also provided as examples so that administrators may copy
them and easily modify them to tweak their contents.
Template Locations and Extensions:
----------------------------------
== Template Locations and Extensions:
The default example templates reside under: `'$site_path'/etc/mail` and are
terminated with the double extension `.vm.example`. Modifying these example
@ -17,77 +15,66 @@ example template to an equivalently named file without the `.example` extension
and modifying it will allow an administrator to customize the template.
Supported Mail Templates:
-------------------------
== Supported Mail Templates:
Each mail that Gerrit sends out is controlled by at least one template. These
are listed below. Change emails are influenced by two additional templates,
one to set the subject line, and one to set the footer which gets appended to
all the change emails (see `ChangeSubject.vm` and `ChangeFooter.vm` below.)
Abandoned.vm
~~~~~~~~~~~~
=== Abandoned.vm
The `Abandoned.vm` template will determine the contents of the email related
to a change being abandoned. It is a `ChangeEmail`: see `ChangeSubject.vm` and
`ChangeFooter.vm`.
ChangeFooter.vm
~~~~~~~~~~~~~~~
=== ChangeFooter.vm
The `ChangeFooter.vm` template will determine the contents of the footer
text that will be appended to emails related to changes (all `ChangeEmail`s).
ChangeSubject.vm
~~~~~~~~~~~~~~~~
=== ChangeSubject.vm
The `ChangeSubject.vm` template will determine the contents of the email
subject line for ALL emails related to changes.
Comment.vm
~~~~~~~~~~
=== Comment.vm
The `Comment.vm` template will determine the contents of the email related to
a user submitting comments on changes. It is a `ChangeEmail`: see
`ChangeSubject.vm`, `ChangeFooter.vm` and `CommentFooter.vm`.
CommentFooter.vm
~~~~~~~~~~~~~~~~
=== CommentFooter.vm
The `CommentFooter.vm` template will determine the contents of the footer
text that will be appended to emails related to a user submitting comments on
changes. See `ChangeSubject.vm`, `Comment.vm` and `ChangeFooter.vm`.
CommitMessageEdited.vm
~~~~~~~~~~~~~~~~~~~~~~
=== CommitMessageEdited.vm
The `CommitMessageEdited.vm` template will determine the contents of the email
related to a user editing the commit message through the Gerrit UI. It is a
`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
Footer.vm
~~~~~~~~~
=== Footer.vm
The `Footer.vm` template will determine the contents of the footer text
appended to the end of all outgoing emails after the ChangeFooter and
CommentFooter.
Merged.vm
~~~~~~~~~
=== Merged.vm
The `Merged.vm` template will determine the contents of the email related to
a change successfully merged to the head. It is a `ChangeEmail`: see
`ChangeSubject.vm` and `ChangeFooter.vm`.
MergeFail.vm
~~~~~~~~~~~~
=== MergeFail.vm
The `MergeFail.vm` template will determine the contents of the email related
to a failure upon attempting to merge a change to the head. It is a
`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
NewChange.vm
~~~~~~~~~~~~
=== NewChange.vm
The `NewChange.vm` template will determine the contents of the email related
to a user submitting a new change for review. This includes changes created
@ -95,14 +82,12 @@ by actions made by the user in the Web UI such as cherry picking a commit or
reverting a change. It is a `ChangeEmail`: see `ChangeSubject.vm` and
`ChangeFooter.vm`.
RegisterNewEmail.vm
~~~~~~~~~~~~~~~~~~~
=== RegisterNewEmail.vm
The `RegisterNewEmail.vm` template will determine the contents of the email
related to registering new email accounts.
ReplacePatchSet.vm
~~~~~~~~~~~~~~~~~~
=== ReplacePatchSet.vm
The `ReplacePatchSet.vm` template will determine the contents of the email
related to a user submitting a new patchset for a change. This includes
@ -110,23 +95,20 @@ patchsets created by actions made by the user in the Web UI such as editing
the commit message, cherry picking a commit, or rebasing a change. It is a
`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
Restored.vm
~~~~~~~~~~~
=== Restored.vm
The `Restored.vm` template will determine the contents of the email related
to a change being restored. It is a `ChangeEmail`: see `ChangeSubject.vm` and
`ChangeFooter.vm`.
Reverted.vm
~~~~~~~~~~~
=== Reverted.vm
The `Reverted.vm` template will determine the contents of the email related
to a change being reverted. It is a `ChangeEmail`: see `ChangeSubject.vm` and
`ChangeFooter.vm`.
Mail Variables and Methods
--------------------------
== Mail Variables and Methods
Mail templates can access and display objects currently made available to them
via the velocity context. While the base objects are documented here, it is
@ -137,16 +119,14 @@ that writing templates for Gerrit emails is likely to require some basic
knowledge of the class structure to be useful. Browsing the source code might
be necessary for anything more than a minor formatting change.
Warning
~~~~~~~
=== Warning
Be aware that modifying templates can cause them to fail to parse and therefore
not send out the actual email, or worse, calling methods on the available
objects could have internal side effects which would adversely affect the
health of your Gerrit server and/or data.
All OutgoingEmails
~~~~~~~~~~~~~~~~~~
=== All OutgoingEmails
All outgoing emails have the following variables available to them:
@ -165,8 +145,7 @@ $StringUtils::
A reference to the Apache `StringUtils` class. This can be very useful for
formatting strings.
Change Emails
~~~~~~~~~~~~~
=== Change Emails
All change related emails have the following additional variables available to them:
@ -203,8 +182,7 @@ $patchSetInfo::
A reference to the current `PatchSetInfo`.
See Also
--------
== See Also
* link:http://velocity.apache.org/[velocity]

30
Documentation/config-project-config.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Project Configuration File Format
======================================================
= Gerrit Code Review - Project Configuration File Format
This page explains the storage format of Gerrit's project configuration
and access control models.
@ -10,8 +9,7 @@ affected project. Direct manipulation of these files is mainly
relevant in an automation scenario of the access controls.
The +refs/meta/config+ namespace
--------------------------------
== The +refs/meta/config+ namespace
The namespace contains three different files that play different
roles in the permission model. With read permission to that reference,
@ -24,8 +22,7 @@ space if you'd like to use the possibility to automate permission updates.
[[file-project_config]]
The file +project.config+
-------------------------
== The file +project.config+
The +project.config+ file contains the link between groups and their
permitted actions on reference patterns in this project and any projects
@ -75,8 +72,7 @@ on a global level. You can find examples of these
[[project-section]]
Project section
~~~~~~~~~~~~~~~
=== Project section
The project section includes configuration of project settings.
@ -86,8 +82,7 @@ These are the keys:
[[receive-section]]
Receive section
~~~~~~~~~~~~~~~
=== Receive section
The receive section includes configuration of project-specific
receive settings:
@ -135,8 +130,7 @@ Default is zero.
Common unit suffixes of k, m, or g are supported.
[[submit-section]]
Submit section
~~~~~~~~~~~~~~
=== Submit section
The submit section includes configuration of project-specific
submit settings:
@ -152,8 +146,7 @@ Merge strategy
[[access-section]]
Access section
~~~~~~~~~~~~~~
=== Access section
Each +access+ section includes a reference and access rights connected
to groups. Each group listed must exist in the link:#file-groups[+groups+ file].
@ -164,8 +157,7 @@ documentation for a full list of available access rights.
[[capability-section]]
Capability section
~~~~~~~~~~~~~~~~~~
=== Capability section
The +capability+ section only appears once, and only in the +All-Projects+
repository. It controls Gerrit administration capabilities that are configured
@ -177,8 +169,7 @@ documentation for a full list of available capabilities.
[[file-groups]]
The file +groups+
-----------------
== The file +groups+
Each group in this list is linked with its UUID so that renaming of
groups is possible without having to rewrite every +groups+ file
@ -209,8 +200,7 @@ link:cmd-ls-groups.html[the +ls-groups+ SSH command].
[[file-rules_pl]]
The file +rules.pl+
-------------------
== The file +rules.pl+
The +rules.pl+ files allows you to replace or amend the default Prolog
rules that control e.g. what conditions need to be fulfilled for a

27
Documentation/config-reverseproxy.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review - Reverse Proxy
==================================
= Gerrit Code Review - Reverse Proxy
Description
-----------
== Description
Gerrit can be configured to run behind a third-party web server.
This allows the other web server to bind to the privileged port 80
@ -10,8 +8,7 @@ This allows the other web server to bind to the privileged port 80
from Java to optimized native C code.
Gerrit Configuration
--------------------
== Gerrit Configuration
Ensure `'$site_path'/etc/gerrit.config` has the property
link:config-gerrit.html#httpd.listenUrl[httpd.listenUrl] configured
@ -25,8 +22,7 @@ during 'init'.
----
Apache 2 Configuration
----------------------
== Apache 2 Configuration
To run Gerrit behind an Apache server using 'mod_proxy', enable the
necessary Apache2 modules:
@ -62,8 +58,7 @@ or links will redirect to incorrect locations.
The two options 'AllowEncodedSlashes On' and 'ProxyPass .. nocanon' are required
since Gerrit 2.6.
SSL
~~~
=== SSL
To enable Apache to perform the SSL processing, use 'proxy-https://'
in httpd.listenUrl within Gerrit's configuration file, and enable
@ -83,8 +78,7 @@ See the Apache 'mod_ssl' documentation for more details on how to
configure SSL within the server, like controlling how strong of an
encryption algorithm is required.
Troubleshooting
~~~~~~~~~~~~~~~
=== Troubleshooting
If you are encountering 'Page Not Found' errors when opening the change
screen, your Apache proxy is very likely decoding the passed URL.
@ -93,8 +87,7 @@ Make sure to either use 'AllowEncodedSlashes On' together with
'AllowEncodedSlashes NoDecode' set.
Nginx Configuration
-------------------
== Nginx Configuration
To run Gerrit behind an Nginx server, use a server statement such
as this one:
@ -112,8 +105,7 @@ as this one:
}
----
SSL
~~~
=== SSL
To enable Nginx to perform the SSL processing, use 'proxy-https://'
in httpd.listenUrl within Gerrit's configuration file, and enable
@ -136,8 +128,7 @@ See the Nginx 'http ssl module' documentation for more details on
how to configure SSL within the server, like controlling how strong
of an encryption algorithm is required.
Troubleshooting
~~~~~~~~~~~~~~~
=== Troubleshooting
If you are encountering 'Page Not Found' errors when opening the change
screen, your Nginx proxy is very likely decoding the passed URL.

21
Documentation/config-sso.txt
View File

@ -1,12 +1,10 @@
Gerrit Code Review - Single Sign-On Security
============================================
= Gerrit Code Review - Single Sign-On Security
Gerrit supports integration with some types of single sign-on
security solutions, making it possible for end-users to setup
and manage accounts, without administrator involvement.
OpenID
------
== OpenID
By default a new Gerrit installation relies upon OpenID to perform
user authentication services. To enable OpenID, the auth.type
@ -50,8 +48,7 @@ To trust only Google Accounts:
git config --file $site_path/etc/gerrit.config auth.trustedOpenID 'https://www.google.com/accounts/o8/id?id='
====
Database Schema
~~~~~~~~~~~~~~~
=== Database Schema
User identities obtained from OpenID providers are stored into the
`account_external_ids` table. Users may link more than one OpenID
@ -61,8 +58,7 @@ in to Gerrit if they are frequently switching between different
unique OpenID accounts.
HTTP Basic/Digest Authentication
--------------------------------
== HTTP Basic/Digest Authentication
When using HTTP authentication, Gerrit assumes that the servlet
container or the frontend web server has performed all user
@ -107,8 +103,7 @@ authentication at the proper time:
</Location>
====
Database Schema
~~~~~~~~~~~~~~~
=== Database Schema
User identities are stored in the `account_external_ids` table.
The user string obtained from the authorization header has the prefix
@ -117,8 +112,7 @@ if a username was "foo" then the external_id field would be populated
with "gerrit:foo".
Computer Associates Siteminder
------------------------------
== Computer Associates Siteminder
Siteminder is a commercial single sign on solution marketed by
Computer Associates. It is very common in larger enterprise
@ -167,8 +161,7 @@ Add the following to `$JETTY_HOME/etc/jetty.xml` under
====
Database Schema
~~~~~~~~~~~~~~~
=== Database Schema
User identities are stored in the `account_external_ids` table.
The user string obtained from Siteminder (e.g. the value in the

15
Documentation/config-themes.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Themes
===========================
= Gerrit Code Review - Themes
Gerrit supports some customization of the HTML it sends to
the browser, allowing organizations to alter the look and
@ -15,8 +14,7 @@ only served from a single theme directory; if you want to modify or
extend an inherited theme, you must copy it into the appropriate
per-project directory.
HTML Header/Footer
------------------
== HTML Header/Footer
At startup Gerrit reads the following files (if they exist) and
uses them to customize the HTML page it sends to clients:
@ -44,8 +42,7 @@ typically a single `<div>` tag. The server parses it as XML, and
then inserts the root element into the host page. If a file has
more than one root level element, Gerrit will not start.
Static Images
-------------
== Static Images
Static image files can also be served from `'$site_path'/static`,
and may be referenced in `GerritSite{Header,Footer}.html`
@ -58,8 +55,7 @@ being served from this location by enforcing the rule that file names
cannot contain `/` or `\`. (Client requests for `static/foo/bar`
will result in 404 Not Found responses.)
HTTP Caching
------------
== HTTP Caching
The header, footer, and CSS files are inlined into the host page,
which is always sent with a no-cache header. Clients will see any
@ -87,8 +83,7 @@ disk cache. If the image needs to be modified, create a new file,
`my_logo2.cache.png` and update the header (or footer) HTML to
reference the new image path.
Google Analytics Integration
----------------------------
== Google Analytics Integration
To connect Gerrit to Google Analytics add the following to your
`GerritSiteFooter.html`:

9
Documentation/config-validation.txt
View File

@ -1,12 +1,10 @@
Gerrit Code Review - Commit Validation
======================================
= Gerrit Code Review - Commit Validation
Gerrit supports link:dev-plugins.html[plugin-based] validation of
commits.
[[new-commit-validation]]
New commit validation
---------------------
== New commit validation
Plugins implementing the `CommitValidationListener` interface can
@ -24,8 +22,7 @@ Out of the box, Gerrit includes a plugin that checks the length of the
subject and body lines of commit messages on uploaded commits.
[[pre-merge-validation]]
Pre-merge validation
--------------------
== Pre-merge validation
Plugins implementing the `MergeValidationListener` interface can

15
Documentation/database-setup.txt
View File

@ -1,12 +1,10 @@
[[createdb]]
Database Setup
--------------
== Database Setup
During the init phase of Gerrit you will need to specify which database to use.
[[createdb_h2]]
H2
~~
=== H2
If you choose H2, Gerrit will automatically set up the embedded H2 database as
backend so no set up or configuration is necessary.
@ -21,8 +19,7 @@ and it's not possible to set up H2 in a load balanced/hotswap configuration.
If this option interests you, you might want to consider link:install-quick.html[the quick guide].
[[createdb_postgres]]
PostgreSQL
~~~~~~~~~~
=== PostgreSQL
This option is more complicated than the H2 option but is recommended
for larger installations. It's the database backend with the largest userbase
@ -41,8 +38,7 @@ Visit PostgreSQL's link:http://www.postgresql.org/docs/9.1/interactive/index.htm
using PostgreSQL.
[[createdb_mysql]]
MySQL
~~~~~
=== MySQL
This option is also more complicated than the H2 option. Just as with
PostgreSQL it's also recommended for larger installations.
@ -65,8 +61,7 @@ Visit MySQL's link:http://dev.mysql.com/doc/[documentation] for further
information regarding using MySQL.
[[createdb_oracle]]
Oracle
~~~~~~
=== Oracle
PostgreSQL or H2 is the recommended database for Gerrit Code Review.
Oracle is supported for environments where running on an existing Oracle

57
Documentation/dev-buck.txt
View File

@ -1,9 +1,7 @@
Gerrit Code Review - Building with Buck
=======================================
= Gerrit Code Review - Building with Buck
Installation
------------
== Installation
There is currently no binary distribution of Buck, so it has to be manually
built and installed. Apache Ant is required. Currently only Linux and Mac
@ -50,12 +48,10 @@ the script's header comments for installation instructions.
[[eclipse]]
Eclipse Integration
-------------------
== Eclipse Integration
Generating the Eclipse Project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Generating the Eclipse Project
Create the Eclipse project:
@ -75,8 +71,7 @@ Filters on a folder, they will be overwritten the next time you run
`tools/eclipse/project.py`.
Refreshing the Classpath
~~~~~~~~~~~~~~~~~~~~~~~~
=== Refreshing the Classpath
If an updated classpath is needed, the Eclipse project can be
refreshed and missing dependency JARs can be downloaded:
@ -86,8 +81,7 @@ refreshed and missing dependency JARs can be downloaded:
----
Attaching Sources
~~~~~~~~~~~~~~~~~
=== Attaching Sources
To save time and bandwidth source JARs are only downloaded by the buck
build where necessary to compile Java source into JavaScript using the
@ -100,12 +94,10 @@ show documentation or dive into the implementation of a library JAR:
[[build]]
Building on the Command Line
----------------------------
== Building on the Command Line
Gerrit Development WAR File
~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Gerrit Development WAR File
To build the Gerrit web application:
@ -120,8 +112,7 @@ The output executable WAR will be placed in:
----
Extension and Plugin API JAR Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Extension and Plugin API JAR Files
To build the extension, plugin and GWT API JAR files:
@ -159,8 +150,7 @@ for the repository need to be
link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
configured in Maven's settings.xml file].
Plugins
~~~~~~~
=== Plugins
To build all core plugins:
@ -213,8 +203,7 @@ next time project.py is run:
[[documentation]]
Documentation
~~~~~~~~~~~~~
=== Documentation
To build only the documentation:
@ -247,8 +236,7 @@ The WAR file will be placed in:
----
[[release]]
Gerrit Release WAR File
~~~~~~~~~~~~~~~~~~~~~~~
=== Gerrit Release WAR File
To build the release of the Gerrit web application, including documentation and
all core plugins:
@ -264,8 +252,7 @@ The output release WAR will be placed in:
----
[[tests]]
Running Unit Tests
------------------
== Running Unit Tests
To run all tests including acceptance tests:
@ -287,8 +274,7 @@ To run a specific test, e.g. the acceptance test
----
Dependencies
------------
== Dependencies
Dependency JARs are normally downloaded automatically, but Buck can inspect
its graph and download any missing JAR files. This is useful to enable
@ -319,8 +305,7 @@ The `local.properties` file may be placed in the root of the gerrit repository
being built, or in `~/.gerritcodereview/`. The file in the root of the gerrit
repository has precedence.
Building against unpublished Maven JARs
---------------------------------------
== Building against unpublished Maven JARs
To build against unpublished Maven JARs, like gwtorm or PrologCafe, the custom
JARs must be installed in the local Maven repository (`mvn clean install`) and
@ -337,8 +322,7 @@ that artifact:
)
----
Building against artifacts from custom Maven repositories
---------------------------------------------------------
== Building against artifacts from custom Maven repositories
To build against custom Maven repositories, two modes of operations are
supported: with rewrite in local.properties and without.
@ -382,8 +366,7 @@ And corresponding BUCK excerpt:
)
----
Caching Build Results
~~~~~~~~~~~~~~~~~~~~~
=== Caching Build Results
Build results can be locally cached, saving rebuild time when
switching between Git branches. Buck's documentation covers
@ -399,8 +382,7 @@ The trivial case using a local directory is:
----
[[buck-daemon]]
Using Buck daemon
~~~~~~~~~~~~~~~~~
=== Using Buck daemon
Buck ships with a daemon command `buckd`, which uses the
link:https://github.com/martylamb/nailgun[Nailgun] protocol for running
@ -426,8 +408,7 @@ run `buck` as usual:
[-] BUILDING...FINISHED 0.2s
----
Override Buck's settings
~~~~~~~~~~~~~~~~~~~~~~~~
=== Override Buck's settings
Additional JVM args for Buck can be set in `.buckjavaargs` in the
project root directory. For example to override Buck's default 1GB

33
Documentation/dev-contributing.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Contributing
=================================
= Gerrit Code Review - Contributing
Gerrit is developed as a self-hosting open source project and
very much welcomes contributions from anyone with a contributor's
@ -44,8 +43,7 @@ haven't replied or made a fix, so it helps them know if you
missed it or decided against it.
Review Criteria
---------------
== Review Criteria
Here are some hints as to what approvers may be looking for
before approving or submitting changes to the Gerrit project.
@ -58,8 +56,7 @@ spans, we really do want your code.
[[commit-message]]
Commit Message
--------------
== Commit Message
It is essential to have a good commit message if you want your
change to be reviewed.
@ -74,8 +71,7 @@ change to be reviewed.
* Include a Change-Id line
A sample good Gerrit commit message:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== A sample good Gerrit commit message:
====
Add sample commit message to guidelines doc
@ -122,8 +118,7 @@ link:https://gerrit-review.googlesource.com/#/settings/http-password[HTTP
Password tab of the user settings page].
Style
-----
== Style
The basic coding style is covered by the tools/GoogleFormat.xml
doc, see the link:dev-eclipse.html#Formatting[Eclipse Setup]
@ -157,8 +152,7 @@ examples:
between internal ones.
Code Organization
-----------------
== Code Organization
Do your best to organize classes and methods in a logical way.
Here are some guidelines that Gerrit uses:
@ -191,8 +185,7 @@ Naturally new classes are a little harder; you may want to come
back and consult this section when creating them.
Design
------
== Design
Here are some design level objectives that you should keep in mind
when coding:
@ -224,14 +217,12 @@ when coding:
* ...and so is Guava (previously known as Google Collections).
Tests
-----
== Tests
* Tests for new code will greatly help your change get approved.
Change Size/Number of Files Touched
-----------------------------------
== Change Size/Number of Files Touched
And finally, I probably cannot say enough about change sizes.
Generally, smaller is better, hopefully within reason. Do try to
@ -269,11 +260,9 @@ especially if changing one without the other will break something!
* Use topic branches to link your separate changes together.
[[process]]
Process
-------
== Process
Backporting to stable branches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Backporting to stable branches
From time to time bug fix releases are made for existing stable branches.

72
Documentation/dev-design.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review - System Design
==================================
= Gerrit Code Review - System Design
Objective
---------
== Objective
Gerrit is a web based code review system, facilitating online code
reviews for projects using the Git version control system.
@ -17,8 +15,7 @@ hand by the project maintainer. This functionality enables a more
centralized usage of Git.
Background
----------
== Background
Google developed Mondrian, a Perforce based code review tool to
facilitate peer-review of changes prior to submission to the central
@ -74,8 +71,7 @@ on a J2EE servlet container and an SQL database.
* link:http://source.android.com/[Android Open Source Project]
Overview
--------
== Overview
Developers create one or more changes on their local desktop system,
then upload them for review to Gerrit using the standard `git push`
@ -121,8 +117,7 @@ are maintained, the user pressing the submit button does not need
to be the author of the change.
Infrastructure
--------------
== Infrastructure
End-user web browsers make HTTP requests directly to Gerrit's
HTTP server. As nearly all of the user interface is implemented
@ -184,8 +179,7 @@ has been migrated out of the database and into the git
repositories for each project.
Project Information
-------------------
== Project Information
Gerrit is developed as a self-hosting open source project:
@ -196,8 +190,7 @@ Gerrit is developed as a self-hosting open source project:
* link:https://review.source.android.com/[Change Review]
Internationalization and Localization
-------------------------------------
== Internationalization and Localization
As a source code review system for open source projects, where the
commonly preferred language for communication is typically English,
@ -220,8 +213,7 @@ before translating the UI to an RTL language.
* link:i18n-readme.html[Gerrit's i18n Support]
Accessibility Considerations
----------------------------
== Accessibility Considerations
Whenever possible Gerrit displays raw text rather than image icons,
so screen readers should still be able to provide useful information
@ -239,8 +231,7 @@ When possible, Gerrit uses the ARIA properties on DOM widgets to
provide hints to screen readers.
Browser Compatibility
---------------------
== Browser Compatibility
Supporting non-JavaScript enabled browsers is a non-goal for Gerrit.
@ -281,8 +272,7 @@ Therefore the lack of support for most search engine spiders is a
non-issue for most Gerrit deployments.
Product Integration
-------------------
== Product Integration
Gerrit integrates with an existing gitweb installation by optionally
creating hyperlinks to reference changes on the gitweb server.
@ -328,8 +318,7 @@ Gerrit does not integrate with any Google service, or any other
services other than those listed above.
Standards / Developer APIs
--------------------------
== Standards / Developer APIs
Gerrit uses an XSRF protected variant of JSON-RPC 1.1 to communicate
between the browser client and the server.
@ -356,8 +345,7 @@ to be used with the JSON-RPC interface.
* link:http://code.google.com/p/gerrit/source/browse/README?repo=gwtjsonrpc&name=master[XSRF JSON-RPC]
Privacy Considerations
----------------------
== Privacy Considerations
Gerrit stores the following information per user account:
@ -409,8 +397,7 @@ really left to the discretion of the Gerrit site administrator as
to when it is reasonable to reveal this information to a 3rd party.
Spam and Abuse Considerations
-----------------------------
== Spam and Abuse Considerations
Gerrit makes no attempt to detect spam changes or comments. The
somewhat high barrier to entry makes it unlikely that a spammer
@ -441,8 +428,7 @@ These assumptions may need to be revisited in the future if any
public Gerrit site actually notices spam.
Latency
-------
== Latency
Gerrit targets for sub-250 ms per page request, mostly by using
very compact JSON payloads between client and server. However, as
@ -451,8 +437,7 @@ database) is out of control of the Gerrit developers, no real
guarantees can be made about latency.
Scalability
-----------
== Scalability
Gerrit is designed for a very large scale open source project, or
large commercial development project. Roughly this amounts to
@ -477,8 +462,7 @@ to run closer to the estimated maximum if sufficient memory is made
available to the JVM and the relevant cache.*.memoryLimit variables
are increased from their defaults.
Discussion
~~~~~~~~~~
=== Discussion
Very few, if any open source projects have more than a handful of
Git repositories associated with them. Since Gerrit treats each
@ -548,8 +532,7 @@ less than 10 files modified in any single change. Changes larger than
version of an upstream library, where the reviewer has little to do
beyond verifying the project compiles and passes a test suite.
CPU Usage - Web UI
~~~~~~~~~~~~~~~~~~
=== CPU Usage - Web UI
Gerrit's web UI would require on average `4+F+F*C` HTTP requests to
review a change and post comments. Here `F` is the number of files
@ -581,8 +564,7 @@ Given a more realistic estimate of 79 changes per day (from the
Linux kernel) suggests only 8,532 queries per day, and a much lower
0.29 QPS when spread out over an 8 hour work day.
CPU Usage - Git over SSH/HTTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== CPU Usage - Git over SSH/HTTP
A 24 core server is able to handle ~25 concurrent `git fetch`
operations per second. The issue here is each concurrent operation
@ -609,8 +591,7 @@ If the server's own network interface is 1 Gib/sec (Gigabit Ethernet),
the system can really only serve about 10 concurrent clients at the
10 MiB/sec speed, no matter how many cores it has.
Disk Usage
~~~~~~~~~~
=== Disk Usage
The average size of a revision in the Linux kernel once compressed by
Git is 2,327 bytes, or roughly 2 KiB. Over the course of a year a
@ -630,8 +611,7 @@ clients from needing to clone unnecessary materials (for example a C
developer does not need every 800+ megabyte firmware image created by
the product's quality assurance team).
Redundancy & Reliability
------------------------
== Redundancy & Reliability
Gerrit largely assumes that the local filesystem where Git repository
data is stored is always available. Important data written to disk
@ -666,8 +646,7 @@ of time on the Gerrit site anyway in order to ensure any interested
parties around the world have had a chance to comment. This expected
lag largely allows for some downtime in a disaster scenario.
Backups
~~~~~~~
=== Backups
PostgreSQL and MySQL can be configured to replicate their data to
other systems, where they are applied to a warm-standby backup in
@ -683,8 +662,7 @@ to send copies of all changes over SSH to other servers, or to the
Amazon S3 blob storage service.
Logging Plan
------------
== Logging Plan
Gerrit does not maintain logs on its own.
@ -711,8 +689,7 @@ logs may be mined for usage information. This is outside of the
scope of Gerrit.
Testing Plan
------------
== Testing Plan
Gerrit is currently manually tested through its web UI.
@ -721,8 +698,7 @@ changes to JGit are rejected unless corresponding automated unit
tests are included.
Caveats
-------
== Caveats
Rietveld can't be used as it does not provide the "submit over the
web" feature that Gerrit provides for Git.

21
Documentation/dev-eclipse.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Eclipse Setup
==================================
= Gerrit Code Review - Eclipse Setup
This document is about configuring Gerrit Code Review into an
Eclipse workspace for development and debugging with GWT.
@ -9,8 +8,7 @@ runtime debugging environment.
[[Formatting]]
Code Formatter Settings
-----------------------
== Code Formatter Settings
Import `tools/GoogleFormat.xml` using Window -> Preferences ->
Java -> Code Style -> Formatter -> Import...
@ -19,8 +17,7 @@ This will define the 'Google Format' profile, which the project
settings prefer when formatting source code.
Site Initialization
-------------------
== Site Initialization
Build once on the command line with
link:dev-buck.html#build[Buck] and then follow
@ -28,11 +25,9 @@ link:dev-readme.html#init[Site Initialization] in the
Developer Setup guide to configure a local site for testing.
Testing
-------
== Testing
Running the Daemon
~~~~~~~~~~~~~~~~~~
=== Running the Daemon
Duplicate the existing launch configuration:
@ -52,8 +47,7 @@ Duplicate the existing launch configuration:
* Close the Debug Configurations dialog and save the changes when prompted.
Running Hosted Mode
~~~~~~~~~~~~~~~~~~~
=== Running Hosted Mode
Duplicate the existing launch configuration:
@ -74,8 +68,7 @@ Duplicate the existing launch configuration:
[[known-problems]]
Known problems
--------------
== Known problems
* OpenID authentication won't work in hosted mode, so you need to change
the link:config-gerrit.html#auth.type[auth.type] configuration parameter

30
Documentation/dev-inspector.txt
View File

@ -1,12 +1,9 @@
Gerrit Inspector
================
= Gerrit Inspector
NAME
----
== NAME
Gerrit Inspector - Interactive Jython environment for Gerrit
SYNOPSIS
--------
== SYNOPSIS
--
'java' -jar gerrit.war 'daemon'
-d <SITE_PATH>
@ -17,8 +14,7 @@ SYNOPSIS
-s
--
DESCRIPTION
-----------
== DESCRIPTION
Runs the Gerrit network daemon on the local system as described
in the link:pgm-daemon.html[Daemon documentation], additionally
starting an interactive Jython shell for inspection
@ -32,8 +28,7 @@ to introduce changes to the internal state of the system in
an inconsistent way. Care must be taken not to break the running system
and/or destroy the data.
INSTALLATION
------------
== INSTALLATION
Gerrit Inspector requires Jython library ('jython.jar') to be installed
in the '$site_path/lib' directory. Jython, a Python interpreter for
@ -42,8 +37,7 @@ website. Only 'jython.jar' file is needed, installation of Jython libraries
is optional. Gerrit Inspector has been tested with Jython 2.5.2 but
might work an earlier version.
STARTUP
-------
== STARTUP
During startup Jython examines Java libraries found on the classpath.
While libraries are inspected a large amount of messages is displayed on the console:
@ -77,8 +71,7 @@ the interactive interpreter.
When interactive interpreter exits (by issuing EOF on the command line),
a whole Gerrit instance is shut down gracefully.
USING THE INTERPRETER
---------------------
== USING THE INTERPRETER
Gerrit Inspector launches Jython interpreter in the context of the Gerrit
Java Virtual Machine. All core facilities of the Jython (and Python)
@ -219,8 +212,7 @@ And Gerrit should shut down all its subsystems and exit:
[2012-04-17 15:31:08,458] INFO com.google.gerrit.pgm.Daemon : caught shutdown, cleaning up
----
TROUBLESHOOTING
---------------
== TROUBLESHOOTING
Gerrit Inspector is logging to the Gerrit error log.
@ -281,16 +273,14 @@ by issuing the following command in the Gerrit Inspector console:
Shell.reload()
----
LOGGING
-------
== LOGGING
Error and warning messages from the server are automatically written
to the log file under '$site_path/logs/error_log'.
Output and error messages (including Java and Python exceptions)
resulting from interactive work are logged to the console.
KNOWN ISSUES
------------
== KNOWN ISSUES
The Inspector does not yet recognize Google Guice bindings.
IMPORTANT: Using the Inspector may void your warranty.

87
Documentation/dev-plugins.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Plugin Development
=======================================
= Gerrit Code Review - Plugin Development
The Gerrit server functionality can be extended by installing plugins.
This page describes how plugins for Gerrit can be developed.
@ -24,8 +23,7 @@ of server versions.
Most of this documentation refers to either type as a plugin.
[[getting-started]]
Getting started
---------------
== Getting started
To get started with the development of a plugin there are two
recommended ways:
@ -66,8 +64,7 @@ Gerrit version (no `SNAPSHOT` version) then the URL for the
`https://gerrit-api.storage.googleapis.com/release/`.
[[API]]
API
---
== API
There are two different API formats offered against which plugins can
be developed:
@ -88,8 +85,7 @@ gerrit-plugin-api.jar::
that compiles against 2.5 will probably need source code level
changes to work with 2.6, 2.7, and so on.
Manifest
--------
== Manifest
Plugins may provide optional description information with standard
manifest fields:
@ -101,8 +97,7 @@ manifest fields:
Implementation-URL: http://example.com/opensource/plugin-foo/
====
ApiType
~~~~~~~
=== ApiType
Plugins using the tightly coupled `gerrit-plugin-api.jar` must
declare this API dependency in the manifest to gain access to server
@ -114,8 +109,7 @@ loading a plugin that needs the plugin API.
Gerrit-ApiType: plugin
====
Explicit Registration
~~~~~~~~~~~~~~~~~~~~~
=== Explicit Registration
Plugins that use explicit Guice registration must name the Guice
modules in the manifest. Up to three modules can be named in the
@ -133,8 +127,7 @@ will be performed by scanning all classes in the plugin JAR for
====
[[plugin_name]]
Plugin Name
~~~~~~~~~~~
=== Plugin Name
A plugin can optionally provide its own plugin name.
@ -215,8 +208,7 @@ The canonical web URL may be injected into any .jar plugin regardless of
whether or not the plugin provides an HTTP servlet.
[[reload_method]]
Reload Method
~~~~~~~~~~~~~
=== Reload Method
If a plugin holds an exclusive resource that must be released before
loading the plugin again (for example listening on a network port or
@ -258,8 +250,7 @@ To reload/restart a plugin the link:cmd-plugin-reload.html[plugin reload]
command can be used.
[[init_step]]
Init step
~~~~~~~~~
=== Init step
Plugins can contribute their own "init step" during the Gerrit init
wizard. This is useful for guiding the Gerrit administrator through
@ -358,8 +349,7 @@ public class MyInitStep implements InitStep {
----
[[classpath]]
Classpath
---------
== Classpath
Each plugin is loaded into its own ClassLoader, isolating plugins
from each other. A plugin or extension inherits the Java runtime
@ -374,8 +364,7 @@ to package additional dependencies. Relocating (or renaming) classes
should not be necessary due to the ClassLoader isolation.
[[events]]
Listening to Events
-------------------
== Listening to Events
Certain operations in Gerrit trigger events. Plugins may receive
notifications of these events by implementing the corresponding
@ -404,8 +393,7 @@ Project deletion
Update of HEAD on a project
[[stream-events]]
Sending Events to the Events Stream
-----------------------------------
== Sending Events to the Events Stream
Plugins may send events to the events stream where consumers of
Gerrit's `stream-events` ssh command will receive them.
@ -415,8 +403,7 @@ methods in the `ChangeHookRunner` class, passing an instance of
its own custom event class derived from `ChangeEvent`.
[[ssh]]
SSH Commands
------------
== SSH Commands
Plugins may provide commands that can be accessed through the SSH
interface (extensions do not have this option).
@ -537,8 +524,7 @@ $ ssh -p 29418 review.example.com sh ps
----
[[simple-configuration]]
Simple Configuration in `gerrit.config`
---------------------------------------
== Simple Configuration in `gerrit.config`
In Gerrit, global configuration is stored in the `gerrit.config` file.
If a plugin needs global configuration, this configuration should be
@ -581,8 +567,7 @@ String language = cfg.getFromGerritConfig("helloworld")
----
[[configuration]]
Configuration in own config file
--------------------------------
== Configuration in own config file
Plugins can store their configuration in an own configuration file.
This makes sense if the plugin configuration is rather complex and
@ -624,8 +609,7 @@ Similar to changes in 'gerrit.config', changes to the plugin
configuration file will only become effective after a Gerrit restart.
[[simple-project-specific-configuration]]
Simple Project Specific Configuration in `project.config`
---------------------------------------------------------
== Simple Project Specific Configuration in `project.config`
In Gerrit, project specific configuration is stored in the project's
`project.config` file on the `refs/meta/config` branch. If a plugin
@ -688,8 +672,7 @@ Project owners can edit the project configuration by fetching the
pushing the commit back.
[[project-specific-configuration]]
Project Specific Configuration in own config file
-------------------------------------------------
== Project Specific Configuration in own config file
Plugins can store their project specific configuration in an own
configuration file in the projects `refs/meta/config` branch.
@ -744,8 +727,7 @@ Project owners can edit the project configuration by fetching the
`refs/meta/config` branch, editing the `<plugin-name>.config` file and
pushing the commit back.
React on changes in project configuration
-----------------------------------------
== React on changes in project configuration
If a plugin wants to react on changes in the project configuration, it
can implement a `GitReferenceUpdatedListener` and filter on events for
@ -789,8 +771,7 @@ public class MyListener implements GitReferenceUpdatedListener {
[[capabilities]]
Plugin Owned Capabilities
-------------------------
== Plugin Owned Capabilities
Plugins may provide their own capabilities and restrict usage of SSH
commands to the users who are granted those capabilities.
@ -879,8 +860,7 @@ this can be specified by setting `scope = CapabilityScope.CORE`:
----
[[ui_extension]]
UI Extension
------------
== UI Extension
Plugins can contribute UI actions on core Gerrit pages. This is useful
for workflow customization or exposing plugin functionality through the
@ -1148,8 +1128,7 @@ Gerrit.install(function(self) {
----
[[top-menu-extensions]]
Top Menu Extensions
-------------------
== Top Menu Extensions
Plugins can contribute items to Gerrit's top menu.
@ -1266,8 +1245,7 @@ public class MyTopMenuExtension implements TopMenu {
----
[[gwt_ui_extension]]
GWT UI Extension
----------------
== GWT UI Extension
Plugins can extend the Gerrit UI with own GWT code.
The Maven archetype 'gerrit-plugin-gwt-archetype' can be used to
@ -1521,8 +1499,7 @@ In order to be able to do REST calls the GWT module must inherit
----
[[http]]
HTTP Servlets
-------------
== HTTP Servlets
Plugins or extensions may register additional HTTP servlets, and
wrap them with HTTP filters.
@ -1572,8 +1549,7 @@ $ curl http://review.example.com/plugins/helloworld/print
----
[[data-directory]]
Data Directory
--------------
== Data Directory
Plugins can request a data directory with a `@PluginData` File
dependency. A data directory will be created automatically by the
@ -1590,8 +1566,7 @@ MyType(@PluginData java.io.File myDir) {
----
[[download-commands]]
Download Commands
-----------------
== Download Commands
Gerrit offers commands for downloading changes using different
download schemes (e.g. for downloading via different network
@ -1604,8 +1579,7 @@ The download schemes and download commands which are used most often
are provided by the Gerrit core plugin `download-commands`.
[[documentation]]
Documentation
-------------
== Documentation
If a plugin does not register a filter or servlet to handle URLs
`/Documentation/*` or `/static/*`, the core Gerrit server will
@ -1648,8 +1622,7 @@ Macros that start with `\` such as `\@KEEP@` will render as `@KEEP@`
even if there is an expansion for `KEEP` in the future.
[[auto-index]]
Automatic Index
~~~~~~~~~~~~~~~
=== Automatic Index
If a plugin does not handle its `/` URL itself, Gerrit will
redirect clients to the plugin's `/Documentation/index.html`.
@ -1701,8 +1674,7 @@ displayed as part of the index page, if present in the manifest:
|===================================================
[[deployment]]
Deployment
----------
== Deployment
Compiled plugins and extensions can be deployed to a running Gerrit
server using the link:cmd-plugin-install.html[plugin install] command.
@ -1724,8 +1696,7 @@ command can be used.
Disabled plugins can be re-enabled using the
link:cmd-plugin-enable.html[plugin enable] command.
SEE ALSO
--------
== SEE ALSO
* link:js-api.html[JavaScript API]
* link:dev-rest-api.html[REST API Developers' Notes]

51
Documentation/dev-readme.txt
View File

@ -1,13 +1,11 @@
Gerrit Code Review - Developer Setup
====================================
= Gerrit Code Review - Developer Setup
Facebook Buck is needed to compile the code, and an SQL database to
house the review metadata. H2 is recommended for development
databases, as it requires no external server process.
Getting the Source
------------------
== Getting the Source
Create a new client workspace:
@ -21,15 +19,13 @@ the core plugins, which are included as git submodules, are also
cloned.
Compiling
---------
== Compiling
For details on how to build the source code with Buck, refer to:
link:dev-buck.html#build[Building on the command line with Buck].
Switching between branches
--------------------------
== Switching between branches
When switching between branches with `git checkout`, be aware that
submodule revisions are not altered. This may result in the wrong
@ -45,8 +41,7 @@ revisions for the new branch with the commands:
----
Configuring Eclipse
-------------------
== Configuring Eclipse
To use the Eclipse IDE for development, please see
link:dev-eclipse.html[Eclipse Setup].
@ -55,8 +50,7 @@ For details on how to configure the Eclipse workspace with Buck,
refer to: link:dev-buck.html#eclipse[Eclipse integration with Buck].
Mac OS X
--------
== Mac OS X
On Mac OS X ensure "Java For Mac OS X 10.5 Upate 4" (or later) has
been installed, and that `JAVA_HOME` is set to
@ -67,8 +61,7 @@ version crash during the build due to a bug in the JIT compiler.
[[init]]
Site Initialization
-------------------
== Site Initialization
After compiling (above), run Gerrit's 'init' command to create a
testing site for development use:
@ -93,13 +86,11 @@ through the web interface:
----
Testing
-------
== Testing
[[tests]]
Running the Acceptance Tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Running the Acceptance Tests
Gerrit has a set of integration tests that test the Gerrit daemon via
REST, SSH and the git protocol.
@ -113,8 +104,7 @@ please refer to:
link:dev-buck.html#tests[Running integration tests with Buck].
Running the Daemon
~~~~~~~~~~~~~~~~~~
=== Running the Daemon
The daemon can be directly launched from the build area, without
copying to the test site:
@ -123,8 +113,7 @@ copying to the test site:
java -jar buck-out/gen/gerrit.war daemon -d ../gerrit_testsite
----
Running the Daemon with Gerrit Inspector
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Running the Daemon with Gerrit Inspector
link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable
environment to inspect and modify internal state of the system.
@ -161,8 +150,7 @@ interfaces (HTTP, SSH etc.) are available.
Care must be taken not to modify internal state of the system
when using the Inspector.
Querying the Database
~~~~~~~~~~~~~~~~~~~~~
=== Querying the Database
The embedded H2 database can be queried and updated from the
command line. If the daemon is not currently running:
@ -180,8 +168,7 @@ using an administrator user account:
[[debug-javascript]]
Debugging JavaScript
~~~~~~~~~~~~~~~~~~~~
=== Debugging JavaScript
When debugging browser specific issues add `?dbg=1` to the URL so the
resulting JavaScript more closely matches the Java sources. The debug
@ -200,8 +187,7 @@ To use the GWT DETAILED style the package must be recompiled and
----
Release Builds
--------------
== Release Builds
To create a release build for a production server, or deployment
through the download site:
@ -219,8 +205,7 @@ an additional flag:
----
Client-Server RPC
-----------------
== Client-Server RPC
The client-server RPC implementation is gwtjsonrpc, not the stock RPC
system that comes with GWT. This buys us automatic XSRF protection.
@ -231,15 +216,13 @@ The programming API is virtually identical, except service interfaces
extend RemoteJsonService instead of RemoteService.
Why GWT?
--------
== Why GWT?
We like it. Plus we can write Java code once and run it both in
the browser and on the server side.
External Links
--------------
== External Links
Google Web Toolkit:

9
Documentation/dev-release-deploy-config.txt
View File

@ -1,5 +1,4 @@
Deploy Gerrit Artifacts
=======================
= Deploy Gerrit Artifacts
Gerrit Artifacts are stored on
link:https://developers.google.com/storage/[Google Cloud Storage].
@ -17,8 +16,7 @@ Jar.
Bucket to store Gerrit Subproject Artifacts (e.g. `gwtjsonrpc` etc.).
[[deploy-configuration-settings-xml]]
Deploy Configuration in Maven `settings.xml`
--------------------------------------------
== Deploy Configuration in Maven `settings.xml`
To upload artifacts to a bucket the user must authenticate with a
username and password. The username and password need to be retrieved
@ -58,8 +56,7 @@ configured in the `~/.m2/settings.xml` file.
----
[[deploy-configuration-subprojects]]
Gerrit Subprojects
~~~~~~~~~~~~~~~~~~
=== Gerrit Subprojects
* You will need to have the following in the `pom.xml` to make it
deployable to the `gerrit-maven` storage bucket:

15
Documentation/dev-release-subproject.txt
View File

@ -1,9 +1,7 @@
Making a Release of a Gerrit Subproject
=======================================
= Making a Release of a Gerrit Subproject
[[make-snapshot]]
Make a Snapshot
---------------
== Make a Snapshot
* Build the latest snapshot and install it into the local Maven
repository:
@ -15,8 +13,7 @@ repository:
* Test Gerrit with this snapshot locally
Publish Snapshot
----------------
== Publish Snapshot
If a snapshot for a subproject was created that should be referenced by
Gerrit while current Gerrit development is ongoing, this snapshot needs
@ -42,8 +39,7 @@ and Gerrit has to reference the released subproject version.
[[prepare-release]]
Prepare the Release
-------------------
== Prepare the Release
* link:#make-snapshot[First create (and test) the latest snapshot for
the subproject]
@ -66,8 +62,7 @@ below)
[[publish-release]]
Publish the Release
-------------------
== Publish the Release
* Make sure you have done the configuration needed for deployment:
** link:dev-release-deploy-config.html#deploy-configuration-settings-xml[

54
Documentation/dev-release.txt
View File

@ -1,5 +1,4 @@
Making a Gerrit Release
=======================
= Making a Gerrit Release
[NOTE]
========================================================================
@ -16,16 +15,14 @@ and as a checklist for those already familiar with these
tasks.
Gerrit Release Type
-------------------
== Gerrit Release Type
Here are some guidelines on release approaches depending on the
type of release you want to make (`stable-fix`, `stable`, `RC0`,
`RC1`...).
[[stable]]
Stable
~~~~~~
=== Stable
A `stable` release is generally built from the `master` branch and may
need to undergo some stabilization before releasing the final release.
@ -51,8 +48,7 @@ There should be no new features in this release, only bug fixes
* Finally create the `stable` release (no `RC`)
Stable-Fix
~~~~~~~~~~
=== Stable-Fix
`stable-fix` releases should likely only contain bug fixes and doc
updates.
@ -64,8 +60,7 @@ objectives are met
[[security]]
Security-Fix
~~~~~~~~~~~~
=== Security-Fix
`security-fix` releases should only contain bug fixes for security
issues.
@ -82,8 +77,7 @@ the `gerrit-security-fixes` project be taken over into the public
`gerrit` project.
Create the Actual Release
-------------------------
== Create the Actual Release
To create a Gerrit release the following steps have to be done:
@ -102,8 +96,7 @@ To create a Gerrit release the following steps have to be done:
[[subproject]]
Release Subprojects
~~~~~~~~~~~~~~~~~~~
=== Release Subprojects
The subprojects to be released are:
@ -128,8 +121,7 @@ for the Subproject in `/lib/BUCK` to the released version.
[[build-gerrit]]
Build Gerrit
~~~~~~~~~~~~
=== Build Gerrit
* Build the Gerrit WAR and API JARs
+
@ -142,13 +134,11 @@ Build Gerrit
* Test the new Gerrit version
[[publish-gerrit]]
Publish the Gerrit Release
~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Publish the Gerrit Release
[[extension-and-plugin-api]]
Publish the Extension and Plugin API Jars
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== Publish the Extension and Plugin API Jars
* Make sure you have done the
link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
@ -162,16 +152,14 @@ configuration needed for deployment]
[[publish-gerrit-war]]
Publish the Gerrit WAR (with Core Plugins)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==== Publish the Gerrit WAR (with Core Plugins)
* The WAR file to upload is `buck-out/gen/release.war`
* Upload WAR to the storage bucket via `https://cloud.google.com/console` (manual via web browser)
[[push-stable]]
Push the Stable Branch
^^^^^^^^^^^^^^^^^^^^^^
==== Push the Stable Branch
* create the stable branch `stable-2.5` in the `gerrit` project
+
@ -183,8 +171,7 @@ get them merged
[[push-tag]]
Push the Release Tag
^^^^^^^^^^^^^^^^^^^^
==== Push the Release Tag
* Push the new Release Tag
+
@ -202,8 +189,7 @@ For a final `stable` release:
[[upload-documentation]]
Upload the Documentation
^^^^^^^^^^^^^^^^^^^^^^^^
==== Upload the Documentation
Build the release notes:
@ -221,8 +207,7 @@ Description text, and in the `Links` section.
Description text
[[update-issues]]
Update the Issues
^^^^^^^^^^^^^^^^^
==== Update the Issues
====
How do the issues get updated? Do you run a script to do
@ -242,8 +227,7 @@ because `Status=Submitted` is considered a closed issue.
[[announce]]
Announce on Mailing List
^^^^^^^^^^^^^^^^^^^^^^^^
==== Announce on Mailing List
* Send an email to the mailing list to announce the release, consider
including some or all of the following in the email:
@ -295,8 +279,7 @@ To read more about the bug fixes:
[[increase-version]]
Increase Gerrit Version for Current Development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Increase Gerrit Version for Current Development
All new development that is done in the `master` branch will be
included in the next Gerrit release. Update the Gerrit version in the
@ -305,8 +288,7 @@ for review and get it merged.
[[merge-stable]]
Merge `stable` into `master`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Merge `stable` into `master`
After every release, stable should be merged to master to ensure that
none of the changes/fixes ever get lost.

18
Documentation/dev-rest-api.txt
View File

@ -1,17 +1,14 @@
Gerrit Code Review - REST API Developers' Notes
===============================================
= Gerrit Code Review - REST API Developers' Notes
This document is about developing the REST API. For details of the
actual APIs available in Gerrit, please see the
link:rest-api.html[REST API interface reference].
Testing REST API Functionality
------------------------------
== Testing REST API Functionality
Basic Testing
~~~~~~~~~~~~~
=== Basic Testing
Basic testing of REST API functionality can be done with `curl`:
@ -29,8 +26,7 @@ or `DELETE`, an additional argument is required:
----
Sending Data in the Request
~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Sending Data in the Request
Some REST APIs accept data in the request body of `PUT` and `POST` requests.
@ -49,8 +45,7 @@ option instead:
----
Authentication
~~~~~~~~~~~~~~
=== Authentication
To test APIs that require authentication, the username and password must be specified on
the command line:
@ -71,8 +66,7 @@ file (on Windows, `_netrc`):
In both cases, the password should be the user's link:user-upload.html#http[HTTP password].
Verifying Header Content
~~~~~~~~~~~~~~~~~~~~~~~~
=== Verifying Header Content
To verify the headers returned from a REST API call, use `curl` in verbose mode:

3
Documentation/error-branch-not-found.txt
View File

@ -1,5 +1,4 @@
branch ... not found
====================
= branch ... not found
With this error message Gerrit rejects to push a commit for code
review if the specified target branch does not exist.

9
Documentation/error-change-closed.txt
View File

@ -1,11 +1,9 @@
change ... closed
=================
= change ... closed
With this error message Gerrit rejects to push a commit or submit a
review label (approval) to a change that is already closed.
When Pushing a Commit
---------------------
== When Pushing a Commit
This error occurs if you are trying to push a commit that contains
the Change-Id of a closed change in its commit message. A change can
@ -27,8 +25,7 @@ this change you may want to restore the change in the Gerrit WebUI
'Restore Change' button). Afterwards the push should succeed and a
new patch set for this change will be created.
When Submitting a Review Label
------------------------------
== When Submitting a Review Label
This error occurs if you are trying to submit a review label (approval) using
the link:cmd-review.html[ssh review command] after the change has been closed.

3
Documentation/error-change-does-not-belong-to-project.txt
View File

@ -1,5 +1,4 @@
change ... does not belong to project ...
=========================================
= change ... does not belong to project ...
With this error message Gerrit rejects to push a commit to a change
that belongs to another project.

3
Documentation/error-change-not-found.txt
View File

@ -1,5 +1,4 @@
change ... not found
====================
= change ... not found
With this error message Gerrit rejects to push a commit to a change
that cannot be found.

3
Documentation/error-change-upload-blocked.txt
View File

@ -1,5 +1,4 @@
One or more refs/for/ names blocks change upload
================================================
= One or more refs/for/ names blocks change upload
With this error message Gerrit rejects to push a commit for code
review if the remote git repository has a branch under the

3
Documentation/error-commit-already-exists.txt
View File

@ -1,5 +1,4 @@
commit already exists
=====================
= commit already exists
With this error message Gerrit rejects to push a commit to an
existing change via `refs/changes/n` if the commit was already

3
Documentation/error-contains-banned-commit.txt
View File

@ -1,5 +1,4 @@
contains banned commit ...
==========================
= contains banned commit ...
With this error message Gerrit rejects to push a commit that is
banned or that would merge in an ancestor that is banned.

3
Documentation/error-has-duplicates.txt
View File

@ -1,5 +1,4 @@
\... has duplicates
===================
= \... has duplicates
With this error message Gerrit rejects to push a commit if its commit
message contains a Change-ID for which multiple changes can be found

15
Documentation/error-invalid-author.txt
View File

@ -1,5 +1,4 @@
invalid author
==============
= invalid author
For every pushed commit Gerrit verifies that the e-mail address of
the author matches one of the registered e-mail addresses of the
@ -14,8 +13,7 @@ This error may happen for two reasons:
. missing privileges to push commits of other authors
Incorrect configuration of the e-mail address on client or server side
----------------------------------------------------------------------
== Incorrect configuration of the e-mail address on client or server side
If pushing to Gerrit fails with the error message "invalid author"
and you are the author of the commit for which the push
@ -23,8 +21,7 @@ fails, then either you have not successfully registered this e-mail
address for your Gerrit account or the author information of the
pushed commit is incorrect.
Configuration of e-mail address in Gerrit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Configuration of e-mail address in Gerrit
Check in Gerrit under 'Settings -> Identities' which e-mail addresses
you've configured for your Gerrit account. If no e-mail address is
@ -34,8 +31,7 @@ clicking on the link in the e-mail verification mail sent by Gerrit.
If you don't receive the e-mail verification mail it might be that it
was caught by your spam filter.
Incorrect author information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Incorrect author information
For every commit Git maintains the author. If not explicitly
specified Git computes the author on commit out of the Git
@ -128,8 +124,7 @@ For further details about git rebase please check the
link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation].
Missing privileges to push commits of other users
-------------------------------------------------
== Missing privileges to push commits of other users
If pushing to Gerrit fails with the error message "invalid author"
and somebody else is author of the commit for which the

6
Documentation/error-invalid-changeid-line.txt
View File

@ -1,5 +1,4 @@
invalid Change-Id line format in commit message footer
======================================================
= invalid Change-Id line format in commit message footer
With this error message Gerrit rejects to push a commit if its commit
message footer contains an invalid Change-Id line.
@ -20,8 +19,7 @@ link:error-push-fails-due-to-commit-message.html#commit_hook[here]. In case you
Change-Id will be automatically generated and inserted.
SEE ALSO
--------
== SEE ALSO
* link:user-changeid.html[Change-Id Lines]

15
Documentation/error-invalid-committer.txt
View File

@ -1,5 +1,4 @@
invalid committer
=================
= invalid committer
For every pushed commit Gerrit verifies that the e-mail address of
the committer matches one of the registered e-mail addresses of the
@ -16,8 +15,7 @@ This error may happen for two reasons:
users
Incorrect configuration of the e-mail address on client or server side
----------------------------------------------------------------------
== Incorrect configuration of the e-mail address on client or server side
If pushing to Gerrit fails with the error message "invalid committer"
and you committed the change for which the push fails,
@ -25,8 +23,7 @@ then either you have not successfully registered this e-mail address
for your Gerrit account or the committer information of the pushed
commit is incorrect.
Configuration of e-mail address in Gerrit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Configuration of e-mail address in Gerrit
Check in Gerrit under 'Settings -> Identities' which e-mail addresses
you've configured for your Gerrit account. If no e-mail address is
@ -34,8 +31,7 @@ registered go to 'Settings -> Contact Information' and register a new
e-mail address there. Make sure you confirm your e-mail address by
clicking on the link in the e-mail verification mail sent by Gerrit.
Incorrect committer information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=== Incorrect committer information
For every commit Git maintains the user who did the commit, the so
called committer. Git computes the committer out of the Git
@ -93,8 +89,7 @@ rewritten. For further details about git rebase please check the
link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation].
Missing privileges to push commits that were committed by other users
---------------------------------------------------------------------
== Missing privileges to push commits that were committed by other users
If pushing to Gerrit fails with the error message "invalid committer"
and somebody else committed the change for which the

9
Documentation/error-messages.txt
View File

@ -1,13 +1,11 @@
Gerrit Code Review - Error Messages
===================================
= Gerrit Code Review - Error Messages
This page provides access to detailed explanations of Gerrit error
messages. For each error message it is explained why the error is
occurring and what can be done to solve it.
Error Messages
--------------
== Error Messages
* link:error-branch-not-found.html[branch ... not found]
* link:error-change-closed.html[change ... closed]
@ -38,8 +36,7 @@ Error Messages
* link:error-not-allowed-to-upload-merges.html[you are not allowed to upload merges]
General Hints
-------------
== General Hints
* link:error-push-fails-due-to-commit-message.html[push fails due to commit message]

12
Documentation/error-missing-changeid.txt
View File

@ -1,5 +1,4 @@
missing Change-Id in commit message footer
==========================================
= missing Change-Id in commit message footer
With this error message Gerrit rejects to push a commit to a project
which is configured to always require a Change-Id in the commit
@ -21,8 +20,7 @@ automatically create and insert a unique Change-Id into the commit
message on every commit.
Missing Change-Id in the commit message
---------------------------------------
== Missing Change-Id in the commit message
If the commit message of a commit that you want to push does not
contain a Change-Id you have to update its commit message and insert
@ -41,8 +39,7 @@ insert it into the commit message. How to update the commit message
is explained link:error-push-fails-due-to-commit-message.html[here].
Change-Id is contained in the commit message but not in the last paragraph
--------------------------------------------------------------------------
== Change-Id is contained in the commit message but not in the last paragraph
To be picked up by Gerrit, a Change-Id must be in the last paragraph
of a commit message, for details, see link:user-changeid.html[Change-Id Lines].
@ -52,8 +49,7 @@ last paragraph you have to update the commit message and move the
Change-ID into the last paragraph. How to update the commit message
is explained link:error-push-fails-due-to-commit-message.html[here].
Change-Id is the only line in the commit message
------------------------------------------------
== Change-Id is the only line in the commit message
Gerrit does not parse the subject of a commit message for the
Change-Id even if this is the only and last paragraph of the commit

6
Documentation/error-multiple-changeid-lines.txt
View File

@ -1,5 +1,4 @@
multiple Change-Id lines in commit message footer
=================================================
= multiple Change-Id lines in commit message footer
With this error message Gerrit rejects to push a commit if the commit
message footer of the pushed commit contains several Change-Id lines.
@ -20,8 +19,7 @@ link:error-push-fails-due-to-commit-message.html#commit_hook[here]. In case you
will be automatically generated and inserted.
SEE ALSO
--------
== SEE ALSO
* link:user-changeid.html[Change-Id Lines]

3
Documentation/error-no-changes-made.txt
View File

@ -1,5 +1,4 @@
no changes made
===============
= no changes made
With this error message Gerrit rejects to push a commit as a new
patch set for a change, if the pushed commit is identical to the

3
Documentation/error-no-common-ancestry.txt
View File

@ -1,5 +1,4 @@
no common ancestry
==================
= no common ancestry
With this error message Gerrit rejects to push a commit for code
review if the pushed commit and the commit at the tip of the target

3
Documentation/error-no-new-changes.txt
View File

@ -1,5 +1,4 @@
no new changes
==============
= no new changes
With this error message Gerrit rejects to push a commit if the pushed
commit was already successfully pushed to Gerrit. In this case there

9
Documentation/error-non-fast-forward.txt
View File

@ -1,5 +1,4 @@
non-fast forward
================
= non-fast forward
With this error message Gerrit rejects a push if the remote branch can't
be fast forwarded onto the pushed commit. This is the case if the
@ -20,8 +19,7 @@ There are different reasons why this error can occur:
. you are pushing the commit to the wrong project
the remote branch has evolved since you started your development
----------------------------------------------------------------
== the remote branch has evolved since you started your development
You start your development based on the current tip of the remote
branch. While you implement your feature / bug-fix, a change in Gerrit
@ -36,8 +34,7 @@ message 'non-fast forward'. To solve the problem you have to either
Afterwards the push should be successful.
you are pushing the commit to the wrong project
-----------------------------------------------
== you are pushing the commit to the wrong project
If you do a commit in one project and then accidentally push this
commit, with bypassing code review, to another project, this will fail

3
Documentation/error-not-a-gerrit-administrator.txt
View File

@ -1,5 +1,4 @@
Not a Gerrit administrator
==========================
= Not a Gerrit administrator
With this error message Gerrit rejects to execute an SSH command that
requires administrator privileges if the user is not a Gerrit

3
Documentation/error-not-allowed-to-upload-merges.txt
View File

@ -1,5 +1,4 @@
you are not allowed to upload merges
====================================
= you are not allowed to upload merges
With this error message Gerrit rejects to push a merge commit if the
pushing user has no permission to upload merge commits for the

3
Documentation/error-not-permitted-to-create.txt
View File

@ -1,5 +1,4 @@
Not permitted to create ...
===========================
= Not permitted to create ...
With this error message Gerrit rejects to create a new project in
Gerrit if the user has no privileges for project creation.

3
Documentation/error-not-signed-off-by.txt
View File

@ -1,5 +1,4 @@
not Signed-off-by author/committer/uploader in commit message footer
====================================================================
= not Signed-off-by author/committer/uploader in commit message footer
Projects in Gerrit can be configured to require a link:user-signedoffby.html#Signed-off-by[Signed-off-by] in
the footer of the commit message to enforce that every change is signed by the

9
Documentation/error-not-valid-ref.txt
View File

@ -1,5 +1,4 @@
not valid ref
=============
= not valid ref
With this error message Gerrit rejects to push a commit if the target
ref in the push specification has an incorrect format (for example:
@ -10,8 +9,7 @@ specification. Depending on whether you want to push your commit with
or without code review the ref format is different:
ref format for pushing a commit for code review:
------------------------------------------------
== ref format for pushing a commit for code review:
If it was the intention to push a commit for code review the target
ref in the push specification must be the project's magical ref
@ -26,8 +24,7 @@ $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
----
ref format for directly pushing a commit (without code review):
---------------------------------------------------------------
== ref format for directly pushing a commit (without code review):
If it was the intention to bypass code review and to push directly to
a branch the target ref in the push specification must be the name of

6
Documentation/error-permission-denied.txt
View File

@ -1,5 +1,4 @@
Permission denied (publickey)
=============================
= Permission denied (publickey)
With this error message an SSH command to Gerrit is rejected if the
SSH authentication is not successful.
@ -23,8 +22,7 @@ If you are facing this problem, do the following:
key is used.
Test SSH authentication
-----------------------
== Test SSH authentication
To test the SSH authentication you can run the following SSH command.
This command will print out a detailed trace which is helpful to

3
Documentation/error-prohibited-by-gerrit.txt
View File

@ -1,5 +1,4 @@
prohibited by Gerrit
====================
= prohibited by Gerrit
This is a general error message that is returned by Gerrit if a push
is not allowed, e.g. because the pushing user has no sufficient

3
Documentation/error-project-not-found.txt
View File

@ -1,5 +1,4 @@
Project not found: ...
======================
= Project not found: ...
With this error message Gerrit rejects to push a commit if the git
repository to which the push is done does not exist as a project in

3
Documentation/error-push-fails-due-to-commit-message.txt
View File

@ -1,5 +1,4 @@
Push fails due to commit message
================================
= Push fails due to commit message
If Gerrit rejects pushing a commit it is often the case that there is
an issue with the commit message of the pushed commit. In this case

6
Documentation/error-squash-commits-first.txt
View File

@ -1,5 +1,4 @@
squash commits first
====================
= squash commits first
With this error message Gerrit rejects to push a commit if it
contains the same Change-ID as a predecessor commit.
@ -19,8 +18,7 @@ changes to be reviewed and accidentally included the same Change-ID
into the different commit messages.
Example
-------
== Example
Here an example about how the push is failing. Please note that the
two commits 'one commit' and 'another commit' both have the same

9
Documentation/i18n-readme.txt
View File

@ -1,19 +1,16 @@
Gerrit Code Review - i18n
=========================
= Gerrit Code Review - i18n
Aside from actually writing translations, there are some issues with
the way the code produces output. Most of the UI should support
right-to-left (RTL) languages.
Labels
------
== Labels
Labels and their values are defined in project.config by the Gerrit
administrator or project owners. Only a single translation of these
strings is supported.
/Gerrit Gerrit.html
-------------------
== /Gerrit Gerrit.html
* The title of the host page is not translated.

24
Documentation/index.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review for Git
==========================
= Gerrit Code Review for Git
Tutorial
--------
== Tutorial
. Getting started
.. link:intro-quick.html[A Quick Introduction to Gerrit]
.. link:intro-change-screen.html[A Quick Introduction to the New Change Screen]
@ -24,8 +22,7 @@ Tutorial
... link:user-signedoffby.html[Signed-off-by Lines]
.. Patch sets
Project Management
------------------
== Project Management
. link:project-setup.html[Project Setup]
. link:access-control.html[Access Controls]
.. link:config-labels.html[Review Labels]
@ -39,8 +36,7 @@ Project Management
. link:user-submodules.html[Subscribing to Git Submodules]
. Project sunset
Customization and Integration
-----------------------------
== Customization and Integration
. link:user-dashboards.html[Dashboards]
. link:rest-api.html[REST API]
. link:config-gitweb.html[Gitweb Integration]
@ -50,8 +46,7 @@ Customization and Integration
. link:config-mail.html[Mail Templates]
. link:config-cla.html[Contributor Agreements]
Server Administration
---------------------
== Server Administration
. link:install.html[Installation Guide]
. link:config-gerrit.html[System Settings]
. Backup
@ -68,8 +63,7 @@ Server Administration
. link:config-auto-site-initialization.html[Automatic Site Initialization on Startup]
. link:pgm-index.html[Server Side Administrative Tools]
Developer
---------
== Developer
. link:dev-readme.html[Developer Setup]
. link:dev-buck.html[Building with Buck]
. link:dev-eclipse.html[Eclipse Setup]
@ -82,13 +76,11 @@ Developer
.. link:js-api.html[JavaScript Plugin API]
.. link:config-validation.html[Commit Validation]
Maintainer
----------
== Maintainer
. link:dev-release.html[Developer Release]
. link:dev-release-subproject.html[Developer Subproject Release]
Resources
---------
== Resources
* link:licenses.html[Licenses and Notices]
* link:http://code.google.com/p/gerrit/[Homepage]
* link:http://code.google.com/p/gerrit/downloads/list[Downloads]

12
Documentation/install-j2ee.txt
View File

@ -1,8 +1,6 @@
Gerrit Code Review - J2EE Installation
======================================
= Gerrit Code Review - J2EE Installation
Description
-----------
== Description
Gerrit binary distributions include a standalone Jetty servlet
container, but are packaged as a standard WAR file to permit easy
@ -14,8 +12,7 @@ including popular open source containers such as Jetty or Tomcat, or
any commercial server which supports the J2EE servlet specification.
Installation
------------
== Installation
* Complete the link:install.html#createdb[database setup] and
link:install.html#init[site initialization] tasks described
@ -50,8 +47,7 @@ directory so it's available to Gerrit Code Review.
Configure Automatic Site Initialization on Startup]
Jetty 7.x
---------
== Jetty 7.x
These directions will configure Gerrit as the default web
application, allowing URLs like `http://example.com/4543` to jump
directly to change 4543.

30
Documentation/install-quick.txt
View File

@ -1,5 +1,4 @@
Gerrit Code Review - Quick get started guide
============================================
= Gerrit Code Review - Quick get started guide
****
This guide was made with the impatient in mind, ready to try out Gerrit on their
@ -21,8 +20,7 @@ OpenID provider you choose is necessary for both you and your Gerrit instance.
[[requirements]]
Requirements
------------
== Requirements
Most distributions come with Java today. Do you already have Java installed?
@ -39,8 +37,7 @@ If Java isn't installed, get it:
[[user]]
Create a user to host the Gerrit service
----------------------------------------
== Create a user to host the Gerrit service
We will run the service as a non-privileged user on your system.
First create the user and then become the user:
@ -55,8 +52,7 @@ as your own user as well.
[[download]]
Download Gerrit
---------------
== Download Gerrit
It's time to download the archive that contains the Gerrit web and ssh service.
@ -70,8 +66,7 @@ This tutorial is based on version 2.2.2, and you can download that from this lin
[[initialization]]
Initialize the Site
-------------------
== Initialize the Site
It's time to run the initialization, and with the batch switch enabled, we don't have to answer any questions at all:
@ -111,16 +106,14 @@ commands to gerrit.sh.
include::config-login-register.txt[]
Project creation
----------------
== Project creation
Your base Gerrit server is now running and you have a user that's ready
to interact with it. You now have two options, either you create a new
test project to work with or you already have a git with history that
you would like to import into Gerrit and try out code review on.
New project from scratch
~~~~~~~~~~~~~~~~~~~~~~~~
=== New project from scratch
If you choose to create a new repository from scratch, it's easier for
you to create a project with an initial commit in it. That way first
time setup between client and server is easier.
@ -134,8 +127,7 @@ This is done via the SSH port:
This will create a repository that you can clone to work with.
Already existing project
~~~~~~~~~~~~~~~~~~~~~~~~
=== Already existing project
The other alternative is if you already have a git project that you
want to try out Gerrit on.
@ -166,8 +158,7 @@ After that it's time to upload the previous history to the server:
This will create a repository that you can clone to work with.
My first change
---------------
== My first change
Download a local clone of the repository and move into it
@ -216,8 +207,7 @@ You should now be able to access your change by browsing to the http URL
suggested above, http://localhost:8080/1
Quick Installation Complete
---------------------------
== Quick Installation Complete
This covers the scope of getting Gerrit started and your first change uploaded.
It doesn't give any clue as to how the review workflow works, please read

33
Documentation/install.txt
View File

@ -1,9 +1,7 @@
Gerrit Code Review - Standalone Daemon Installation Guide
=========================================================
= Gerrit Code Review - Standalone Daemon Installation Guide
[[requirements]]
Requirements
------------
== Requirements
To run the Gerrit service, the following requirements must be met on
the host:
@ -14,8 +12,7 @@ choice of either using the embedded H2 or to host your own MySQL or PostgreSQL.
[[download]]
Download Gerrit
---------------
== Download Gerrit
Current and past binary releases of Gerrit can be obtained from
the link:https://gerrit-releases.storage.googleapis.com/index.html[
@ -31,8 +28,7 @@ the notes under link:dev-readme.html[developer setup].
include::database-setup.txt[]
[[init]]
Initialize the Site
-------------------
== Initialize the Site
Gerrit stores configuration files, the server's SSH keys, and the
managed Git repositories under a local directory, typically referred
@ -90,8 +86,7 @@ permitting server management over the web and over SSH. Subsequent
users will be automatically registered as unprivileged users.
Installation Complete
---------------------
== Installation Complete
Your base Gerrit server is now installed and running. You're now ready to
either set up more projects or start working with the projects you've already
@ -99,8 +94,7 @@ imported.
[[project_setup]]
Project Setup
-------------
== Project Setup
See link:project-setup.html[Project Setup] for further details on
how to register a new project with Gerrit. This step is necessary
@ -108,8 +102,7 @@ if existing Git repositories were not imported during 'init'.
[[rc_d]]
Start/Stop Daemon
-----------------
== Start/Stop Daemon
To control the Gerrit Code Review daemon that is running in the
background, use the rc.d style start script created by 'init':
@ -149,8 +142,7 @@ link:install-j2ee.html[J2EE installation].
[[customize]]
Site Customization
------------------
== Site Customization
Gerrit Code Review supports some site-specific customization options.
For more information, see the related topics in this manual:
@ -164,8 +156,7 @@ For more information, see the related topics in this manual:
[[anonymous_access]]
Anonymous Access
----------------
== Anonymous Access
Exporting the Git repository directory
(link:config-gerrit.html#gerrit.basePath[gerrit.basePath]) over the
@ -177,14 +168,12 @@ for details on how to configure this if anonymous access is desired.
[[plugins]]
Plugins
-------
== Plugins
Place Gerrit plugins in the review_site/plugins directory to have them loaded on Gerrit startup.
External Documentation Links
----------------------------
== External Documentation Links
* http://www.postgresql.org/docs/[PostgreSQL Documentation]
* http://dev.mysql.com/doc/[MySQL Documentation]

63
Documentation/intro-change-screen.txt
View File

@ -1,5 +1,4 @@
Change Screen - Introduction
============================
= Change Screen - Introduction
As of Gerrit 2.8 the change screen was redesigned from the ground up. The old
change screen is deprecated and will be discontinued in one of the next Gerrit
@ -25,8 +24,7 @@ link:https://groups.google.com/forum/#!topic/repo-discuss/6Ryz9p6AzgE[
CodeScreen2 thread on the repo-discuss mailing list].
[[configuration]]
Configuration
-------------
== Configuration
The new change screen is activated by default. It can be deactivated
system-wide by changing the link:config-gerrit.html[gerrit.changeScreen]
@ -34,8 +32,7 @@ setting to `OLD_UI`. Users can deactivate it by setting `OLD_UI` on their
user preferences page.
[[switching-between-patch-sets]]
Switching between patch sets
----------------------------
== Switching between patch sets
As already mentioned above, the main difference between the old and the new
change screen is the fact that only one patch set is presented on the screen.
@ -54,8 +51,7 @@ screen.
Key bindings: "n" & "p" to navigate between the patch sets.
[[download-commands]]
Download commands
-----------------
== Download commands
The download commands are moved to the 'Download' drop down box. Patch files
can be downloaded as base64 encoded or zipped versions. Download-plugin must
@ -68,8 +64,7 @@ the cached state in the browser will be invalidated and the download commands
will update. Another option to invalidate the cache is to use "Ctrl+Shift+R".
[[included-in]]
Included in
-----------
== Included in
To see the branches a specific change was merged into and the list of the tags
a change was tagged with, use the 'Included In' drop down on the change header,
@ -78,8 +73,7 @@ to the left of the 'Revisions' drop down.
Note that this list is only visible on merged changes.
[[quick-approve]]
Quick approve
-------------
== Quick approve
The so called 'Quick approve' button is some times confusing. Normal users (i.e.
non-maintainers) see this as 'Verified+1' button to the right of the 'Reply'
@ -100,8 +94,7 @@ using this button, hence the name 'Quick approve'. To provide comments, the
'Reply' button should be used.
[[reply-button]]
Reply button
------------
== Reply button
This button corresponds to the 'Review' button the on patch set panel on the old
change screen. The user can optionally send an email during the vote. Inline
@ -115,8 +108,7 @@ is selected.
Key bindings: "a" to open the drop down. "ESC" to close it.
[[edit-commit-message]]
Edit commit message
-------------------
== Edit commit message
To edit the commit message use the 'Edit Message' button on the change header,
which will open a drop-down editor box.
@ -124,8 +116,7 @@ which will open a drop-down editor box.
Key bindings: "e" to open the drop down. "ESC" to close it.
[[star-change]]
Star and unstar changes
-----------------------
== Star and unstar changes
Star change icon allows to star the change, so that "starredby:self" query can
retrieve the starred changes later. If the change is already starred, then
@ -134,8 +125,7 @@ clicking the icon again unstars the change.
Key bindings: "s" to star/unstar the change.
[[permalink-change]]
Permalink a change
------------------
== Permalink a change
Hyperlink "Change <change link>" is a control that serves for two purposes:
reload the change and permalink the change. To permalink,
@ -144,23 +134,20 @@ Right mouse click -> Copy Link Address.
Key bindings: "R" to reload the change.
[[edit-change-topic]]
Edit change topic
-----------------
== Edit change topic
To edit the topic use the edit icon to the right of the topic field.
Key bindings: "t" to open the drop down. "ESC" to close it.
[[abandon-restore]]
Abandon or Restore changes
--------------------------
== Abandon or Restore changes
When a change is abandoned or restored, a panel appears and a comment message
can be provided.
[[working-with-drafts]]
Working with draft changes and patch sets
-----------------------------------------
== Working with draft changes and patch sets
When a change or a patch set is a draft, then three additional buttons
appear on the action panel: 'Publish', 'Delete Revision', and 'Delete
@ -170,16 +157,14 @@ suffix is added to the patch set number to indicate that the patch set
is a draft.
[[draft-comments]]
Highlight draft comments
------------------------
== Highlight draft comments
If a patch set has draft comments that weren't published yet, then that patch
set is marked on the list in the 'Patch Sets' drop down list. In addition a red
"draft" prefix appears on the filenames in the file table.
[[codemirror]]
Codemirror
----------
== Codemirror
On the user preferences page, 'Side By Side' or 'Unified Diff' view can be
configured. Use the "/" key to start the CodeMirror search, like in 'vim'.
@ -206,8 +191,7 @@ Key bindings:
* <Ctrl> + s: Save draft comment
[[reviewers]]
Reviewers
---------
== Reviewers
Reviewer are split into two groups: Reviewers who actually voted on the change
in the 'Reviewers' field, and reviewers, who were added to the change but didn't
@ -223,8 +207,7 @@ To remove reviewers click on the 'x' icon in the reviewer's "chip".
Key bindings: "c" to add a reviewer. "ESC" to close the drop down.
[[auto-refresh]]
Auto refresh of change data
---------------------------
== Auto refresh of change data
On the new change screen polling for updates to the currently open change is
activated per default. For example, if another user votes or comments on the
@ -235,8 +218,7 @@ The default delay is 30 seconds. It can be configured with the
link:config-gerrit.html[change.updateDelay] setting.
[[related-changes]]
"Related changes"
-----------------
== "Related changes"
A tab control on the third column shows the related changes. There are 4
different tabs:
@ -283,8 +265,7 @@ Key bindings: "J" & "K" to navigate between the related changes. "O" to
open the currently selected change on one of the related changes tab page.
[[file-table]]
File table
----------
== File table
The user can now manually toggle the 'reviewed' flag per file using the check
box to the left of the filename.
@ -294,8 +275,7 @@ Key bindings: "j" & "k" to navigate in the file table, "r" to toggle the
view.
[[diff-against]]
Diff against
------------
== Diff against
In the 'Diff against' dropdown, base reference version can be selected. On
selecting an entry the file table list is reloaded and shows only the files
@ -304,8 +284,7 @@ is passed to the side by side view, so that code mirror windows "remember"
the base reference version choice made on the change screen.
[[history]]
History
-------
== History
The history table shows change messages and inline file comments. Expand All and
Collapse All buttons show/hide the messages.

Some files were not shown because too many files have changed in this diff Show More