Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 1 | = gerrit query |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 2 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 3 | == NAME |
Dave Borowitz | ada289c | 2018-12-18 13:24:14 -0800 | [diff] [blame] | 4 | gerrit query - Query the change search index |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 5 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 6 | == SYNOPSIS |
Michael Ochmann | e2d76a1 | 2016-06-23 17:07:37 +0200 | [diff] [blame] | 7 | [verse] |
Yuxuan 'fishy' Wang | d85b687 | 2013-11-15 11:47:46 -0800 | [diff] [blame] | 8 | -- |
Michael Ochmann | e2d76a1 | 2016-06-23 17:07:37 +0200 | [diff] [blame] | 9 | _ssh_ -p <port> <host> _gerrit query_ |
Shawn O. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 10 | [--format {TEXT | JSON}] |
| 11 | [--current-patch-set] |
| 12 | [--patch-sets | --all-approvals] |
Gustaf Lundh | 2ebc42d | 2011-11-02 17:21:05 +0100 | [diff] [blame] | 13 | [--files] |
Mika Hamalainen | 0917a2b | 2011-07-22 14:21:28 +0300 | [diff] [blame] | 14 | [--comments] |
Brad Larson | 0943d6e | 2011-10-27 19:36:27 -0500 | [diff] [blame] | 15 | [--commit-message] |
Gregory Bean | e7232c4 | 2012-02-23 11:03:40 -0800 | [diff] [blame] | 16 | [--dependencies] |
James E. Blair | 3fe3d3f | 2012-07-20 17:11:37 -0700 | [diff] [blame] | 17 | [--submit-records] |
Mani Chandel | 72cb603 | 2013-10-17 17:12:03 +0530 | [diff] [blame] | 18 | [--all-reviewers] |
David Ostrovsky | 6855018 | 2014-08-09 03:32:08 +0200 | [diff] [blame] | 19 | [--start <n> | -S <n>] |
Martin Fick | b186cd7 | 2018-12-02 23:34:23 -0700 | [diff] [blame] | 20 | [--no-limit] |
Shawn O. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 21 | [--] |
| 22 | <query> |
| 23 | [limit:<n>] |
Yuxuan 'fishy' Wang | d85b687 | 2013-11-15 11:47:46 -0800 | [diff] [blame] | 24 | -- |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 25 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 26 | == DESCRIPTION |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 27 | |
Dave Borowitz | ada289c | 2018-12-18 13:24:14 -0800 | [diff] [blame] | 28 | Queries the change search index and returns results describing changes |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 29 | that match the input query. More recently updated changes appear |
| 30 | before older changes, which is the same order presented in the |
David Pursehouse | 93a4ae6 | 2013-05-01 13:50:09 +0900 | [diff] [blame] | 31 | web interface. For each matching change, the result contains data |
| 32 | for the change's latest patch set, even if the query matched on an |
| 33 | older patch set (for example an older patch set's sha1 revision). |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 34 | |
| 35 | A query may be limited on the number of results it returns with the |
| 36 | 'limit:' operator. If no limit is supplied an internal default |
| 37 | limit is used to prevent explosion of the result set. To obtain |
Alan Tokaev | 098272e | 2014-08-08 23:22:01 +0200 | [diff] [blame] | 38 | results beyond the limit, the '--start' flag can be used to resume |
| 39 | the query after skipping a certain number of results. |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 40 | |
Shawn O. Pearce | 757df06 | 2012-11-30 11:20:37 -0800 | [diff] [blame] | 41 | Non-option arguments to this command are joined with spaces and |
| 42 | then parsed as a query. This simplifies calling conventions over |
| 43 | SSH by permitting operators to appear in different arguments. |
| 44 | |
David Pursehouse | 93a4ae6 | 2013-05-01 13:50:09 +0900 | [diff] [blame] | 45 | Query operators may quote values using matched curly braces |
Shawn O. Pearce | 757df06 | 2012-11-30 11:20:37 -0800 | [diff] [blame] | 46 | (e.g. `reviewerin:{Developer Group}`) to sidestep issues with 2 |
| 47 | levels of shell quoting (caller shell invoking SSH, and the SSH |
| 48 | command line parser in the server). |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 49 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 50 | == OPTIONS |
Shawn O. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 51 | --format:: |
David Pursehouse | 93a4ae6 | 2013-05-01 13:50:09 +0900 | [diff] [blame] | 52 | 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. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 55 | per matching record, with embedded LFs escaped. |
| 56 | |
| 57 | --current-patch-set:: |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 58 | Include information about the current patch set in the results. |
David Pursehouse | e2f4c2f | 2016-04-18 17:59:44 +0900 | [diff] [blame] | 59 | Note that the information will only be included when the current |
| 60 | patch set is visible to the caller. |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 61 | |
Shawn O. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 62 | --patch-sets:: |
David Pursehouse | e2f4c2f | 2016-04-18 17:59:44 +0900 | [diff] [blame] | 63 | 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. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 66 | |
Shawn O. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 67 | --all-approvals:: |
David Pursehouse | e2f4c2f | 2016-04-18 17:59:44 +0900 | [diff] [blame] | 68 | 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. Pearce | 4776924 | 2011-06-14 16:40:48 -0700 | [diff] [blame] | 70 | the --current-patch-set flag then the current patch set |
Martin Fick | db3be25 | 2010-09-15 13:59:54 -0600 | [diff] [blame] | 71 | information will be output twice, once in each field. |
| 72 | |
Gustaf Lundh | 2ebc42d | 2011-11-02 17:21:05 +0100 | [diff] [blame] | 73 | --files:: |
| 74 | Support for listing files with patch sets and their |
Bruce Zu | 1a9be5e | 2012-10-09 14:49:39 +0800 | [diff] [blame] | 75 | attributes (ADDED, MODIFIED, DELETED, RENAMED, COPIED) |
| 76 | and size information (number of insertions and deletions). |
thomas.westling | 5a4d61b | 2011-12-29 16:34:45 +0100 | [diff] [blame] | 77 | Note that this option requires either the --current-patch-set |
| 78 | or the --patch-sets option in order to give any file information. |
Gustaf Lundh | 2ebc42d | 2011-11-02 17:21:05 +0100 | [diff] [blame] | 79 | |
Mika Hamalainen | 0917a2b | 2011-07-22 14:21:28 +0300 | [diff] [blame] | 80 | --comments:: |
| 81 | Include comments for all changes. If combined with the |
Bruce Zu | 6b0fd76 | 2012-10-25 16:52:00 +0800 | [diff] [blame] | 82 | --patch-sets flag then all inline/file comments are included for |
David Pursehouse | e2f4c2f | 2016-04-18 17:59:44 +0900 | [diff] [blame] | 83 | each patch set that is visible to the caller. |
Mika Hamalainen | 0917a2b | 2011-07-22 14:21:28 +0300 | [diff] [blame] | 84 | |
Brad Larson | 0943d6e | 2011-10-27 19:36:27 -0500 | [diff] [blame] | 85 | --commit-message:: |
| 86 | Include the full commit message in the change description. |
| 87 | |
Gregory Bean | e7232c4 | 2012-02-23 11:03:40 -0800 | [diff] [blame] | 88 | --dependencies:: |
| 89 | Show information about patch sets which depend on, or are needed by, |
| 90 | each patch set. |
| 91 | |
Mani Chandel | 72cb603 | 2013-10-17 17:12:03 +0530 | [diff] [blame] | 92 | --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. Blair | 3fe3d3f | 2012-07-20 17:11:37 -0700 | [diff] [blame] | 96 | --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 Ostrovsky | 6855018 | 2014-08-09 03:32:08 +0200 | [diff] [blame] | 101 | --start:: |
| 102 | -S:: |
| 103 | Number of changes to skip. |
| 104 | |
Martin Fick | b186cd7 | 2018-12-02 23:34:23 -0700 | [diff] [blame] | 105 | --no-limit:: |
| 106 | Return all results, overriding the default limit. |
| 107 | |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 108 | limit:<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' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 114 | == ACCESS |
Gert van Dijk | dc4f8d1 | 2017-08-27 21:14:23 +0200 | [diff] [blame] | 115 | Any user who has SSH access to Gerrit. |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 116 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 117 | == SCRIPTING |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 118 | This command is intended to be used in scripts. |
| 119 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 120 | == EXAMPLES |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 121 | |
| 122 | Find the 2 most recent open changes in the tools/gerrit project: |
Michael Ochmann | b99feab | 2016-07-06 14:10:22 +0200 | [diff] [blame] | 123 | ---- |
David Shevitz | c47f236 | 2018-09-27 10:55:35 -0700 | [diff] [blame] | 124 | $ 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 Ochmann | b99feab | 2016-07-06 14:10:22 +0200 | [diff] [blame] | 128 | ---- |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 129 | |
Alan Tokaev | 098272e | 2014-08-08 23:22:01 +0200 | [diff] [blame] | 130 | Skip number of changes: |
Michael Ochmann | b99feab | 2016-07-06 14:10:22 +0200 | [diff] [blame] | 131 | ---- |
David Shevitz | c47f236 | 2018-09-27 10:55:35 -0700 | [diff] [blame] | 132 | $ 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 Ochmann | b99feab | 2016-07-06 14:10:22 +0200 | [diff] [blame] | 136 | ---- |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 137 | |
| 138 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 139 | == SCHEMA |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 140 | The JSON messages consist of nested objects referencing the |
| 141 | link:json.html#change[change], |
Edwin Kempin | a319d35 | 2012-09-06 10:28:11 +0200 | [diff] [blame] | 142 | link:json.html#patchSet[patchset], |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 143 | link:json.html#[account] |
| 144 | involved, and other attributes as appropriate. |
| 145 | |
| 146 | Note that any field may be missing in the JSON messages, so consumers |
| 147 | of this JSON stream should deal with that appropriately. |
| 148 | |
Yuxuan 'fishy' Wang | 61698b1 | 2013-12-20 12:55:51 -0800 | [diff] [blame] | 149 | == SEE ALSO |
Shawn O. Pearce | 14760b7 | 2010-07-19 09:44:46 -0700 | [diff] [blame] | 150 | |
| 151 | * link:user-search.html[Query Operators] |
| 152 | * link:json.html[JSON Data Formats] |
| 153 | * link:access-control.html[Access Controls] |
| 154 | |
| 155 | GERRIT |
| 156 | ------ |
| 157 | Part of link:index.html[Gerrit Code Review] |
Yuxuan 'fishy' Wang | 99cb68d | 2013-10-31 17:26:00 -0700 | [diff] [blame] | 158 | |
| 159 | SEARCHBOX |
| 160 | --------- |