blob: d0419d7bff02b43854133b76f968933fbbf38964 [file] [log] [blame]
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08001= gerrit query
Shawn O. Pearce14760b72010-07-19 09:44:46 -07002
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08003== NAME
Dave Borowitzada289c2018-12-18 13:24:14 -08004gerrit query - Query the change search index
Shawn O. Pearce14760b72010-07-19 09:44:46 -07005
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -08006== SYNOPSIS
Michael Ochmanne2d76a12016-06-23 17:07:37 +02007[verse]
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -08008--
Michael Ochmanne2d76a12016-06-23 17:07:37 +02009_ssh_ -p <port> <host> _gerrit query_
Shawn O. Pearce47769242011-06-14 16:40:48 -070010 [--format {TEXT | JSON}]
11 [--current-patch-set]
12 [--patch-sets | --all-approvals]
Gustaf Lundh2ebc42d2011-11-02 17:21:05 +010013 [--files]
Mika Hamalainen0917a2b2011-07-22 14:21:28 +030014 [--comments]
Brad Larson0943d6e2011-10-27 19:36:27 -050015 [--commit-message]
Gregory Beane7232c42012-02-23 11:03:40 -080016 [--dependencies]
James E. Blair3fe3d3f2012-07-20 17:11:37 -070017 [--submit-records]
Mani Chandel72cb6032013-10-17 17:12:03 +053018 [--all-reviewers]
David Ostrovsky68550182014-08-09 03:32:08 +020019 [--start <n> | -S <n>]
Martin Fickb186cd72018-12-02 23:34:23 -070020 [--no-limit]
Shawn O. Pearce47769242011-06-14 16:40:48 -070021 [--]
22 <query>
23 [limit:<n>]
Yuxuan 'fishy' Wangd85b6872013-11-15 11:47:46 -080024--
Shawn O. Pearce14760b72010-07-19 09:44:46 -070025
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080026== DESCRIPTION
Shawn O. Pearce14760b72010-07-19 09:44:46 -070027
Dave Borowitzada289c2018-12-18 13:24:14 -080028Queries the change search index and returns results describing changes
Shawn O. Pearce14760b72010-07-19 09:44:46 -070029that match the input query. More recently updated changes appear
30before older changes, which is the same order presented in the
David Pursehouse93a4ae62013-05-01 13:50:09 +090031web interface. For each matching change, the result contains data
32for the change's latest patch set, even if the query matched on an
33older patch set (for example an older patch set's sha1 revision).
Shawn O. Pearce14760b72010-07-19 09:44:46 -070034
35A query may be limited on the number of results it returns with the
36'limit:' operator. If no limit is supplied an internal default
37limit is used to prevent explosion of the result set. To obtain
Alan Tokaev098272e2014-08-08 23:22:01 +020038results beyond the limit, the '--start' flag can be used to resume
39the query after skipping a certain number of results.
Shawn O. Pearce14760b72010-07-19 09:44:46 -070040
Shawn O. Pearce757df062012-11-30 11:20:37 -080041Non-option arguments to this command are joined with spaces and
42then parsed as a query. This simplifies calling conventions over
43SSH by permitting operators to appear in different arguments.
44
David Pursehouse93a4ae62013-05-01 13:50:09 +090045Query operators may quote values using matched curly braces
Shawn O. Pearce757df062012-11-30 11:20:37 -080046(e.g. `reviewerin:{Developer Group}`) to sidestep issues with 2
47levels of shell quoting (caller shell invoking SSH, and the SSH
48command line parser in the server).
Shawn O. Pearce14760b72010-07-19 09:44:46 -070049
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -080050== OPTIONS
Shawn O. Pearce47769242011-06-14 16:40:48 -070051--format::
David Pursehouse93a4ae62013-05-01 13:50:09 +090052 Formatting method for the results. `TEXT` is the default,
53 presenting a human readable display. `JSON` returns
54 link:json.html#change[change attributes], one line
Shawn O. Pearce47769242011-06-14 16:40:48 -070055 per matching record, with embedded LFs escaped.
56
57--current-patch-set::
Shawn O. Pearce14760b72010-07-19 09:44:46 -070058 Include information about the current patch set in the results.
David Pursehousee2f4c2f2016-04-18 17:59:44 +090059 Note that the information will only be included when the current
60 patch set is visible to the caller.
Shawn O. Pearce14760b72010-07-19 09:44:46 -070061
Shawn O. Pearce47769242011-06-14 16:40:48 -070062--patch-sets::
David Pursehousee2f4c2f2016-04-18 17:59:44 +090063 Include information about all patch sets visible to the caller.
64 If combined with the --current-patch-set flag then the current patch
65 set information will be output twice, once in each field.
Shawn O. Pearce14760b72010-07-19 09:44:46 -070066
Shawn O. Pearce47769242011-06-14 16:40:48 -070067--all-approvals::
David Pursehousee2f4c2f2016-04-18 17:59:44 +090068 Include information about all patch sets visible to the caller along
69 with the approval information for each patch set. If combined with
Shawn O. Pearce47769242011-06-14 16:40:48 -070070 the --current-patch-set flag then the current patch set
Martin Fickdb3be252010-09-15 13:59:54 -060071 information will be output twice, once in each field.
72
Gustaf Lundh2ebc42d2011-11-02 17:21:05 +010073--files::
74 Support for listing files with patch sets and their
Bruce Zu1a9be5e2012-10-09 14:49:39 +080075 attributes (ADDED, MODIFIED, DELETED, RENAMED, COPIED)
76 and size information (number of insertions and deletions).
thomas.westling5a4d61b2011-12-29 16:34:45 +010077 Note that this option requires either the --current-patch-set
78 or the --patch-sets option in order to give any file information.
Gustaf Lundh2ebc42d2011-11-02 17:21:05 +010079
Mika Hamalainen0917a2b2011-07-22 14:21:28 +030080--comments::
81 Include comments for all changes. If combined with the
Bruce Zu6b0fd762012-10-25 16:52:00 +080082 --patch-sets flag then all inline/file comments are included for
David Pursehousee2f4c2f2016-04-18 17:59:44 +090083 each patch set that is visible to the caller.
Mika Hamalainen0917a2b2011-07-22 14:21:28 +030084
Brad Larson0943d6e2011-10-27 19:36:27 -050085--commit-message::
86 Include the full commit message in the change description.
87
Gregory Beane7232c42012-02-23 11:03:40 -080088--dependencies::
89 Show information about patch sets which depend on, or are needed by,
90 each patch set.
91
Mani Chandel72cb6032013-10-17 17:12:03 +053092--all-reviewers::
93 Show the name and email of all reviewers which are added to a change
94 (irrespective of whether they have been voting on that change or not).
95
James E. Blair3fe3d3f2012-07-20 17:11:37 -070096--submit-records::
97 Show submit record information about the change, which
98 includes whether the change meets the criteria for submission
99 (including information for each review label).
100
David Ostrovsky68550182014-08-09 03:32:08 +0200101--start::
102-S::
103 Number of changes to skip.
104
Martin Fickb186cd72018-12-02 23:34:23 -0700105--no-limit::
106 Return all results, overriding the default limit.
107
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700108limit:<n>::
109 Maximum number of results to return. This is actually a
110 query operator, and not a command line option. If more
111 than one limit: operator is provided, the smallest limit
112 will be used to cut the result set.
113
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800114== ACCESS
Gert van Dijkdc4f8d12017-08-27 21:14:23 +0200115Any user who has SSH access to Gerrit.
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700116
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800117== SCRIPTING
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700118This command is intended to be used in scripts.
119
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800120== EXAMPLES
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700121
122Find the 2 most recent open changes in the tools/gerrit project:
Michael Ochmannb99feab2016-07-06 14:10:22 +0200123----
David Shevitzc47f2362018-09-27 10:55:35 -0700124$ ssh -p 29418 review.example.com gerrit query --format=JSON status:open project:tools/gerrit limit:2
125{"project":"tools/gerrit", ...}
126{"project":"tools/gerrit", ...}
127{"type":"stats","rowCount":2,"runningTimeMilliseconds:15}
Michael Ochmannb99feab2016-07-06 14:10:22 +0200128----
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700129
Alan Tokaev098272e2014-08-08 23:22:01 +0200130Skip number of changes:
Michael Ochmannb99feab2016-07-06 14:10:22 +0200131----
David Shevitzc47f2362018-09-27 10:55:35 -0700132$ ssh -p 29418 review.example.com gerrit query --format=JSON --start 42 status:open project:tools/gerrit limit:2
133{"project":"tools/gerrit", ...}
134{"project":"tools/gerrit", ...}
135{"type":"stats","rowCount":1,"runningTimeMilliseconds:15}
Michael Ochmannb99feab2016-07-06 14:10:22 +0200136----
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700137
138
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800139== SCHEMA
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700140The JSON messages consist of nested objects referencing the
141link:json.html#change[change],
Edwin Kempina319d352012-09-06 10:28:11 +0200142link:json.html#patchSet[patchset],
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700143link:json.html#[account]
144involved, and other attributes as appropriate.
145
146Note that any field may be missing in the JSON messages, so consumers
147of this JSON stream should deal with that appropriately.
148
Yuxuan 'fishy' Wang61698b12013-12-20 12:55:51 -0800149== SEE ALSO
Shawn O. Pearce14760b72010-07-19 09:44:46 -0700150
151* link:user-search.html[Query Operators]
152* link:json.html[JSON Data Formats]
153* link:access-control.html[Access Controls]
154
155GERRIT
156------
157Part of link:index.html[Gerrit Code Review]
Yuxuan 'fishy' Wang99cb68d2013-10-31 17:26:00 -0700158
159SEARCHBOX
160---------