645 lines
19 KiB
Plaintext
645 lines
19 KiB
Plaintext
= 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. If exactly one change
|
|
matches the search, the change will be presented instead of a list.
|
|
|
|
|
|
[options="header"]
|
|
|=================================================
|
|
|Description | Default Query
|
|
|All > Open | status:open '(or is:open)'
|
|
|All > Merged | status:merged
|
|
|All > Abandoned | status:abandoned
|
|
|My > Drafts | owner:self is:draft
|
|
|My > Watched Changes | status:open is:watched
|
|
|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
|
|
|Approval requirement | Code-Review>=+2, Verified=1
|
|
|=============================================================
|
|
|
|
|
|
[[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'.
|
|
|
|
[[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.
|
|
|
|
[[reviewerin]]
|
|
reviewerin:'GROUP'::
|
|
+
|
|
Changes that have been, or need to be, reviewed by a user in 'GROUP'.
|
|
|
|
[[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.
|
|
|
|
[[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:open, is:pending::
|
|
+
|
|
True if the change is open.
|
|
|
|
is:draft::
|
|
+
|
|
True if the change is a draft.
|
|
|
|
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.
|
|
|
|
[[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
|
|
---------
|