opendev/gerrit
Code Issues Proposed changes
b8fbb8ac61
gerrit/Documentation/user-search.txt
Edwin Kempin 9e972ccb44 Support star labels 
At the moment Gerrit supports only one kind of star on changes, either
a change is starred by a user or it is not. For some use cases users
want to put different stars on changes. E.g. issue 1144 requests
colored stars (yellow, red, blue) and issue 2576 requests an ignore
star.

Star labels behave like private hashtags. A user can apply any label
to a change, but these labels are only visible to that user.

Having support for stars allows us to implement a first working
version of the ReviewIt Gerrit Android application.

To support star labels the API of StarredChangesUtil is extended so
that it can read/store star labels.

Star labels are stored in the change index. This is needed to be able
to return the star labels as part of ChangeInfo without needing to
scan for them. Including the star labels into ChangeInfo is done in a
follow-up change so that a online migration is possible, where search
results don't need to read from git:
1. The star labels are stored in the index, changes retured as query
results do not contain star labels (this change).
2. Run online schema migration, when finished the index contains the
new STAR field for all changes.
3. Include the star labels into ChangeInfo, access to git is not
needed since the star labels are read from the index (next change).

Also the STAR field in the index enables a new search operator for
star labels ("star:<label>") that finds changes that have been starred
by the current user with the given label

The STARREDBY field and the IsStarredByPredicate will be no longer
needed since the 'is:starred' query that they serve can be implemented
by using the new STAR field and the new StarPredicate. This is why the
STARREDBY field is and the IsStarredByPredicate predicate are
deprecated.

In addition a STARBY field is added to the index that tracks all users
that have starred the change with any label. This field is needed to
be able to list all starred changes (changes that have at least one
star by the user). Without this field we would need to scan the full
refs/starred-changes/ namespace for this. The STARBY field also backs
a new 'has:stars' query operator which finds all changes that have at
least one star by the current user.

The REST API is extended so that users can get/add/remove star labels.

New REST endpoints have been added to
- get star labels from a change
  GET /accounts/<account-id>/stars.changes/<change-id>
- update star labels on a change
  POST /accounts/<account-id>/stars.changes/<change-id>
- list changes that are starred by any label
  GET /accounts/<account-id>/stars.changes/

The REST endpoints that deal with the default stars are left
unmodified for backwards compatibility. They are exposed under
'/accounts/<id>/starred.changes/'.

Star labels are private to a user, hence a user can access only the
own star labels.

New methods have been added to the AccountApi to support get and
update of star labels, and listing of changes that have been starred
with any label.

Star labels also affect the ETag of a change. Instead of including the
actual labels into the ETag computation we simply use the ID of the
object in which the labels are stored in git. This way we don't need
to read the blob for the ETag computation.

The old method to retrieve starred changes from an IdentifiedUser and
the way to load the starred changes asynchroniously is deprecated now.
The asynchronous loading was needed when the starred changes were
(slowly) loaded from the database, but the new lookup is faster so
that we no longer need this asynchronous loading. The code for this is
still kept so that we can still support IsStarredByLegacyPredicate
which is needed to find starred changes when the change index doesn't
contain the new star fields yet.

Change-Id: I25d8af5a2a26930320c074225e26ff032889c891
Signed-off-by: Edwin Kempin <ekempin@google.com>
2016-05-06 17:04:47 +02:00

561 lines
16 KiB
Plaintext
Raw Blame History

= 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`)
[[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.
[[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.
[[is]]
[[is-starred]]
is:starred::
+
Same as 'has:star', true if the change has been starred by the
current user with the default label.
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'>>.
[[mergeable]]
is:mergeable::
+
True if the change has no merge conflicts and could be merged into its
destination branch.
[[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.
== 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 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' 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
---------
View Git Blame Copy Permalink