Documentation/cmd-ls-groups.txt

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]