Support to check via REST if a group is owned by the calling user

It is now possible to list the groups that are owned by a user by
GET on '/groups/?owned&user=<user>'. If the 'user' parameter is
omitted the owned groups of the calling user are listed.

Groups can be added by the 'q' parameter to limit the result to
those groups that are of interest to the caller, e.g. if a user wants
to check if he owns group 'MyGroup' he can send this request:
  GET /groups/?owned&q=MyGroup
If the group is returned the user owns 'MyGroup'.

Change-Id: I09bc99ce0fb60a40320a26d592257408ef2d9c75
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>

Documentation/cmd-ls-groups.txt

diff --git a/Documentation/cmd-ls-groups.txt b/Documentation/cmd-ls-groups.txt
index 91b9e3e..17ebba1 100644
--- a/Documentation/cmd-ls-groups.txt
+++ b/Documentation/cmd-ls-groups.txt
@@ -11,8 +11,10 @@
 'ssh' -p <port> <host> 'gerrit ls-groups'
   [--project <NAME> | -p <NAME>]
   [--user <NAME> | -u <NAME>]
+  [--owned]
   [--visible-to-all]
   [--type {internal | system}]
+  [-q <GROUP>]
   [--verbose | -v]
 
 DESCRIPTION
@@ -61,6 +63,11 @@
 +
 This option can't be used together with the '--project' option.
 
+--owned::
+	Lists only the groups that are owned by the user that was specified
+	by the `--user` option or if no user was specified the groups that
+	are owned by the calling user.
+
 --visible-to-all::
 	Displays only groups that are visible to all registered users
 	(groups that are explicitly marked as visible to all registered
@@ -75,6 +82,14 @@
 `system`:: Any system defined and managed group.
 --
 
+-q::
+	Group that should be inspected. The `-q` option can be specified
+	multiple times to define several groups to be inspected. If
+	specified the listed groups will only contain groups that were
+	specified to be inspected. This is e.g. useful in combination with
+	the `--owned` and `--user` options to check whether a group is
+	owned by a user.
+
 --verbose::
 -v::
 	Enable verbose output with tab-separated columns for the
@@ -106,6 +121,21 @@
 	Registered Users
 =====
 
+List all groups which are owned by the calling user:
+=====
+	$ ssh -p 29418 review.example.com gerrit ls-groups --owned
+	MyProject_Committers
+	MyProject_Verifiers
+=====
+
+Check if the calling user owns the group `MyProject_Committers`. If
+`MyProject_Committers` is returned the calling user owns this group.
+If the result is empty, the calling user doesn't own the group.
+=====
+	$ ssh -p 29418 review.example.com gerrit ls-groups --owned -q MyProject_Committers
+	MyProject_Committers
+=====
+
 Extract the UUID of the 'Administrators' group:
 
 =====