opendev/gerrit
Code Issues Proposed changes
d103b2b61c
gerrit/Documentation/rest-api-projects.txt
Edwin Kempin 6ce96a1e89 Support deletion of branches via REST 
A branch can now be deleted by DELETE on
/projects/<project-name>/branches/<branch-id>.

Change-Id: I2c9af129f024cd2668a46dd2bd8848bd0bc0655c
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
2013-06-06 17:28:40 +02:00

1285 lines
32 KiB
Plaintext
Raw Blame History

Gerrit Code Review - /projects/ REST API
========================================
This page describes the project related REST endpoints.
Please also take note of the general information on the
link:rest-api.html[REST API].
Endpoints
---------
[[project-endpoints]]
Project Endpoints
-----------------
[[list-projects]]
List Projects
~~~~~~~~~~~~~
[verse]
'GET /projects/'
Lists the projects accessible by the caller. This is the same as
using the link:cmd-ls-projects.html[ls-projects] command over SSH,
and accepts the same options as query parameters.
As result a map is returned that maps the project names to
link:#project-info[ProjectInfo] entries. The entries in the map are sorted
by project name.
.Request
----
GET /projects/?d HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"external/bison": {
"kind": "gerritcodereview#project",
"id": "external%2Fbison",
"description": "GNU parser generator"
},
"external/gcc": {
"kind": "gerritcodereview#project",
"id": "external%2Fgcc",
},
"external/openssl": {
"kind": "gerritcodereview#project",
"id": "external%2Fopenssl",
"description": "encryption\ncrypto routines"
},
"test": {
"kind": "gerritcodereview#project",
"id": "test",
"description": "\u003chtml\u003e is escaped"
}
}
----
.Get all projects with their description
****
get::/projects/?d
****
[[suggest-projects]]
The `/projects/` URL also accepts a prefix string in the `p` parameter.
This limits the results to those projects that start with the specified
prefix.
List all projects that start with `platform/`:
.Request
----
GET /projects/?p=platform%2F HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"platform/drivers": {
"kind": "gerritcodereview#project",
"id": "platform%2Fdrivers",
},
"platform/tools": {
"kind": "gerritcodereview#project",
"id": "platform%2Ftools",
}
}
----
E.g. this feature can be used by suggestion client UI's to limit results.
[[get-project]]
Get Project
~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]'
Retrieves a project.
.Request
----
GET /projects/plugins%2Freplication HTTP/1.0
----
As response a link:#project-info[ProjectInfo] entity is returned that
describes the project.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#project",
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
}
----
[[create-project]]
Create Project
~~~~~~~~~~~~~~
[verse]
'PUT /projects/link:#project-name[\{project-name\}]'
Creates a new project.
In the request body additional data for the project can be provided as
link:#project-input[ProjectInput].
.Request
----
PUT /projects/MyProject HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"description": "This is a demo project.",
"submit_type": "CHERRY_PICK",
"owners": [
"MyProject-Owners"
]
}
----
As response the link:#project-info[ProjectInfo] entity is returned that
describes the created project.
.Response
----
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#project",
"id": "MyProject",
"name": "MyProject",
"parent": "All-Projects",
"description": "This is a demo project."
}
----
[[get-project-description]]
Get Project Description
~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/description'
Retrieves the description of a project.
.Request
----
GET /projects/plugins%2Freplication/description HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"Copies to other servers using the Git protocol"
----
If the project does not have a description an empty string is returned.
[[set-project-description]]
Set Project Description
~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'PUT /projects/link:#project-name[\{project-name\}]/description'
Sets the description of a project.
The new project description must be provided in the request body inside
a link:#project-description-input[ProjectDescriptionInput] entity.
.Request
----
PUT /projects/plugins%2Freplication/description HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"description": "Plugin for Gerrit that handles the replication.",
"commit_message": "Update the project description"
}
----
As response the new project description is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"Plugin for Gerrit that handles the replication."
----
If the description was deleted the response is "`204 No Content`".
[[delete-project-description]]
Delete Project Description
~~~~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'DELETE /projects/link:#project-name[\{project-name\}]/description'
Deletes the description of a project.
The request body does not need to include a
link:#project-description-input[ProjectDescriptionInput] entity if no
commit message is specified.
Please note that some proxies prohibit request bodies for DELETE
requests. In this case, if you want to specify a commit message, use
link:#set-project-description[PUT] to delete the description.
.Request
----
DELETE /projects/plugins%2Freplication/description HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[get-project-parent]]
Get Project Parent
~~~~~~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/parent'
Retrieves the name of a project's parent project. For the
`All-Projects` root project an empty string is returned.
.Request
----
GET /projects/plugins%2Freplication/parent HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"All-Projects"
----
[[set-project-parent]]
Set Project Parent
~~~~~~~~~~~~~~~~~~
[verse]
'PUT /projects/link:#project-name[\{project-name\}]/parent'
Sets the parent project for a project.
The new name of the parent project must be provided in the request body
inside a link:#project-parent-input[ProjectParentInput] entity.
.Request
----
PUT /projects/plugins%2Freplication/parent HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"parent": "Public-Plugins",
"commit_message": "Update the project parent"
}
----
As response the new parent project name is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"Public-Plugins"
----
[[get-head]]
Get HEAD
~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/HEAD'
Retrieves for a project the name of the branch to which `HEAD` points.
.Request
----
GET /projects/plugins%2Freplication/HEAD HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"refs/heads/master"
----
[[set-head]]
Set HEAD
~~~~~~~~
[verse]
'PUT /projects/link:#project-name[\{project-name\}]/HEAD'
Sets `HEAD` for a project.
The new ref to which `HEAD` should point must be provided in the
request body inside a link:#head-input[HeadInput] entity.
.Request
----
PUT /projects/plugins%2Freplication/HEAD HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"ref": "refs/heads/stable"
}
----
As response the new ref to which `HEAD` points is returned.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
"refs/heads/stable"
----
[[get-repository-statistics]]
Get Repository Statistics
~~~~~~~~~~~~~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/statistics.git'
Return statistics for the repository of a project.
.Request
----
GET /projects/plugins%2Freplication/statistics.git HTTP/1.0
----
The repository statistics are returned as a
link:#repository-statistics-info[RepositoryStatisticsInfo] entity.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"number_of_loose_objects": 127,
"number_of_loose_refs": 15,
"number_of_pack_files": 15,
"number_of_packed_objects": 67,
"number_of_packed_refs": 0,
"size_of_loose_objects": 29466,
"size_of_packed_objects": 9646
}
----
[[get-config]]
Get Config
~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/config'
Gets some configuration information about a project. Note that this
config info is not simply the contents of `project.config`; it generally
contains fields that may have been inherited from parent projects.
.Request
----
GET /projects/myproject/config
----
A link:#config-info[ConfigInfo] entity is returned that describes the
project configuration. Some fields are only visible to users that have
read access to `refs/meta/config`.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#project_config",
"use_contributor_agreements": false,
"use_content_merge": true,
"use_signed_off_by": false,
"require_change_id": true,
"commentlinks": {}
}
----
[[run-gc]]
Run GC
~~~~~~
[verse]
'POST /projects/link:#project-name[\{project-name\}]/gc'
Run the Git garbage collection for the repository of a project.
.Request
----
POST /projects/plugins%2Freplication/gc HTTP/1.0
----
The response is the streamed output of the garbage collection.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: text/plain;charset=UTF-8
collecting garbage for "plugins/replication":
Pack refs: 100% (21/21)
Counting objects: 20
Finding sources: 100% (20/20)
Getting sizes: 100% (13/13)
Compressing objects: 83% (5/6)
Writing objects: 100% (20/20)
Selecting commits: 100% (7/7)
Building bitmaps: 100% (7/7)
Finding sources: 100% (41/41)
Getting sizes: 100% (25/25)
Compressing objects: 52% (12/23)
Writing objects: 100% (41/41)
Prune loose objects also found in pack files: 100% (36/36)
Prune loose, unreferenced objects: 100% (36/36)
done.
----
[[branch-endpoints]]
Branch Endpoints
----------------
[[list-branches]]
List Branches
~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/branches/'
List the branches of a project.
As result a list of link:#branch-info[BranchInfo] entries is
returned.
.Request
----
GET /projects/work%2Fmy-project/branches/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
[
{
"ref": "HEAD",
"revision": "master"
},
{
"ref": "refs/meta/config",
"revision": "76016386a0d8ecc7b6be212424978bb45959d668"
},
{
"ref": "refs/heads/master",
"revision": "67ebf73496383c6777035e374d2d664009e2aa5c"
},
{
"ref": "refs/heads/stable",
"revision": "64ca533bd0eb5252d2fee83f63da67caae9b4674",
"can_delete": true
}
]
----
[[get-branch]]
Get Branch
~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]'
Retrieves a branch of a project.
.Request
----
GET /projects/work%2Fmy-project/branches/master HTTP/1.0
----
As response a link:#branch-info[BranchInfo] entity is returned that
describes the branch.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"ref": "refs/heads/master",
"revision": "67ebf73496383c6777035e374d2d664009e2aa5c"
}
----
[[create-branch]]
Create Branch
~~~~~~~~~~~~~
[verse]
'PUT /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]'
Creates a new branch.
In the request body additional data for the branch can be provided as
link:#branch-input[BranchInput].
.Request
----
PUT /projects/MyProject/branches/stable HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"revision": "76016386a0d8ecc7b6be212424978bb45959d668"
}
----
As response a link:#branch-info[BranchInfo] entity is returned that
describes the created branch.
.Response
----
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"ref": "refs/heads/stable",
"revision": "76016386a0d8ecc7b6be212424978bb45959d668",
"can_delete": true
}
----
[[delete-branch]]
Delete Branch
~~~~~~~~~~~~~
[verse]
'DELETE /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]'
Deletes a branch.
.Request
----
DELETE /projects/MyProject/branches/stable HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[child-project-endpoints]]
Child Project Endpoints
-----------------------
[[list-child-projects]]
List Child Projects
~~~~~~~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/children/'
List the direct child projects of a project.
.Request
----
GET /projects/Public-Plugins/children/ HTTP/1.0
----
As result a list of link:#project-info[ProjectInfo] entries is
returned that describe the child projects.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
[
{
"kind": "gerritcodereview#project",
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
},
{
"kind": "gerritcodereview#project",
"id": "plugins%2Freviewnotes",
"name": "plugins/reviewnotes",
"parent": "Public-Plugins",
"description": "Annotates merged commits using notes on refs/notes/review."
},
{
"kind": "gerritcodereview#project",
"id": "plugins%2Fsingleusergroup",
"name": "plugins/singleusergroup",
"parent": "Public-Plugins",
"description": "GroupBackend enabling users to be directly added to access rules"
}
]
----
To resolve the child projects of a project recursively the parameter
`recursive` can be set.
Child projects that are not visible to the calling user are ignored and
are not resolved further.
.Request
----
GET /projects/Public-Projects/children/?recursive HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
[
{
"kind": "gerritcodereview#project",
"id": "gerrit",
"name": "gerrit",
"parent": "Public-Projects",
"description": "Gerrit Code Review"
},
{
"kind": "gerritcodereview#project",
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
},
{
"kind": "gerritcodereview#project",
"id": "plugins%2Freviewnotes",
"name": "plugins/reviewnotes",
"parent": "Public-Plugins",
"description": "Annotates merged commits using notes on refs/notes/review."
},
{
"kind": "gerritcodereview#project",
"id": "plugins%2Fsingleusergroup",
"name": "plugins/singleusergroup",
"parent": "Public-Plugins",
"description": "GroupBackend enabling users to be directly added to access rules"
},
{
"kind": "gerritcodereview#project",
"id": "Public-Plugins",
"name": "Public-Plugins",
"parent": "Public-Projects",
"description": "Parent project for plugins/*"
}
]
----
[[get-child-project]]
Get Child Project
~~~~~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/children/link:#project-name[\{project-name\}]'
Retrieves a child project. If a non-direct child project should be
retrieved the parameter `recursive` must be set.
.Request
----
GET /projects/Public-Plugins/children/plugins%2Freplication HTTP/1.0
----
As response a link:#project-info[ProjectInfo] entity is returned that
describes the child project.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#project",
"id": "plugins%2Freplication",
"name": "plugins/replication",
"parent": "Public-Plugins",
"description": "Copies to other servers using the Git protocol"
}
----
[[dashboard-endpoints]]
Dashboard Endpoints
-------------------
[[list-dashboards]]
List Dashboards
~~~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/dashboards/'
List custom dashboards for a project.
As result a list of link:#dashboard-info[DashboardInfo] entries is
returned.
List all dashboards for the `work/my-project` project:
.Request
----
GET /projects/work%2Fmy-project/dashboards/ HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
[
{
"kind": "gerritcodereview#dashboard",
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
]
----
.Get all dashboards of the 'All-Projects' project
****
get::/projects/All-Projects/dashboards/
****
[[get-dashboard]]
Get Dashboard
~~~~~~~~~~~~~
[verse]
'GET /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{dashboard-id\}]'
Retrieves a project dashboard. The dashboard can be defined on that
project or be inherited from a parent project.
.Request
----
GET /projects/work%2Fmy-project/dashboards/main:closed HTTP/1.0
----
As response a link:#dashboard-info[DashboardInfo] entity is returned
that describes the dashboard.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#dashboard",
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
----
To retrieve the default dashboard of a project use `default` as
dashboard-id.
.Request
----
GET /projects/work%2Fmy-project/dashboards/default HTTP/1.0
----
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#dashboard",
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
----
[[set-dashboard]]
Set Dashboard
~~~~~~~~~~~~~
[verse]
'PUT /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{dashboard-id\}]'
Updates/Creates a project dashboard.
Currently only supported for the `default` dashboard.
The creation/update information for the dashboard must be provided in
the request body as a link:#dashboard-input[DashboardInput] entity.
.Request
----
PUT /projects/work%2Fmy-project/dashboards/default HTTP/1.0
Content-Type: application/json;charset=UTF-8
{
"id": "main:closed",
"commit_message": "Define the default dashboard"
}
----
As response the new/updated dashboard is returned as a
link:#dashboard-info[DashboardInfo] entity.
.Response
----
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json;charset=UTF-8
)]}'
{
"kind": "gerritcodereview#dashboard",
"id": "main:closed",
"ref": "main",
"path": "closed",
"description": "Merged and abandoned changes in last 7 weeks",
"url": "/dashboard/?title\u003dClosed+changes\u0026Merged\u003dstatus:merged+age:7w\u0026Abandoned\u003dstatus:abandoned+age:7w",
"default": true,
"title": "Closed changes",
"sections": [
{
"name": "Merged",
"query": "status:merged age:7w"
},
{
"name": "Abandoned",
"query": "status:abandoned age:7w"
}
]
}
----
[[delete-dashboard]]
Delete Dashboard
~~~~~~~~~~~~~~~~
[verse]
'DELETE /projects/link:#project-name[\{project-name\}]/dashboards/link:#dashboard-id[\{dashboard-id\}]'
Deletes a project dashboard.
Currently only supported for the `default` dashboard.
The request body does not need to include a link:#dashboard-input[
DashboardInput] entity if no commit message is specified.
Please note that some proxies prohibit request bodies for DELETE
requests.
.Request
----
DELETE /projects/work%2Fmy-project/dashboards/default HTTP/1.0
----
.Response
----
HTTP/1.1 204 No Content
----
[[ids]]
IDs
---
[[branch-id]]
\{branch-id\}
~~~~~~~~~~~~~
The name of a branch or `HEAD`. The prefix `refs/heads/` can be
omitted.
[[dashboard-id]]
\{dashboard-id\}
~~~~~~~~~~~~~~~~
The ID of a dashboard in the format '<ref>:<path>'.
A special dashboard ID is `default` which represents the default
dashboard of a project.
[[project-name]]
\{project-name\}
~~~~~~~~~~~~~~~~
The name of the project.
[[json-entities]]
JSON Entities
-------------
[[branch-info]]
BranchInfo
~~~~~~~~~~
The `BranchInfo` entity contains information about a branch.
[options="header",width="50%",cols="1,^2,4"]
|=========================
|Field Name ||Description
|`ref` ||The ref of the branch.
|`revision` ||The revision to which the branch points.
|`can_delete`|`false` if not set|
Whether the calling user can delete this branch.
|=========================
[[branch-input]]
BranchInput
~~~~~~~~~~~
The `BranchInput` entity contains information for the creation of
a new branch.
[options="header",width="50%",cols="1,^2,4"]
|=======================
|Field Name||Description
|`ref` |optional|
The name of the branch. The prefix `refs/heads/` can be
omitted. +
If set, must match the branch ID in the URL.
|`revision`|optional|
The base revision of the new branch. +
If not set, `HEAD` will be used as base revision.
|=======================
[[dashboard-info]]
DashboardInfo
~~~~~~~~~~~~~
The `DashboardInfo` entity contains information about a project
dashboard.
[options="header",width="50%",cols="1,^2,4"]
|===============================
|Field Name ||Description
|`kind` ||`gerritcodereview#dashboard`
|`id` ||
The ID of the dashboard. The ID has the format '<ref>:<path>',
where ref and path are URL encoded.
|`project` ||
The name of the project for which this dashboard is returned.
|`defining_project`||
The name of the project in which this dashboard is defined.
This is different from `project` if the dashboard is inherited from a
parent project.
|`ref` ||
The name of the ref in which the dashboard is defined, without the
`refs/meta/dashboards/` prefix, which is common for all dashboard refs.
|`path` ||
The path of the file in which the dashboard is defined.
|`description` |optional|The description of the dashboard.
|`foreach` |optional|
Subquery that applies to all sections in the dashboard. +
Tokens such as `${project}` are not resolved.
|`url` ||
The URL under which the dashboard can be opened in the Gerrit WebUI. +
The URL is relative to the canonical web URL. +
Tokens in the queries such as `${project}` are resolved.
|`default` |not set if `false`|
Whether this is the default dashboard of the project.
|`title` |optional|The title of the dashboard.
|`sections` ||
The list of link:#dashboard-section-info[sections] in the dashboard.
|===============================
[[dashboard-input]]
DashboardInput
~~~~~~~~~~~~~~
The `DashboardInput` entity contains information to create/update a
project dashboard.
[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`id` |optional|
URL encoded ID of a dashboard to which this dashboard should link to.
|`commit_message`|optional|
Message that should be used to commit the change of the dashboard.
|=============================
[[dashboard-section-info]]
DashboardSectionInfo
~~~~~~~~~~~~~~~~~~~~
The `DashboardSectionInfo` entity contains information about a section
in a dashboard.
[options="header",width="50%",cols="1,6"]
|===========================
|Field Name |Description
|`name` |The title of the section.
|`query` |The query of the section. +
Tokens such as `${project}` are not resolved.
|===========================
[[head-input]]
HeadInput
~~~~~~~~~
The `HeadInput` entity contains information for setting `HEAD` for a
project.
[options="header",width="50%",cols="1,6"]
|============================
|Field Name |Description
|`ref` |
The ref to which `HEAD` should be set, the `refs/heads` prefix can be
omitted.
|============================
[[project-description-input]]
ProjectDescriptionInput
~~~~~~~~~~~~~~~~~~~~~~~
The `ProjectDescriptionInput` entity contains information for setting a
project description.
[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`description` |optional|The project description. +
The project description will be deleted if not set.
|`commit_message`|optional|
Message that should be used to commit the change of the project
description in the `project.config` file to the `refs/meta/config`
branch.
|=============================
[[project-info]]
ProjectInfo
~~~~~~~~~~~
The `ProjectInfo` entity contains information about a project.
[options="header",width="50%",cols="1,^2,4"]
|===========================
|Field Name ||Description
|`kind` ||`gerritcodereview#project`
|`id` ||The URL encoded project name.
|`name` |
not set if returned in a map where the project name is used as map key|
The name of the project.
|`parent` |optional|
The name of the parent project. +
`?-<n>` if the parent project is not visible (`<n>` is a number which
is increased for each non-visible project).
|`description` |optional|The description of the project.
|`branches` |optional|Map of branch names to HEAD revisions.
|===========================
[[project-input]]
ProjectInput
~~~~~~~~~~~~
The `ProjectInput` entity contains information for the creation of
a new project.
[options="header",width="50%",cols="1,^2,4"]
|=========================================
|Field Name ||Description
|`name` |optional|
The name of the project (not encoded). +
If set, must match the project name in the URL.
|`parent` |optional|
The name of the parent project. +
If not set, the `All-Projects` project will be the parent project.
|`description` |optional|The description of the project.
|`permissions_only` |`false` if not set|
Whether a permission-only project should be created.
|`create_empty_commit` |`false` if not set|
Whether an empty initial commit should be created.
|`submit_type` |optional|
The submit type that should be set for the project
(`MERGE_IF_NECESSARY`, `REBASE_IF_NECESSARY`, `FAST_FORWARD_ONLY`,
`MERGE_ALWAYS`, `CHERRY_PICK`). +
If not set, `MERGE_IF_NECESSARY` is set as submit type.
|`branches` |optional|
A list of branches that should be initially created. +
For the branch names the `refs/heads/` prefix can be omitted.
|`owners` |optional|
A list of groups that should be assigned as project owner. +
Each group in the list must be specified as
link:rest-api-groups.html#group-id[group-id]. +
If not set, the link:config-gerrit.html#repository.name.ownerGroup[
groups that are configured as default owners] are set as project
owners.
|`use_contributor_agreements`|`INHERIT` if not set|
Whether contributor agreements should be used for the project (`TRUE`,
`FALSE`, `INHERIT`).
|`use_signed_off_by` |`INHERIT` if not set|
Whether the usage of 'Signed-Off-By' footers is required for the
project (`TRUE`, `FALSE`, `INHERIT`).
|`use_content_merge` |`INHERIT` if not set|
Whether content merge should be enabled for the project (`TRUE`,
`FALSE`, `INHERIT`). +
`FALSE`, if the `submit_type` is `FAST_FORWARD_ONLY`.
|`require_change_id` |`INHERIT` if not set|
Whether the usage of Change-Ids is required for the project (`TRUE`,
`FALSE`, `INHERIT`).
|=========================================
[[project-parent-input]]
ProjectParentInput
~~~~~~~~~~~~~~~~~~
The `ProjectParentInput` entity contains information for setting a
project parent.
[options="header",width="50%",cols="1,^2,4"]
|=============================
|Field Name ||Description
|`parent` ||The name of the parent project.
|`commit_message`|optional|
Message that should be used to commit the change of the project parent
in the `project.config` file to the `refs/meta/config` branch.
|=============================
[[repository-statistics-info]]
RepositoryStatisticsInfo
~~~~~~~~~~~~~~~~~~~~~~~~
The `RepositoryStatisticsInfo` entity contains information about
statistics of a Git repository.
[options="header",width="50%",cols="1,6"]
|======================================
|Field Name |Description
|`number_of_loose_objects` |Number of loose objects.
|`number_of_loose_refs` |Number of loose refs.
|`number_of_pack_files` |Number of pack files.
|`number_of_packed_objects`|Number of packed objects.
|`number_of_packed_refs` |Number of packed refs.
|`size_of_loose_objects` |Size of loose objects in bytes.
|`size_of_packed_objects` |Size of packed objects in bytes.
|======================================
[[config-info]]
ConfigInfo
~~~~~~~~~~
The `ConfigInfo` entity contains information about the effective project
configuration.
Fields marked with * are only visible to users who have read access to
`refs/meta/config`.
[options="header",width="50%",cols="1,6"]
|======================================
|Field Name |Description
|`use_contributor_agreements*`|
If set, authors must complete a contributor agreement on the site
before pushing any commits or changes to this project.
|`use_content_merge*`|
If set, Gerrit will try to perform a 3-way merge of text file content
when a file has been modified by both the destination branch and the
change being submitted. This option only takes effect if submit type is
not FAST_FORWARD_ONLY.
|`use_signed_off_by*`|
If set, each change must contain a Signed-off-by line from either the
author or the uploader in the commit message.
|`require_change_id*`|
If set, require a valid link:user-changeid.html[Change-Id] footer in any
commit uploaded for review. This does not apply to commits pushed
directly to a branch or tag.
|`commentlinks`|
Comment link configuration for the project. Has the same format as the
link:config-gerrit.html#_a_id_commentlink_a_section_commentlink[commentlink section]
of `gerrit.config`.
|======================================
GERRIT
------
Part of link:index.html[Gerrit Code Review]
View Git Blame Copy Permalink