opendev/gerrit
Code Issues Proposed changes
de3594b29e
gerrit/Documentation/rest-api-config.txt
Dave Borowitz a3d6788212 Use consistent lowercase for "gitweb" 
We had inconsistent class and variable naming in Gerrit to the point
that (prior to I640e645f6) there were two completely different classes
named "GitwebConfig" and "GitWebConfig".

In the official upstream Git documentation, this command line tool is
most often referred to as "gitweb". Standardize on this
capitalization in text. It may still be capitalized at the beginning
of sentences, or where required by programming language style (e.g.
Java class names).

The only exceptions are:
 - MSysGit's wiki page is entitled GitWeb, so use that when referring
   specifically to that page.
 - Old release notes were not touched.

Change-Id: I497477c264e9cc1380c520618f8edf13e7226c9d
2015-06-12 13:24:46 -04:00

1476 lines
39 KiB
Plaintext
Raw Blame History

= Gerrit Code Review - /config/ REST API
This page describes the config related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].
[[config-endpoints]]
Config Endpoints
---------------
[[get-version]]
=== Get Version
--
'GET /config/server/version'
--
Returns the version of the Gerrit server.
.Request
----
GET /config/server/version HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
"2.7"
----
[[get-info]]
=== Get Server Info
--
'GET /config/server/info'
--
Returns the information about the Gerrit server configuration.
.Request
----
GET /config/server/info HTTP/1.0
----
As result a link:#server-info[ServerInfo] entity is returned.
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"auth": {
"auth_type": "LDAP",
"editable_account_fields": [
"FULL_NAME",
"REGISTER_NEW_EMAIL"
]
},
"download": {
"schemes": [
"anonymous http": {
"url": "http://gerrithost:8080/${project}",
"commands": {
"Checkout": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD",
"Format Patch": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
"Pull": "git pull http://gerrithost:8080/${project} ${ref}",
"Cherry Pick": "git fetch http://gerrithost:8080/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD"
},
"clone_commands": {
"Clone": "git clone http://gerrithost:8080/${project}"
"Clone with commit-msg hook": "git clone http://gerrithost:8080/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/"
}
},
"http": {
"url": "http://jdoe@gerrithost:8080/${project}",
"is_auth_required": true,
"is_auth_supported": true,
"commands": {
"Checkout": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD",
"Format Patch": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
"Pull": "git pull http://jdoe@gerrithost:8080/${project} ${ref}",
"Cherry Pick": "git fetch http://jdoe@gerrithost:8080/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD"
},
"clone_commands": {
"Clone": "git clone http://jdoe@gerrithost:8080/${project}",
"Clone with commit-msg hook": "git clone http://jdoe@gerrithost:8080/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/"
}
},
"ssh": {
"url": "ssh://jdoe@gerrithost:29418/${project}",
"is_auth_required": true,
"is_auth_supported": true,
"commands": {
"Checkout": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git checkout FETCH_HEAD",
"Format Patch": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git format-patch -1 --stdout FETCH_HEAD",
"Pull": "git pull ssh://jdoe@gerrithost:29418/${project} ${ref}",
"Cherry Pick": "git fetch ssh://jdoe@gerrithost:29418/${project} ${ref} \u0026\u0026 git cherry-pick FETCH_HEAD"
},
"clone_commands": {
"Clone": "git clone ssh://jdoe@gerrithost:29418/${project}",
"Clone with commit-msg hook": "git clone ssh://jdoe@gerrithost:29418/${project} \u0026\u0026 scp -p -P 29418 jdoe@gerrithost:hooks/commit-msg ${project}/.git/hooks/"
}
}
],
"archives": [
"tgz",
"tar",
"tbz2",
"txz"
]
},
"gerrit": {
"all_projects": "All-Projects",
"all_users": "All-Users"
},
"sshd": {},
"suggest": {
"from": 0
},
"user": {
"anonymous_coward_name": "Anonymous Coward"
}
}
----
[[list-caches]]
=== List Caches
--
'GET /config/server/caches/'
--
Lists the caches of the server. Caches defined by plugins are included.
The caller must be a member of a group that is granted one of the
following capabilities:
* link:access-control.html#capability_viewCaches[View Caches]
* link:access-control.html#capability_maintainServer[Maintain Server]
* link:access-control.html#capability_administrateServer[Administrate Server]
As result a map of link:#cache-info[CacheInfo] entities is returned.
The entries in the map are sorted by cache name.
.Request
----
GET /config/server/caches/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"accounts": {
"type": "MEM",
"entries": {
"mem": 4
},
"average_get": "2.5ms",
"hit_ratio": {
"mem": 94
}
},
"accounts_byemail": {
"type": "MEM",
"entries": {
"mem": 4
},
"average_get": "771.8us",
"hit_ratio": {
"mem": 95
}
},
"accounts_byname": {
"type": "MEM",
"entries": {
"mem": 4
},
"hit_ratio": {
"mem": 100
}
},
"adv_bases": {
"type": "MEM",
"entries": {},
"hit_ratio": {}
},
"change_kind": {
"type": "DISK",
"entries": {
"space": "0.00k"
},
"hit_ratio": {}
},
"changes": {
"type": "MEM",
"entries": {},
"hit_ratio": {}
},
"conflicts": {
"type": "DISK",
"entries": {
"mem": 2,
"disk": 3,
"space": "2.75k"
},
"hit_ratio": {
"mem": 0,
"disk": 100
}
},
"diff": {
"type": "DISK",
"entries": {
"mem": 177,
"disk": 253,
"space": "170.97k"
},
"average_get": "1.1ms",
"hit_ratio": {
"mem": 67,
"disk": 100
}
},
"diff_intraline": {
"type": "DISK",
"entries": {
"mem": 1,
"disk": 1,
"space": "0.37k"
},
"average_get": "6.8ms",
"hit_ratio": {
"mem": 0
}
},
"git_tags": {
"type": "DISK",
"entries": {
"space": "0.00k"
},
"hit_ratio": {}
},
groups": {
"type": "MEM",
"entries": {
"mem": 27
},
"average_get": "183.2us",
"hit_ratio": {
"mem": 12
}
},
"groups_byinclude": {
"type": "MEM",
"entries": {},
"hit_ratio": {}
},
"groups_byname": {
"type": "MEM",
"entries": {},
"hit_ratio": {}
},
"groups_byuuid": {
"type": "MEM",
"entries": {
"mem": 25
},
"average_get": "173.4us",
"hit_ratio": {
"mem": 13
}
},
"groups_external": {
"type": "MEM",
"entries": {},
"hit_ratio": {}
},
groups_members": {
"type": "MEM",
"entries": {
"mem": 4
},
"average_get": "697.8us",
"hit_ratio": {
"mem": 82
}
},
"permission_sort": {
"type": "MEM",
"entries": {
"mem": 16
},
"hit_ratio": {
"mem": 96
}
},
"plugin_resources": {
"type": "MEM",
"entries": {
"mem": 2
},
"hit_ratio": {
"mem": 83
}
},
"project_list": {
"type": "MEM",
"entries": {
"mem": 1
},
"average_get": "18.6ms",
"hit_ratio": {
"mem": 0
}
},
"projects": {
"type": "MEM",
"entries": {
"mem": 35
},
"average_get": "8.6ms",
"hit_ratio": {
"mem": 99
}
},
"quota-repo_size": {
"type": "DISK",
"entries": {
"space": "0.00k"
},
"hit_ratio": {}
},
"sshkeys": {
"type": "MEM",
"entries": {
"mem": 1
},
"average_get": "3.2ms",
"hit_ratio": {
"mem": 50
}
},
"web_sessions": {
"type": "DISK",
"entries": {
"mem": 1,
"disk": 2,
"space": "0.78k"
},
"hit_ratio": {
"mem": 82
}
}
}
----
It is possible to get different output formats by specifying the
`format` option:
* `LIST`:
+
Returns the cache names as JSON list.
+
The cache names are alphabetically sorted.
+
.Request
----
GET /config/server/caches/?format=LIST HTTP/1.0
----
+
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
[
"accounts",
"accounts_byemail",
"accounts_byname",
"adv_bases",
"change_kind",
"changes",
"conflicts",
"diff",
"diff_intraline",
"git_tags",
"groups",
"groups_byinclude",
"groups_byname",
"groups_byuuid",
"groups_external",
"groups_members",
"permission_sort",
"plugin_resources",
"project_list",
"projects",
"quota-repo_size",
"sshkeys",
"web_sessions"
]
----
* `TEXT_LIST`:
+
Returns the cache names as a UTF-8 list that is base64 encoded. The
cache names are delimited by '\n'.
+
The cache names are lexicographically sorted.
+
.Request
----
GET /config/server/caches/?format=TEXT_LIST HTTP/1.0
----
+
.Response
----
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
YWNjb3VudHMKYW...ViX3Nlc3Npb25z
----
+
E.g. this could be used to flush all caches:
+
----
for c in $(curl --digest --user jdoe:TNAuLkXsIV7w http://gerrit/a/config/server/caches/?format=TEXT_LIST | base64 -D)
do
curl --digest --user jdoe:TNAuLkXsIV7w -X POST http://gerrit/a/config/server/caches/$c/flush
done
----
[[cache-operations]]
=== Cache Operations
--
'POST /config/server/caches/'
--
Executes a cache operation that is specified in the request body in a
link:#cache-operation-input[CacheOperationInput] entity.
[[flush-all-caches]]
==== Flush All Caches
.Request
----
POST /config/server/caches/ HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"operation": "FLUSH_ALL"
}
----
.Response
----
HTTP/1.1 200 OK
----
[[flush-several-caches]]
==== Flush Several Caches At Once
.Request
----
POST /config/server/caches/ HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"operation": "FLUSH",
"caches": [
"projects",
"project_list"
]
}
----
.Response
----
HTTP/1.1 200 OK
----
[[get-cache]]
=== Get Cache
--
'GET /config/server/caches/link:#cache-name[\{cache-name\}]'
--
Retrieves information about a cache.
The caller must be a member of a group that is granted one of the
following capabilities:
* link:access-control.html#capability_viewCaches[View Caches]
* link:access-control.html#capability_maintainServer[Maintain Server]
* link:access-control.html#capability_administrateServer[Administrate Server]
As result a link:#cache-info[CacheInfo] entity is returned.
.Request
----
GET /config/server/caches/projects HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"name": "projects",
"type": "MEM",
"entries": {
"mem": 35
},
"average_get": " 8.6ms",
"hit_ratio": {
"mem": 99
}
}
----
[[flush-cache]]
=== Flush Cache
--
'POST /config/server/caches/link:#cache-name[\{cache-name\}]/flush'
--
Flushes a cache.
The caller must be a member of a group that is granted one of the
following capabilities:
* link:access-control.html#capability_flushCaches[Flush Caches] (any cache
except "web_sessions")
* link:access-control.html#capability_maintainServer[Maintain Server] (any cache
including "web_sessions")
* link:access-control.html#capability_administrateServer[Administrate Server]
(any cache including "web_sessions")
.Request
----
POST /config/server/caches/projects/flush HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
----
[[get-summary]]
=== Get Summary
--
'GET /config/server/summary'
--
Retrieves a summary of the current server state.
The caller must be a member of a group that is granted the
link:access-control.html#capability_administrateServer[Administrate
Server] capability.
The following options are supported:
* `jvm`:
+
Includes a JVM summary.
* `gc`:
+
Requests a Java garbage collection before computing the information
about the Java memory heap.
.Request
----
GET /config/server/summary?jvm HTTP/1.0
----
As result a link:#summary-info[SummaryInfo] entity is returned.
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"task_summary": {
"total": 2,
"sleeping": 2
},
"mem_summary": {
"total": "341.06m",
"used": "57.16m",
"free": "283.90m",
"buffers": "0.00k",
"max": "1.67g",
}
"thread_summary": {
"cpus": 8,
"threads": 44,
"counts": {
"HTTP": {
"RUNNABLE": 3,
"TIMED_WAITING": 2
},
"SSH-Interactive-Worker": {
"WAITING": 1
},
"Other": {
"WAITING": 10,
"RUNNABLE": 2,
"TIMED_WAITING": 25
},
"SshCommandStart": {
"WAITING": 1
}
}
},
"jvm_summary": {
"vm_vendor": "Oracle Corporation",
"vm_name": "Java HotSpot(TM) 64-Bit Server VM",
"vm_version": "23.25-b01",
"os_name": "Mac OS X",
"os_version": "10.8.5",
"os_arch": "x86_64",
"user": "gerrit",
"host": "GERRIT",
"current_working_directory": "/Users/gerrit/site",
"site": "/Users/gerrit/site"
}
}
----
[[list-capabilities]]
=== List Capabilities
--
'GET /config/server/capabilities'
--
Lists the capabilities that are available in the system. There are two
kinds of capabilities: core and plugin-owned capabilities.
As result a map of link:#capability-info[CapabilityInfo] entities is
returned.
The entries in the map are sorted by capability ID.
.Request
----
GET /config/server/capabilities/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"accessDatabase": {
"id": "accessDatabase",
"name": "Access Database"
},
"administrateServer": {
"id": "administrateServer",
"name": "Administrate Server"
},
"createAccount": {
"id": "createAccount",
"name": "Create Account"
},
"createGroup": {
"id": "createGroup",
"name": "Create Group"
},
"createProject": {
"id": "createProject",
"name": "Create Project"
},
"emailReviewers": {
"id": "emailReviewers",
"name": "Email Reviewers"
},
"flushCaches": {
"id": "flushCaches",
"name": "Flush Caches"
},
"killTask": {
"id": "killTask",
"name": "Kill Task"
},
"priority": {
"id": "priority",
"name": "Priority"
},
"queryLimit": {
"id": "queryLimit",
"name": "Query Limit"
},
"runGC": {
"id": "runGC",
"name": "Run Garbage Collection"
},
"streamEvents": {
"id": "streamEvents",
"name": "Stream Events"
},
"viewCaches": {
"id": "viewCaches",
"name": "View Caches"
},
"viewConnections": {
"id": "viewConnections",
"name": "View Connections"
},
"viewPlugins": {
"id": "viewPlugins",
"name": "View Plugins"
},
"viewQueue": {
"id": "viewQueue",
"name": "View Queue"
}
}
----
[[list-tasks]]
=== List Tasks
--
'GET /config/server/tasks/'
--
Lists the tasks from the background work queues that the Gerrit daemon
is currently performing, or will perform in the near future.
Gerrit contains an internal scheduler, similar to cron, that it uses to
queue and dispatch both short and long term tasks.
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.
End-users may see a task 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.
The caller must be a member of a group that is granted one of the
following capabilities:
* link:access-control.html#capability_viewQueue[View Queue]
* link:access-control.html#capability_maintainServer[Maintain Server]
* link:access-control.html#capability_administrateServer[Administrate Server]
As result a list of link:#task-info[TaskInfo] entities is returned.
The entries in the list are sorted by task state, remaining delay and
command.
.Request
----
GET /config/server/tasks/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"id": "1e688bea",
"state": "SLEEPING",
"start_time": "2014-06-11 12:58:51.991000000",
"delay": 3453,
"command": "Reload Submit Queue"
},
{
"id": "3e6d4ffa",
"state": "SLEEPING",
"start_time": "2014-06-11 12:58:51.508000000",
"delay": 3287966,
"command": "Log File Compressor"
}
]
----
[[get-task]]
=== Get Task
--
'GET /config/server/tasks/link:#task-id[\{task-id\}]'
--
Retrieves a task from the background work queue that the Gerrit daemon
is currently performing, or will perform in the near future.
End-users may see a task 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.
The caller must be a member of a group that is granted one of the
following capabilities:
* link:access-control.html#capability_viewQueue[View Queue]
* link:access-control.html#capability_maintainServer[Maintain Server]
* link:access-control.html#capability_administrateServer[Administrate Server]
As result a link:#task-info[TaskInfo] entity is returned.
.Request
----
GET /config/server/tasks/1e688bea HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
{
"id": "1e688bea",
"state": "SLEEPING",
"start_time": "2014-06-11 12:58:51.991000000",
"delay": 3453,
"command": "Reload Submit Queue"
}
----
[[delete-task]]
=== Delete Task
--
'DELETE /config/server/tasks/link:#task-id[\{task-id\}]'
--
Kills a task from the background work queue that the Gerrit daemon
is currently performing, or will perform in the near future.
The caller must be a member of a group that is granted one of the
following capabilities:
* link:access-control.html#capability_kill[Kill Task]
* link:access-control.html#capability_maintainServer[Maintain Server]
* link:access-control.html#capability_administrateServer[Administrate Server]
End-users may see a task 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.
Members of a group granted one of the following capabilities may view
all tasks:
* link:access-control.html#capability_viewQueue[View Queue]
* link:access-control.html#capability_maintainServer[Maintain Server]
* link:access-control.html#capability_administrateServer[Administrate Server]
.Request
----
DELETE /config/server/tasks/1e688bea HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[get-top-menus]]
=== Get Top Menus
--
'GET /config/server/top-menus'
--
Returns the list of additional top menu entries.
.Request
----
GET /config/server/top-menus HTTP/1.0
----
As response a list of the additional top menu entries as
link:#top-menu-entry-info[TopMenuEntryInfo] entities is returned.
.Response
----
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
)]}'
[
{
"name": "Top Menu Entry",
"items": [
{
"url": "http://gerrit.googlecode.com/",
"name": "Gerrit",
"target": "_blank"
}
]
}
]
----
[[ids]]
== IDs
[[cache-name]]
=== \{cache-name\}
The name of the cache.
If the cache is defined by a plugin the cache name must include the
plugin name: "<plugin-name>-<cache-name>".
Gerrit core caches can optionally be prefixed with "gerrit":
"gerrit-<cache-name>".
[[task-id]]
=== \{task-id\}
The ID of the task (hex string).
[[json-entities]]
== JSON Entities
[[auth-info]]
=== AuthInfo
The `AuthInfo` entity contains information about the authentication
configuration of the Gerrit server.
[options="header",cols="1,^1,5"]
|==========================================
|Field Name ||Description
|`type` ||
The link:config-gerrit.html#auth.type[authentication type] that is
configured on the server. Can be `OPENID`, `OPENID_SSO`, `OAUTH`,
`HTTP`, `HTTP_LDAP`, `CLIENT_SSL_CERT_LDAP`, `LDAP`, `LDAP_BIND`,
`CUSTOM_EXTENSION` or `DEVELOPMENT_BECOME_ANY_ACCOUNT`.
|`use_contributor_agreements` |not set if `false`|
Whether link:config-gerrit.html#auth.contributorAgreements[contributor
agreements] are required.
|`editable_account_fields` ||
List of account fields that are editable. Possible values are
`FULL_NAME`, `USER_NAME` and `REGISTER_NEW_EMAIL`.
|`login_url` |optional|
The link:config-gerrit.html#auth.loginUrl[login URL]. Only set if
link:config-gerrit.html#auth.type[authentication type] is `HTTP` or
`HTTP_LDAP`.
|`login_text` |optional|
The link:config-gerrit.html#auth.loginText[login text]. Only set if
link:config-gerrit.html#auth.type[authentication type] is `HTTP` or
`HTTP_LDAP`.
|`switch_account_url` |optional|
The link:config-gerrit.html#auth.switchAccountUrl[URL to switch
accounts].
|`register_url` |optional|
The link:config-gerrit.html#auth.registerUrl[register URL]. Only set if
link:config-gerrit.html#auth.type[authentication type] is `LDAP`,
`LDAP_BIND` or `CUSTOM_EXTENSION`.
|`register_text` |optional|
The link:config-gerrit.html#auth.registerText[register text]. Only set
if link:config-gerrit.html#auth.type[authentication type] is `LDAP`,
`LDAP_BIND` or `CUSTOM_EXTENSION`.
|`edit_full_name_url` |optional|
The link:config-gerrit.html#auth.editFullNameUrl[URL to edit the full
name]. Only set if link:config-gerrit.html#auth.type[authentication
type] is `LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`.
|`http_password_url` |optional|
The link:config-gerrit.html#auth.httpPasswordUrl[URL to obtain an HTTP
password]. Only set if link:config-gerrit.html#auth.type[authentication
type] is `CUSTOM_EXTENSION`.
|`is_git_basic_auth` |optional, not set if `false`|
Whether link:config-gerrit.html#auth.gitBasicAuth[basic authentication
is used for Git over HTTP/HTTPS]. Only set if
link:config-gerrit.html#auth.type[authentication type] is is `LDAP` or
`LDAP_BIND`.
|==========================================
[[cache-info]]
=== CacheInfo
The `CacheInfo` entity contains information about a cache.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`name` |
not set if returned in a map where the cache name is used as map key|
The cache name. If the cache is defined by a plugin the cache name
includes the plugin name: "<plugin-name>-<cache-name>".
|`type` ||
The type of the cache (`MEM`: in memory cache, `DISK`: disk cache).
|`entries` ||
Information about the entries in the cache as a
link:#entries-info[EntriesInfo] entity.
|`average_get` |optional|
The average duration of getting one entry from the cache. The value is
returned with a standard time unit abbreviation (`ns`: nanoseconds,
`us`: microseconds, `ms`: milliseconds, `s`: seconds).
|`hit_ratio` ||
Information about the hit ratio as a link:#hit-ration-info[
HitRatioInfo] entity.
|==================================
[[cache-operation-input]]
=== CacheOperationInput
The `CacheOperationInput` entity contains information about an
operation that should be executed on caches.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`operation` ||
The cache operation that should be executed:
`FLUSH_ALL`: Flushes all caches, except the `web_sessions` cache.
`FLUSH`: Flushes the specified caches.
|`caches` |optional|
A list of cache names. This list defines the caches on which the
specified operation should be executed. Whether this list must be
specified depends on the operation being executed.
|==================================
[[capability-info]]
=== CapabilityInfo
The `CapabilityInfo` entity contains information about a capability.
[options="header",cols="1,6"]
|=================================
|Field Name |Description
|`id` |capability ID
|`name` |capability name
|=================================
[[change-config-info]]
=== ChangeConfigInfo
The `ChangeConfigInfo` entity contains information about Gerrit
configuration from the link:config-gerrit.html#change[change]
section.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`allow_drafts` |not set if `false`|
link:config-gerrit.html#change.allowDrafts[Whether draft workflow is
allowed].
|`large_change` ||
link:config-gerrit.html#change.largeChange[Number of changed lines from
which on a change is considered as a large change].
|`reply_label` ||
link:config-gerrit.html#change.replyTooltip[Label name for the reply
button].
|`reply_tooltip` ||
link:config-gerrit.html#change.replyTooltip[Tooltip for the reply
button].
|`update_delay` ||
link:config-gerrit.html#change.updateDelay[How often in seconds the web
interface should poll for updates to the currently open change].
|=============================
[[contact-store-info]]
=== ContactStoreInfo
The `ContactStoreInfo` entity contains information about the contact
store.
[options="header",cols="1,6"]
|=======================
|Field Name |Description
|`url` |
The link:config-gerrit.html#contactstore.url[URL of the contact store].
|=======================
[[download-info]]
=== DownloadInfo
The `DownloadInfo` entity contains information about supported download
options.
[options="header",cols="1,6"]
|=======================
|Field Name |Description
|`schemes` |
The supported download schemes as a map which maps the scheme name to a
of link:#download-scheme-info[DownloadSchemeInfo] entity.
|`archives` |
List of supported archive formats. Possible values are `tgz`, `tar`,
`tbz2` and `txz`.
|=======================
[[download-scheme-info]]
=== DownloadSchemeInfo
The `DownloadSchemeInfo` entity contains information about a supported
download scheme and its commands.
[options="header",cols="1,^1,5"]
|=================================
|Field Name ||Description
|`url` ||
The URL of the download scheme, where '${project}' is used as
placeholder for the project name.
|`is_auth_required` |not set if `false`|
Whether this download scheme requires authentication.
|`is_auth_supported` |not set if `false`|
Whether this download scheme supports authentication.
|`commands` ||
Download commands as a map which maps the command name to the download
command. In the download command '${project}' is used as
placeholder for the project name, and '${ref}' is used as
placeholder for the (change) ref.
Empty, if accessed anonymously and the download scheme requires
authentication.
|`clone_commands` ||
Clone commands as a map which maps the command name to the clone
command. In the clone command '${project}' is used as
placeholder for the project name.
Empty, if accessed anonymously and the download scheme requires
authentication.
|=================================
[[entries-info]]
=== EntriesInfo
The `EntriesInfo` entity contains information about the entries in a
cache.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`mem` |optional|Number of cache entries that are held in memory.
|`disk` |optional|Number of cache entries on the disk. For non-disk
caches this value is not set; for disk caches it is only set if there
are entries in the cache.
|`space` |optional|
The space that is consumed by the cache on disk. The value is returned
with a unit abbreviation (`k`: kilobytes, `m`: megabytes,
`g`: gigabytes). Only set for disk caches.
|==================================
[[gerrit-info]]
=== GerritInfo
The `GerritInfo` entity contains information about Gerrit
configuration from the link:config-gerrit.html#gerrit[gerrit] section.
[options="header",cols="1,^1,5"]
|=================================
|Field Name ||Description
|`all_projects_name` ||
Name of the link:config-gerrit.html#gerrit.allProjects[root project].
|`all_users_name` ||
Name of the link:config-gerrit.html#gerrit.allUsers[project in which
meta data of all users is stored].
|`report_bug_url` |optional|
link:config-gerrit.html#gerrit.reportBugUrl[URL to report bugs].
|`report_bug_text` |optional, not set if default|
link:config-gerrit.html#gerrit.reportBugText[Display text for report
bugs link].
|=================================
[[git-web-info]]
=== GitwebInfo
The `GitwebInfo` entity contains information about the
link:config-gerrit.html#gitweb[gitweb] configuration.
[options="header",cols="1,6"]
|=======================
|Field Name |Description
|`url` |
The link:config-gerrit.html#gitweb.url[gitweb base URL].
|`type` |
The link:config-gerrit.html#gitweb.type[gitweb type] as
link:#git-web-type-info[GitwebTypeInfo] entity.
|=======================
[[git-web-type-info]]
=== GitwebTypeInfo
The `GitwebTypeInfo` entity contains information about the
link:config-gerrit.html#gitweb[gitweb] configuration.
[options="header",cols="1,^1,5"]
|=============================
|Field Name ||Description
|`name` ||
The link:config-gerrit.html#gitweb.linkname[gitweb link name].
|`revision` |optional|
The link:config-gerrit.html#gitweb.revision[gitweb revision pattern].
|`project` |optional|
The link:config-gerrit.html#gitweb.project[gitweb project pattern].
|`branch` |optional|
The link:config-gerrit.html#gitweb.branch[gitweb branch pattern].
|`root_tree` |optional|
The link:config-gerrit.html#gitweb.roottree[gitweb root tree pattern].
|`file` |optional|
The link:config-gerrit.html#gitweb.file[gitweb file pattern].
|`file_history` |optional|
The link:config-gerrit.html#gitweb.filehistory[gitweb file history
pattern].
|`path_separator`||
The link:config-gerrit.html#gitweb.pathSeparator[gitweb path separator].
|`link_drafts` |optional|
link:config-gerrit.html#gitweb.linkDrafts[Whether Gerrit should provide
links to gitweb on draft patch set.]
|`url_encode` |optional|
link:config-gerrit.html#gitweb.urlEncode[Whether Gerrit should encode
the generated viewer URL.]
|=============================
[[hit-ration-info]]
=== HitRatioInfo
The `HitRatioInfo` entity contains information about the hit ratio of a
cache.
[options="header",cols="1,^1,5"]
|==================================
|Field Name ||Description
|`mem` ||
Hit ratio for cache entries that are held in memory (0 \<= value \<= 100).
|`disk` |optional|
Hit ratio for cache entries that are held on disk (0 \<= value \<= 100).
Only set for disk caches.
|==================================
[[jvm-summary-info]]
=== JvmSummaryInfo
The `JvmSummaryInfo` entity contains information about the JVM.
[options="header",cols="1,^1,5"]
|========================================
|Field Name ||Description
|`vm_vendor` ||The vendor of the virtual machine.
|`vm_name` ||The name of the virtual machine.
|`vm_version` ||The version of the virtual machine.
|`os_name` ||The name of the operating system.
|`os_version` ||The version of the operating system.
|`os_arch` ||The architecture of the operating system.
|`user` ||The user that is running Gerrit.
|`host` |optional|
The host on which Gerrit is running.
|`current_working_directory`||The current working directory.
|`site` ||The path to the review site.
|========================================
[[mem-summary-info]]
=== MemSummaryInfo
The `MemSummaryInfo` entity contains information about the current
memory usage.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`total` ||
The total size of the memory. The value is returned with a unit
abbreviation (`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
|`used` ||
The size of used memory. The value is returned with a unit abbreviation
(`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
|`free` ||
The size of free memory. The value is returned with a unit abbreviation
(`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
|`buffers` ||
The size of memory used for JGit buffers. The value is returned with a
unit abbreviation (`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
|`max` ||
The maximal memory size. The value is returned with a unit abbreviation
(`k`: kilobytes, `m`: megabytes, `g`: gigabytes).
|`open_files` |optional|
The number of open files.
|============================
[[server-info]]
=== ServerInfo
The `ServerInfo` entity contains information about the configuration of
the Gerrit server.
[options="header",cols="1,^1,5"]
|=======================================
|Field Name ||Description
|`auth` ||
Information about the authentication configuration as
link:#auth-info[AuthInfo] entity.
|`change` ||
Information about the configuration from the
link:config-gerrit.html#change[change] section as
link:#change-config-info[ChangeConfigInfo] entity.
|`contact_store` |optional|
Information about the contact store configuration as
link:#contact-store-info[ContactStoreInfo] entity.
|`download` ||
Information about the configured download options as
link:#download-info[DownloadInfo] entity.
information about Gerrit
|`gerrit` ||
Information about the configuration from the
link:config-gerrit.html#gerrit[gerrit] section as link:#gerrit-info[
GerritInfo] entity.
|`gitweb ` |optional|
Information about the link:config-gerrit.html#gitweb[gitweb]
configuration as link:#git-web-info[GitwebInfo] entity.
|`sshd` |optional|
Information about the configuration from the
link:config-gerrit.html#sshd[sshd] section as link:#sshd-info[SshdInfo]
entity. Not set if SSHD is disabled.
|`suggest` ||
Information about the configuration from the
link:config-gerrit.html#suggest[suggest] section as link:#suggest-info[
SuggestInfo] entity.
|`user` ||
Information about the configuration from the
link:config-gerrit.html#user[user] section as link:#user-config-info[
UserConfigInfo] entity.
|=======================================
[[sshd-info]]
=== SshdInfo
The `SshdInfo` entity contains information about Gerrit
configuration from the link:config-gerrit.html#sshd[sshd]
section.
This entity doesn't contain any data, but the presence of this (empty)
entity in the link:#server-info[ServerInfo] entity means that SSHD is
enabled on the server.
[[suggest-info]]
=== SuggestInfo
The `SuggestInfo` entity contains information about Gerrit
configuration from the link:config-gerrit.html#suggest[suggest]
section.
[options="header",cols="1,6"]
|=======================
|Field Name |Description
|`from` |
The link:config-gerrit.html#suggest.from[number of characters] that a
user must have typed before suggestions are provided.
|=======================
[[summary-info]]
=== SummaryInfo
The `SummaryInfo` entity contains information about the current state
of the server.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`task_summary` ||
Summary about current tasks as a link:#task-summary-info[
TaskSummaryInfo] entity.
|`mem_summary` ||
Summary about current memory usage as a link:#mem-summary-info[
MemSummaryInfo] entity.
|`thread_summary` ||
Summary about current threads as a link:#thread-summary-info[
ThreadSummaryInfo] entity.
|`jvm_summary` |optional|
Summary about the JVM link:#jvm-summary-info[JvmSummaryInfo] entity.
Only set if the `jvm` option was set.
|============================
[[task-info]]
=== TaskInfo
The `TaskInfo` entity contains information about a task in a background
work queue.
[options="header",cols="1,^1,5"]
|====================================
|Field Name ||Description
|`id` ||The ID of the task.
|`state` ||
The state of the task, can be `DONE`, `CANCELLED`, `RUNNING`, `READY`,
`SLEEPING` and `OTHER`.
|`start_time` ||The start time of the task.
|`delay` ||The remaining delay of the task.
|`command` ||The command of the task.
|`remote_name`|optional|
The remote name. May only be set for tasks that are associated with a
project.
|`project` |optional|The project the task is associated with.
|====================================
[[task-summary-info]]
=== TaskSummaryInfo
The `TaskSummaryInfo` entity contains information about the current
tasks.
[options="header",cols="1,^1,5"]
|============================
|Field Name ||Description
|`total` |optional|
Total number of current tasks.
|`running` |optional|
Number of currently running tasks.
|`ready` |optional|
Number of currently ready tasks.
|`sleeping` |optional|
Number of currently sleeping tasks.
|============================
[[thread-summary-info]]
=== ThreadSummaryInfo
The `ThreadSummaryInfo` entity contains information about the current
threads.
[options="header",cols="1,6"]
|===========================
|Field Name |Description
|`cpus` |
The number of available processors.
|`threads` |
The total number of current threads.
|`counts` |
Detailed thread counts as a map that maps a thread kind to a map that
maps a thread state to the thread count. The thread kinds group the
counts by threads that have the same name prefix (`HTTP`,
`IntraLineDiff`, `ReceiveCommits`, `SSH git-receive-pack`,
`SSH git-upload-pack`, `SSH-Interactive-Worker`, `SSH-Stream-Worker`,
`SshCommandStart`). The counts for other threads are available under
the thread kind `Other`. Counts for the following thread states can be
included: `NEW`, `RUNNABLE`, `BLOCKED`, `WAITING`, `TIMED_WAITING` and
`TERMINATED`.
|===========================
[[top-menu-entry-info]]
=== TopMenuEntryInfo
The `TopMenuEntryInfo` entity contains information about a top menu
entry.
[options="header",cols="1,6"]
|=================================
|Field Name |Description
|`name` |Name of the top menu entry.
|`items` |List of link:#top-menu-item-info[menu items].
|=================================
[[top-menu-item-info]]
=== TopMenuItemInfo
The `TopMenuItemInfo` entity contains information about a menu item in
a top menu entry.
[options="header",cols="1,^1,5"]
|========================
|Field Name ||Description
|`url` ||The URL of the menu item link.
|`name` ||The name of the menu item.
|`target` ||Target attribute of the menu item link.
|`id` |optional|The `id` attribute of the menu item link.
|========================
[[user-config-info]]
=== UserConfigInfo
The `UserConfigInfo` entity contains information about Gerrit
configuration from the link:config-gerrit.html#user[user] section.
[options="header",cols="1,6"]
|====================================
|Field Name |Description
|`anonymous_coward_name` |
link:config-gerrit.html#user.anonymousCoward[Username] that is
displayed in the Gerrit Web UI and in e-mail notifications if the full
name of the user is not set.
|====================================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink