blob: 306bb92e18b38b7d617b4979ee4f7b71820a67a8 [file] [log] [blame]
gerrit ls-groups
================
NAME
----
gerrit ls-groups - List groups visible to caller
SYNOPSIS
--------
[verse]
'ssh' -p <port> <host> 'gerrit ls-groups'
[--project <NAME> | -p <NAME>]
[--user <NAME> | -u <NAME>]
[--visible-to-all]
[--type {internal | system}]
[--verbose | -v]
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
------
Any user who has configured an SSH key.
SCRIPTING
---------
This command is intended to be used in scripts.
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.
OPTIONS
-------
--project::
-p::
Name of the project for which the groups should be listed. Only
groups are listed for which any permission is set on this project
(or for which a permission is inherited from a parent project).
Multiple --project options may be specified to specify additional
projects. In this case all groups are listed that have a
permission for any of the specified projects.
+
This option can't be used together with the '--user' option.
--user::
-u::
User for which the groups should be listed. Only groups are
listed that contain this user as a member.
+
The calling user can list the groups for the own user or must be a
member of the privileged 'Administrators' group to list the groups
for other users.
+
This option can't be used together with the '--project' option.
--visible-to-all::
Displays only groups that are visible to all registered users
(groups that are explicitly marked as visible to all registered
users).
--type::
Display only groups of the specified type. If not specified,
groups of all types are displayed. Supported types:
+
--
`internal`:: Any group defined within Gerrit.
`system`:: Any system defined and managed group.
--
--verbose::
-v::
Enable verbose output with tab-separated columns for the
group name, UUID, description, type (`SYSTEM` or `INTERNAL`),
owner group name, owner group UUID and whether the group is
visible to all (`true` or `false`).
+
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
--------
List visible groups:
=====
$ ssh -p 29418 review.example.com gerrit ls-groups
Administrators
Anonymous Users
MyProject_Committers
Project Owners
Registered Users
=====
List all groups for which any permission is set for the project
"MyProject":
=====
$ ssh -p 29418 review.example.com gerrit ls-groups --project MyProject
MyProject_Committers
Project Owners
Registered Users
=====
Extract the UUID of the 'Administrators' group:
=====
$ ssh -p 29418 review.example.com gerrit ls-groups -v | awk '-F\t' '$1 == "Administrators" {print $2}'
ad463411db3eec4e1efb0d73f55183c1db2fd82a
=====
Extract and expand the multi-line description of the 'Administrators'
group:
=====
$ printf "$(ssh -p 29418 review.example.com gerrit ls-groups -v | awk '-F\t' '$1 == "Administrators" {print $3}')\n"
This is a
multi-line
description.
=====
GERRIT
------
Part of link:index.html[Gerrit Code Review]