| = Gerrit Code Review - Searching Changes | |
| == Default Searches | |
| Most basic searches can be viewed by clicking on a link along the top | |
| menu bar. The link will prefill the search box with a common search | |
| query, execute it, and present the results. | |
| [options="header"] | |
| |================================================= | |
| |Description | Default Query | |
| |All > Open | status:open '(or is:open)' | |
| |All > Merged | status:merged | |
| |All > Abandoned | status:abandoned | |
| |My > Watched Changes | is:watched is:open | |
| |My > Starred Changes | is:starred | |
| |My > Draft Comments | has:draft | |
| |Open changes in Foo | status:open project:Foo | |
| |================================================= | |
| == Basic Change Search | |
| Similar to many popular search engines on the web, just enter some | |
| text and let Gerrit figure out the meaning: | |
| [options="header"] | |
| |============================================================= | |
| |Description | Examples | |
| |Legacy numerical id | 15183 | |
| |Full or abbreviated Change-Id | Ic0ff33 | |
| |Full or abbreviated commit SHA-1 | d81b32ef | |
| |Email address | user@example.com | |
| |============================================================= | |
| For change searches (i.e. those using a numerical id, Change-Id, or commit | |
| SHA1), if the search results in a single change that change will be | |
| presented instead of a list. | |
| For more predictable results, use explicit search operators as described | |
| in the following section. | |
| [[search-operators]] | |
| == Search Operators | |
| Operators act as restrictions on the search. As more operators | |
| are added to the same query string, they further restrict the | |
| returned results. Search can also be performed by typing only a | |
| text with no operator, which will match against a variety of fields. | |
| [[age]] | |
| age:'AGE':: | |
| + | |
| Amount of time that has expired since the change was last updated | |
| with a review comment or new patch set. The age must be specified | |
| to include a unit suffix, for example `age:2d`: | |
| + | |
| * s, sec, second, seconds | |
| * m, min, minute, minutes | |
| * h, hr, hour, hours | |
| * d, day, days | |
| * w, week, weeks (`1 week` is treated as `7 days`) | |
| * mon, month, months (`1 month` is treated as `30 days`) | |
| * y, year, years (`1 year` is treated as `365 days`) | |
| [[assignee]] | |
| assignee:'USER':: | |
| + | |
| Changes assigned to the given user. | |
| [[before_until]] | |
| before:'TIME'/until:'TIME':: | |
| + | |
| Changes modified before the given 'TIME', inclusive. Must be in the | |
| format `2006-01-02[ 15:04:05[.890][ -0700]]`; omitting the time defaults | |
| to 00:00:00 and omitting the timezone defaults to UTC. | |
| [[after_since]] | |
| after:'TIME'/since:'TIME':: | |
| + | |
| Changes modified after the given 'TIME', inclusive. Must be in the | |
| format `2006-01-02[ 15:04:05[.890][ -0700]]`; omitting the time defaults | |
| to 00:00:00 and omitting the timezone defaults to UTC. | |
| [[change]] | |
| change:'ID':: | |
| + | |
| Either a legacy numerical 'ID' such as 15183, or a newer style | |
| Change-Id that was scraped out of the commit message. | |
| [[conflicts]] | |
| conflicts:'ID':: | |
| + | |
| Changes that conflict with change 'ID'. Change 'ID' can be specified | |
| as a legacy numerical 'ID' such as 15183, or a newer style Change-Id | |
| that was scraped out of the commit message. | |
| [[destination]] | |
| destination:'NAME':: | |
| + | |
| Changes which match the current user's destination named 'NAME'. | |
| (see link:user-named-destinations.html[Named Destinations]). | |
| [[owner]] | |
| owner:'USER', o:'USER':: | |
| + | |
| Changes originally submitted by 'USER'. The special case of | |
| `owner:self` will find changes owned by the caller. | |
| [[ownerin]] | |
| ownerin:'GROUP':: | |
| + | |
| Changes originally submitted by a user in 'GROUP'. When no other index | |
| predicate is explicitly added in the query, defaults to only include | |
| changes in status 'OPEN'. | |
| [[query]] | |
| query:'NAME':: | |
| + | |
| Changes which match the current user's query named 'NAME' | |
| (see link:user-named-queries.html[Named Queries]). | |
| [[reviewer]] | |
| reviewer:'USER', r:'USER':: | |
| + | |
| Changes that have been, or need to be, reviewed by 'USER'. The | |
| special case of `reviewer:self` will find changes where the caller | |
| has been added as a reviewer. | |
| [[cc]] | |
| cc:'USER':: | |
| + | |
| Changes that have the given user CC'ed on them. The special case of `cc:self` | |
| will find changes where the caller has been CC'ed. | |
| [[revertof]] | |
| revertof:'ID':: | |
| + | |
| Changes that revert the change specified by the numeric 'ID'. | |
| [[reviewerin]] | |
| reviewerin:'GROUP':: | |
| + | |
| Changes that have been, or need to be, reviewed by a user in 'GROUP'. When | |
| no other index predicate is explicitly added in the query, defaults to only | |
| include changes in status 'OPEN'. | |
| [[commit]] | |
| commit:'SHA1':: | |
| + | |
| Changes where 'SHA1' is one of the patch sets of the change. | |
| [[project]] | |
| project:'PROJECT', p:'PROJECT':: | |
| + | |
| Changes occurring in 'PROJECT'. If 'PROJECT' starts with `^` it | |
| matches project names by regular expression. The | |
| link:http://www.brics.dk/automaton/[dk.brics.automaton | |
| library] is used for evaluation of such patterns. | |
| [[projects]] | |
| projects:'PREFIX':: | |
| + | |
| Changes occurring in projects starting with 'PREFIX'. | |
| [[parentproject]] | |
| parentproject:'PROJECT':: | |
| + | |
| Changes occurring in 'PROJECT' or in one of the child projects of | |
| 'PROJECT'. | |
| [[branch]] | |
| branch:'BRANCH':: | |
| + | |
| Changes for 'BRANCH'. The branch name is either the short name shown | |
| in the web interface or the full name of the destination branch with | |
| the traditional 'refs/heads/' prefix. | |
| + | |
| If 'BRANCH' starts with `^` it matches branch names by regular | |
| expression patterns. The | |
| link:http://www.brics.dk/automaton/[dk.brics.automaton | |
| library] is used for evaluation of such patterns. | |
| [[intopic]] | |
| intopic:'TOPIC':: | |
| + | |
| Changes whose designated topic contains 'TOPIC', using a full-text search. | |
| + | |
| If 'TOPIC' starts with `^` it matches topic names by regular | |
| expression patterns. The | |
| link:http://www.brics.dk/automaton/[dk.brics.automaton | |
| library] is used for evaluation of such patterns. | |
| [[topic]] | |
| topic:'TOPIC':: | |
| + | |
| Changes whose designated topic matches 'TOPIC' exactly. This is | |
| often combined with 'branch:' and 'project:' operators to select | |
| all related changes in a series. | |
| [[hashtag]] | |
| hashtag:'HASHTAG':: | |
| + | |
| Changes whose link:intro-user.html#hashtags[hashtag] matches 'HASHTAG' exactly. | |
| [[ref]] | |
| ref:'REF':: | |
| + | |
| Changes where the destination branch is exactly the given 'REF' | |
| name. Since 'REF' is absolute from the top of the repository it | |
| must start with 'refs/'. | |
| + | |
| If 'REF' starts with `^` it matches reference names by regular | |
| expression patterns. The | |
| link:http://www.brics.dk/automaton/[dk.brics.automaton | |
| library] is used for evaluation of such patterns. | |
| [[tr,bug]] | |
| tr:'ID', bug:'ID':: | |
| + | |
| Search for changes whose commit message contains 'ID' and matches | |
| one or more of the | |
| link:config-gerrit.html#trackingid[trackingid sections] | |
| in the server's configuration file. This is typically used to | |
| search for changes that fix a bug or defect by the issue tracking | |
| system's issue identifier. | |
| [[label]] | |
| label:'VALUE':: | |
| + | |
| Matches changes where the approval score 'VALUE' has been set during | |
| a review. See <<labels,labels>> below for more detail on the format | |
| of the argument. | |
| [[message]] | |
| message:'MESSAGE':: | |
| + | |
| Changes that match 'MESSAGE' arbitrary string in the commit message body. | |
| [[comment]] | |
| comment:'TEXT':: | |
| + | |
| Changes that match 'TEXT' string in any comment left by a reviewer. | |
| [[path]] | |
| path:'PATH':: | |
| + | |
| Matches any change touching file at 'PATH'. By default exact path | |
| matching is used, but regular expressions can be enabled by starting | |
| with `^`. For example, to match all XML files use `file:^.*\.xml$`. | |
| The link:http://www.brics.dk/automaton/[dk.brics.automaton library] | |
| is used for the evaluation of such patterns. | |
| + | |
| The `^` required at the beginning of the regular expression not only | |
| denotes a regular expression, but it also has the usual meaning of | |
| anchoring the match to the start of the string. To match all Java | |
| files, use `file:^.*\.java`. | |
| + | |
| The entire regular expression pattern, including the `^` character, | |
| should be double quoted when using more complex construction (like | |
| ones using a bracket expression). For example, to match all XML | |
| files named like 'name1.xml', 'name2.xml', and 'name3.xml' use | |
| `file:"^name[1-3].xml"`. | |
| [[file]] | |
| file:'NAME', f:'NAME':: | |
| + | |
| Matches any change touching a file containing the path component | |
| 'NAME'. For example a `file:src` will match changes that modify | |
| files named `gerrit-server/src/main/java/Foo.java`. Name matching | |
| is exact match, `file:Foo.java` finds any change touching a file | |
| named exactly `Foo.java` and does not match `AbstractFoo.java`. | |
| + | |
| Regular expression matching can be enabled by starting the string | |
| with `^`. In this mode `file:` is an alias of `path:` (see above). | |
| [[star]] | |
| star:'LABEL':: | |
| + | |
| Matches any change that was starred by the current user with the label | |
| 'LABEL'. | |
| + | |
| E.g. if changes that are not interesting are marked with an `ignore` | |
| star, they could be filtered out by '-star:ignore'. | |
| + | |
| 'star:star' is the same as 'has:star' and 'is:starred'. | |
| [[has]] | |
| has:draft:: | |
| + | |
| True if there is a draft comment saved by the current user. | |
| [[has-star]] | |
| has:star:: | |
| + | |
| Same as 'is:starred' and 'star:star', true if the change has been | |
| starred by the current user with the default label. | |
| [[has-stars]] | |
| has:stars:: | |
| + | |
| True if the change has been starred by the current user with any label. | |
| has:edit:: | |
| + | |
| True if the change has inline edit created by the current user. | |
| has:unresolved:: | |
| + | |
| True if the change has unresolved comments. | |
| [[is]] | |
| is:assigned:: | |
| + | |
| True if the change has an assignee. | |
| [[is-starred]] | |
| is:starred:: | |
| + | |
| Same as 'has:star', true if the change has been starred by the | |
| current user with the default label. | |
| is:unassigned:: | |
| + | |
| True if the change does not have an assignee. | |
| is:watched:: | |
| + | |
| True if this change matches one of the current user's watch filters, | |
| and thus is likely to notify the user when it updates. | |
| is:reviewed:: | |
| + | |
| True if any user has commented on the change more recently than the | |
| last update (comment or patch set) from the change owner. | |
| is:owner:: | |
| + | |
| True on any change where the current user is the change owner. | |
| Same as `owner:self`. | |
| is:reviewer:: | |
| + | |
| True on any change where the current user is a reviewer. | |
| Same as `reviewer:self`. | |
| is:cc:: | |
| + | |
| True on any change where the current user is in CC. | |
| Same as `cc:self`. | |
| is:open, is:pending:: | |
| + | |
| True if the change is open. | |
| is:closed:: | |
| + | |
| True if the change is either merged or abandoned. | |
| is:merged, is:abandoned:: | |
| + | |
| Same as <<status,status:'STATE'>>. | |
| is:submittable:: | |
| + | |
| True if the change is submittable according to the submit rules for | |
| the project, for example if all necessary labels have been voted on. | |
| + | |
| This operator only takes into account one change at a time, not any | |
| related changes, and does not guarantee that the submit button will | |
| appear for matching changes. To check whether a submit button appears, | |
| use the | |
| link:rest-api-changes.html#get-revision-actions[Get Revision Actions] | |
| API. | |
| + | |
| Equivalent to <<submittable,submittable:ok>>. | |
| [[mergeable]] | |
| is:mergeable:: | |
| + | |
| True if the change has no merge conflicts and could be merged into its | |
| destination branch. | |
| + | |
| Mergeability of abandoned changes is not computed. This operator will | |
| not find any abandoned but mergeable changes. | |
| [[ignored]] | |
| is:ignored:: | |
| + | |
| True if the change is ignored. Same as `star:ignore`. | |
| [[private]] | |
| is:private:: | |
| + | |
| True if the change is private, ie. only visible to owner and its | |
| reviewers. | |
| [[workInProgress]] | |
| is:wip:: | |
| + | |
| True if the change is Work In Progress. | |
| [[status]] | |
| status:open, status:pending:: | |
| + | |
| True if the change state is 'review in progress'. | |
| status:reviewed:: | |
| + | |
| Same as 'is:reviewed', matches if any user has commented on the change | |
| more recently than the last update (comment or patch set) from the | |
| change owner. | |
| status:closed:: | |
| + | |
| True if the change is either 'merged' or 'abandoned'. | |
| status:merged:: | |
| + | |
| Change has been merged into the branch. | |
| status:abandoned:: | |
| + | |
| Change has been abandoned. | |
| [[size]] | |
| added:'RELATION''LINES', deleted:'RELATION''LINES', delta/size:'RELATION''LINES':: | |
| + | |
| True if the number of lines added/deleted/changed satisfies the given relation | |
| for the given number of lines. | |
| + | |
| For example, added:>50 will be true for any change which adds at least 50 | |
| lines. | |
| + | |
| Valid relations are >=, >, <=, <, or no relation, which will match if the | |
| number of lines is exactly equal. | |
| [[commentby]] | |
| commentby:'USER':: | |
| + | |
| Changes containing a top-level or inline comment by 'USER'. The special | |
| case of `commentby:self` will find changes where the caller has | |
| commented. | |
| [[from]] | |
| from:'USER':: | |
| + | |
| Changes containing a top-level or inline comment by 'USER', or owned by | |
| 'USER'. Equivalent to `(owner:USER OR commentby:USER)`. | |
| [[reviewedby]] | |
| reviewedby:'USER':: | |
| + | |
| Changes where 'USER' has commented on the change more recently than the | |
| last update (comment or patch set) from the change owner. | |
| [[author]] | |
| author:'AUTHOR':: | |
| + | |
| Changes where 'AUTHOR' is the author of the current patch set. 'AUTHOR' may be | |
| the author's exact email address, or part of the name or email address. | |
| [[committer]] | |
| committer:'COMMITTER':: | |
| + | |
| Changes where 'COMMITTER' is the committer of the current patch set. | |
| 'COMMITTER' may be the committer's exact email address, or part of the name or | |
| email address. | |
| [[submittable]] | |
| submittable:'SUBMIT_STATUS':: | |
| + | |
| Changes having the given submit record status after applying submit | |
| rules. Valid statuses are in the `status` field of | |
| link:rest-api-changes.html#submit-record[SubmitRecord]. This operator | |
| only applies to the top-level status; individual label statuses can be | |
| searched link:#labels[by label]. | |
| [[unresolved]] | |
| unresolved:'RELATION''NUMBER':: | |
| + | |
| True if the number of unresolved comments satisfies the given relation for the given number. | |
| + | |
| For example, unresolved:>0 will be true for any change which has at least one unresolved | |
| comment while unresolved:0 will be true for any change which has all comments resolved. | |
| + | |
| Valid relations are >=, >, <=, <, or no relation, which will match if the number of unresolved | |
| comments is exactly equal. | |
| == Argument Quoting | |
| Operator values that are not bare words (roughly A-Z, a-z, 0-9, @, | |
| hyphen, dot and underscore) must be quoted for the query parser. | |
| Quoting is accepted as either double quotes | |
| (e.g. `message:"the value"`) or as matched | |
| curly braces (e.g. `message:{the value}`). | |
| == Boolean Operators | |
| Unless otherwise specified, operators are joined using the `AND` | |
| boolean operator, thereby restricting the search results. | |
| Parentheses can be used to force a particular precedence on complex | |
| operator expressions, otherwise OR has higher precedence than AND. | |
| === Negation | |
| Any operator can be negated by prefixing it with `-`, for example | |
| `-is:starred` is the exact opposite of `is:starred` and will | |
| therefore return changes that are *not* starred by the current user. | |
| The operator `NOT` (in all caps) is a synonym. | |
| === AND | |
| The boolean operator `AND` (in all caps) can be used to join two | |
| other operators together. This results in a restriction of the | |
| results, returning only changes that match both operators. | |
| === OR | |
| The boolean operator `OR` (in all caps) can be used to find changes | |
| that match either operator. This increases the number of results | |
| that are returned, as more changes are considered. | |
| [[labels]] | |
| == Labels | |
| Label operators can be used to match approval scores given during | |
| a code review. The specific set of supported labels depends on | |
| the server configuration, however the `Code-Review` label is provided | |
| out of the box. | |
| A label name is any of the following: | |
| * The label name. Example: `label:Code-Review`. | |
| * The label name followed by a ',' followed by a reviewer id or a | |
| group id. To make it clear whether a user or group is being looked | |
| for, precede the value by a user or group argument identifier | |
| ('user=' or 'group='). If an LDAP group is being referenced make | |
| sure to use 'ldap/<groupname>'. | |
| A label name must be followed by either a score with optional operator, | |
| or a label status. The easiest way to explain this is by example. | |
| First, some examples of scores with operators: | |
| `label:Code-Review=2`:: | |
| `label:Code-Review=+2`:: | |
| `label:Code-Review+2`:: | |
| + | |
| Matches changes where there is at least one +2 score for Code-Review. | |
| The + prefix is optional for positive score values. If the + is used, | |
| the = operator is optional. | |
| `label:Code-Review=-2`:: | |
| `label:Code-Review-2`:: | |
| + | |
| Matches changes where there is at least one -2 score for Code-Review. | |
| Because the negative sign is required, the = operator is optional. | |
| `label:Code-Review=1`:: | |
| + | |
| Matches changes where there is at least one +1 score for Code-Review. | |
| Scores of +2 are not matched, even though they are higher. | |
| `label:Code-Review>=1`:: | |
| + | |
| Matches changes with either a +1, +2, or any higher score. | |
| + | |
| Instead of a numeric vote, you can provide a label status corresponding | |
| to one of the fields in the | |
| link:rest-api-changes.html#submit-record[SubmitRecord] REST API entity. | |
| `label:Non-Author-Code-Review=need`:: | |
| + | |
| Matches changes where the submit rules indicate that a label named | |
| `Non-Author-Code-Review` is needed. (See the | |
| link:prolog-cookbook.html#NonAuthorCodeReview[Prolog Cookbook] for how | |
| this label can be configured.) | |
| `label:Code-Review=+2,aname`:: | |
| `label:Code-Review=ok,aname`:: | |
| + | |
| Matches changes with a +2 code review where the reviewer or group is aname. | |
| `label:Code-Review=2,user=jsmith`:: | |
| + | |
| Matches changes with a +2 code review where the reviewer is jsmith. | |
| `label:Code-Review=+2,user=owner`:: | |
| `label:Code-Review=ok,user=owner`:: | |
| `label:Code-Review=+2,owner`:: | |
| `label:Code-Review=ok,owner`:: | |
| + | |
| The special "owner" parameter corresponds to the change owner. Matches | |
| all changes that have a +2 vote from the change owner. | |
| `label:Code-Review=+1,group=ldap/linux.workflow`:: | |
| + | |
| Matches changes with a +1 code review where the reviewer is in the | |
| ldap/linux.workflow group. | |
| `label:Code-Review<=-1`:: | |
| + | |
| Matches changes with either a -1, -2, or any lower score. | |
| `is:open label:Code-Review+2 label:Verified+1 NOT label:Verified-1 NOT label:Code-Review-2`:: | |
| `is:open label:Code-Review=ok label:Verified=ok`:: | |
| + | |
| Matches changes that are ready to be submitted according to one common | |
| label configuration. (For a more general check, use | |
| link:#submittable[submittable:ok].) | |
| `is:open (label:Verified-1 OR label:Code-Review-2)`:: | |
| `is:open (label:Verified=reject OR label:Code-Review=reject)`:: | |
| + | |
| Changes that are blocked from submission due to a blocking score. | |
| == Magical Operators | |
| Most of these operators exist to support features of Gerrit Code | |
| Review, and are not meant to be accessed by the average end-user. | |
| However, they are recognized by the query parser, and may prove | |
| useful in limited contexts to administrators or power-users. | |
| visibleto:'USER-or-GROUP':: | |
| + | |
| Matches changes that are visible to 'USER' or to anyone who is a | |
| member of 'GROUP'. Here group names may be specified as either | |
| an internal group name, or if LDAP is being used, an external LDAP | |
| group name. The value may be wrapped in double quotes to include | |
| spaces or other special characters. For example, to match an LDAP | |
| group: `visibleto:"CN=Developers, DC=example, DC=com"`. | |
| + | |
| This operator may be useful to test access control rules, however a | |
| change can only be matched if both the current user and the supplied | |
| user or group can see it. This is due to the implicit 'is:visible' | |
| clause that is always added by the server. | |
| is:visible:: | |
| + | |
| Magical internal flag to prove the current user has access to read | |
| the change. This flag is always added to any query. | |
| starredby:'USER':: | |
| + | |
| Matches changes that have been starred by 'USER' with the default label. | |
| The special case `starredby:self` applies to the caller. | |
| watchedby:'USER':: | |
| + | |
| Matches changes that 'USER' has configured watch filters for. | |
| The special case `watchedby:self` applies to the caller. | |
| draftby:'USER':: | |
| + | |
| Matches changes that 'USER' has left unpublished draft comments on. | |
| Since the drafts are unpublished, it is not possible to see the | |
| draft text, or even how many drafts there are. The special case | |
| of `draftby:self` will find changes where the caller has created | |
| a draft comment. | |
| [[limit]] | |
| limit:'CNT':: | |
| + | |
| Limit the returned results to no more than 'CNT' records. This is | |
| automatically set to the page size configured in the current user's | |
| preferences. Including it in a web query may lead to unpredictable | |
| results with regards to pagination. | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |