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.
Description | Default Query |
---|---|
All > Open |
status:open (or is:open) |
All > Merged |
status:merged |
All > Abandoned |
status:abandoned |
My > Drafts |
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:
Description | Examples |
---|---|
Legacy numerical id |
15183 |
Full or abbreviated Change-Id |
Ic0ff33 |
Full or abbreviated commit SHA-1 |
d81b32ef |
Email address |
|
Approval requirement |
Code-Review>=+2, Verified=1 |
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. It will try to match a project name by substring.
E.g. Searching for just "gerrit is:starred" will try to match a project name by "gerrit" as substring.
- 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 as7 days
) -
mon, month, months (
1 month
is treated as30 days
) -
y, year, years (
1 year
is treated as365 days
)
-
- change:'ID'
-
Either a legacy numerical ID such as 15183, or a newer style Change-Id that was scraped out of the commit message.
- owner:'USER'
-
Changes originally submitted by USER. The special case of
owner:self
will find changes owned by the caller.
- ownerin:'GROUP'
-
Changes originally submitted by a user in GROUP.
- reviewer:'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.
- reviewerin:'GROUP'
-
Changes that have been, or need to be, reviewed by a user in GROUP.
- commit:'SHA1'
-
Changes where SHA1 is one of the patch sets of the change.
- project:'PROJECT'
-
Changes occurring in PROJECT. If PROJECT starts with
^
it matches project names by regular expression. The dk.brics.automaton library is used for evaluation of such patterns.
- 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 dk.brics.automaton library is used for evaluation of such patterns.
- topic:'TOPIC'
-
Changes whose designated topic at upload was TOPIC. This is often combined with branch: and project: operators to select all related changes in a series.
If TOPIC starts with
^
it matches topic names by regular expression patterns. The dk.brics.automaton library is used for evaluation of such patterns.
- 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 dk.brics.automaton library is used for evaluation of such patterns.
- tr:'ID', bug:'ID'
-
Search for changes whose commit message contains ID and matches one or more of the 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:'VALUE'
-
Matches changes where the approval score VALUE has been set during a review. See labels below for more detail on the format of the argument.
- message:'MESSAGE'
-
Changes that match MESSAGE arbitrary string in the commit message body.
- comment:'TEXT'
-
Changes that match TEXT string in any comment left by a reviewer.
- file:^REGEX
-
Matches any change where REGEX matches a file that was affected by the change. The regular expression pattern must start with
^
. For example, to match all XML files usefile:^.*\.xml$
. The 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, usefile:^.*\.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 usefile:"^name[1-3].xml"
.
- has:draft
-
True if there is a draft comment saved by the current user.
- has:star
-
Same as is:starred, true if the change has been starred by the current user.
- is:starred
-
Same as has:star, true if the change has been starred by the current user.
- 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 there is at least one non-zero score on the change, in any approval category, by any user.
- 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
-
True if the change is either open or submitted, merge pending.
- is:draft
-
True if the change is a draft.
- is:closed
-
True if the change is either merged or abandoned.
- is:submitted, is:merged, is:abandoned
-
Same as status:'STATE'.
- status:open
-
True if the change state is either review in progress or submitted, merge pending.
- status:reviewed
-
Same as is:reviewed, matches if there is at least one non-zero score on the change, in any approval category, by any user.
- status:submitted
-
Change has been submitted, but is waiting for a dependency.
- 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.
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
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 a score, or an operator and a score. The easiest way to explain this is by example.
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.
label:Code-Review=+2,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=+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
-
Matches changes that are ready to be submitted.
is:open (label:Verified-1 OR label:Code-Review-2)
-
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. 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:'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.
- resume_sortkey:'KEY'
-
Positions the low level scan routine to start from KEY and continue through changes from this point. This is most often used for paginating result sets. Including this in a web query may lead to unpredictable results.
- sortkey_after:'KEY', sortkey_before:'KEY'
-
Restart the low level scan routine from KEY. This is automatically set by the pagination system as the user navigates through results of a query. Including either value in a web query may lead to unpredictable results.
Part of Gerrit Code Review