| = gerrit ls-projects | |
| == NAME | |
| gerrit ls-projects - List projects visible to caller. | |
| == SYNOPSIS | |
| [verse] | |
| -- | |
| _ssh_ -p <port> <host> _gerrit ls-projects_ | |
| [--show-branch <BRANCH> ...] | |
| [--description | -d] | |
| [--tree | -t] | |
| [--type {code | permissions | all}] | |
| [--format {text | json | json_compact}] | |
| [--all] | |
| [--limit <N>] | |
| [--prefix | -p <prefix>] | |
| [--has-acl-for GROUP] | |
| [--match | -m] | |
| [-r REGEX] | |
| [--start | -S] | |
| [--state | -s ] | |
| -- | |
| == 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 | |
| Any user who has SSH access to Gerrit. | |
| == SCRIPTING | |
| This command is intended to be used in scripts. | |
| == OPTIONS | |
| --show-branch:: | |
| -b:: | |
| Branch for which the command will display the sha of each project. | |
| The command may have multiple --show-branch parameters, in this case | |
| sha will be shown for each of the branches. | |
| If the user does not have READ access to some branch or the branch does not | |
| exist then stub (40 `-` symbols) is shown. | |
| If the user does not have access to any branch in the project then the | |
| whole project is not shown. | |
| --description:: | |
| -d:: | |
| Allows listing of projects together with their respective | |
| description. | |
| + | |
| For text format output, all non-printable characters (ASCII value 31 or | |
| less) are escaped according to the conventions used in languages like C, | |
| Python, and Perl, 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. | |
| --tree:: | |
| -t:: | |
| Displays project inheritance in a tree-like format. | |
| This option does not work together with the show-branch option. | |
| --match:: | |
| -m | |
| Match project substring | |
| -r:: | |
| Match project regex | |
| --start:: | |
| -S:: | |
| Number of projects to skip | |
| --state:: | |
| -s:: | |
| Filter by project state. [ACTIVE | READON_ONLY | HIDDEN] | |
| [NOTE] | |
| If the calling user does not meet any of the following criteria: | |
| * The state of the parent project is either "ACTIVE" or "READ ONLY", | |
| and the calling user has READ permission to at least one ref. | |
| * The state of the parent project is "HIDDEN" and the calling user | |
| has READ permission for 'refs/meta/config'. | |
| Then the 'parent' field will be labeled as '?-N', where N represents the | |
| nesting level within the project's tree structure. In the provided example, | |
| 'All-Projects' corresponds to level 1, 'parent-project' to level 2, and | |
| 'child-project' to level 3. | |
| The output format to display the results should be `json` or `json_compact`. | |
| --type:: | |
| Display only projects of the specified type. If not | |
| specified, defaults to `all`. Supported types: | |
| + | |
| -- | |
| `code`:: Any project likely to contain user files. | |
| `permissions`:: Projects created with the `--permissions-only` flag. | |
| `all`:: Any type of project. | |
| -- | |
| --format:: | |
| What output format to display the results in. | |
| + | |
| -- | |
| `text`:: Simple text based format. | |
| `json`:: Map of JSON objects describing each project. | |
| `json_compact`:: Minimized JSON output. | |
| -- | |
| --all:: | |
| Display all projects that are accessible by the calling user | |
| account. Besides the projects that the calling user account has | |
| been granted 'READ' access to, this includes all projects that | |
| are owned by the calling user account (even if for these projects | |
| the 'READ' access right is not assigned to the calling user | |
| account). | |
| --limit:: | |
| Cap the number of results to the first N matches. | |
| --prefix:: | |
| Limit the results to those projects that start with the specified prefix. | |
| --has-acl-for:: | |
| Display only projects on which access rights for this group are | |
| directly assigned. Projects which only inherit access rights for | |
| this group are not listed. | |
| + | |
| With this option you can find out on which projects a group is used. | |
| == 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 | |
| be limited to projects matching a prefix by supplying the prefix | |
| as part of the URL, for example `/projects/external/` lists only | |
| projects whose name start with the string `external/`. | |
| Over HTTP the `json_compact` output format is assumed if the client | |
| explicitly asks for JSON using HTTP header `Accept: application/json`. | |
| When any JSON output format is used on HTTP, readers must skip the | |
| first line produced. The first line is a garbage JSON string crafted | |
| 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 | |
| List visible projects: | |
| ---- | |
| $ ssh -p 29418 review.example.com gerrit ls-projects | |
| platform/manifest | |
| tools/gerrit | |
| tools/gitiles | |
| $ curl http://review.example.com/projects/ | |
| platform/manifest | |
| tools/gerrit | |
| tools/gitiles | |
| $ curl http://review.example.com/projects/tools/ | |
| tools/gerrit | |
| tools/gitiles | |
| ---- | |
| Clone any project visible to the user: | |
| ---- | |
| for p in `ssh -p 29418 review.example.com gerrit ls-projects` | |
| do | |
| mkdir -p `dirname "$p"` | |
| git clone --bare "ssh://review.example.com:29418/$p.git" "$p.git" | |
| done | |
| ---- | |
| == SEE ALSO | |
| * link:access-control.html[Access Controls] | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |