templates/tracker/issue-search-tips.ezt

[define category_css]css/ph_detail.css[end]
[include "../framework/header.ezt" "hidetabs"]

[# Note: No UI element permission checking needed on this page. ]

<div id="searchtips">

<h3>Basic issue search</h3>

<p>In most cases you can find the issues that you want to work with
very easily by using the issue list headers or by entering a few
simple keywords into the main search field.</p>

<p>Whenever you visit the "<a href="list">issue list</a>" in your
project, you are presented with a table of all open issues, or the default
query set up by the project owners.  If you
see too many results, you can quickly filter your results by clicking
on the table headers and choosing a specific value from the "Show
only:" submenu.</p>

[# TODO screenshot ]

<p>The main search field consists of two parts:</p>

<ul>
 <li>A drop-down selection of search scopes, e.g, "All issues" or just "Open issues".</li>
 <li>A search text field where you can enter search terms.</li>
</ul>

[# TODO screenshot ]

<p>In the text field, you may enter simple search terms, or add any of
the search operators described below.</p>

<p>You can also use the search text field to jump directly to any
issue by entering its issue number.  If you wish to search for issues
that contain a number, rather than jumping to that issue, enclose the
number in quotation marks.</p>

<p>Behind the scenes, the search scope is simply an additional set of
search terms that is automatically combined with the user's search
terms to make a complete query.  To see what search terms will be
used for each scope, hover your mouse over the scope item.</p>


<h3>Advanced issue search</h3>

<p>The <a href="advsearch">Advanced Search</a> page helps you
compose a complex query.  The advanced search form breaks the search
down into several popular criteria and allows you to specify each one
easily.  The search criteria boil down to the same thing as the search
operators described below, but you don't need to remember the operator
names.</p>



<h3>Full-text search</h3>

<p>As with Google web search, you can search for issues by simply
entering a few words.  However, you may get a few more results than
you expected.  When you need to search more precisely, you can use
search operators for more power.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="&quot;out of memory&quot;">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>Full-text search terms can include quoted phrases, and words or
phrases can be negated by using a leading minus sign.  Please note
that negated full-text terms are likely to give large result sets,
so it is best to use structured search operators when possible.</p>


<h3>Search operators</h3>

<p>Normal search terms will match words found in any field of an
issue.  You can narrow the search to a specific field by using the
name of the field.  The built-in field operators are <tt>summary</tt>,
<tt>description</tt>, <tt>comment</tt>, <tt>status</tt>, <tt>reporter</tt>,
<tt>owner</tt>, <tt>cc</tt>, <tt>component</tt>, <tt>commentby</tt>,
<tt>hotlist</tt>, <tt>ID</tt>, <tt>project</tt>,
and <tt>label</tt>.</p>

<p>Field names can be compared to a list of values using:</p>
<ul>
  <li>a colon (:) for word matching,</li>
  <li>an equals sign (=) for full string matching,</li>
  <li>a not equals sign (!=) or leading minus sign to negate, or</li>
  <li>inequality operators (&lt;, &gt;, &lt;=, &gt;=) for numeric comparison.</li>
</ul>

<p>You can limit your search to just open issues by using
is:open, or to just closed issues by using a minus sign to negate it:
<tt>-is:open</tt>.</p>
[# TODO(jrobbins): dateopened:]

<p>For example, here's how to search for issues with the word
"calculation" in the summary field.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="summary:calculation">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>When searching for issues owned by a specific user, you can use their
email address, or part of it.  When referring to yourself, you can also
 use the special term <tt>me</tt>. For example, this restricts the search to
issues that are owned by you.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="owner:user@chromium.org">
 <input type="submit" name="btn" value="Search">
</form>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="owner:me">
 <input type="submit" name="btn" [if-any logged_in_user][else]disabled=disabled[end] value="Search">
 [if-any logged_in_user][else]
   <span style="white-space:nowrap"><a href="[login_url]"
   >Sign in</a> to try this example</span>
 [end]</p>
</form>

<p>Rather than have a large number of predefined fields, our issue
tracker stores many issue details as labels.</p>

<p>For example, if you labeled security-related issues with the label
<tt>Security</tt>, here's how to search for them.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="label:security">
 <input type="submit" name="btn" value="Search"></p>
</form>


<p>In addition to simple one-word labels, you can use two part labels
that specify an attribute and a value, like <tt>Priority-High</tt>,
<tt>Priority-Medium</tt>, and <tt>Priority-Low</tt>.  You can search for
these with the <tt>label</tt> operator, or you can use the first part of the
label name like an operator.</p>

<p>For example, if you labeled high priority issues with
<tt>Priority-High</tt>, here's one way to search for them.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="label:Priority-High">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>And, here is a more compact way to do the same search.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="Priority:High">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>For the <tt>components</tt> operator, the default search will find
issues in that component and all of its subcomponents.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="component:UI">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>And of course, you can combine any of these field operators.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q"
     value="status!=New owner:me component:UI">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>You can search for issues in the current project that are also on a user's
hotlist.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q"
     value="hostlist=username@domain:hotlistname">
 <input type="submit" name="btn" value="Search"></p>
</form>


<h3>Empty (or non-empty) field search</h3>

<p>For each built-in field operator, you can use the <tt>has</tt>
operator to search for issues with empty or non-empty fields.  The
<tt>has</tt> operator can be used with status, owner, cc, component,
attachments, blocking, blockedon, mergedinto, any key-value label prefix, or
any custom field name.</p>

<p>For example, here's how to search for issues that have one or more
components.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="has:component">
 <input type="submit" name="btn" value="Search">
</form>

<p>Or, you can use the <tt>-has</tt> operator for negation, to search for
issues with empty fields.</p>

<p>For example, here's how to search for issues that are not associated with
any component.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="-has:component">
 <input type="submit" name="btn" value="Search">
</form>


<h3>Multiple values in search terms</h3>

<p>You can search for two values for one field, or two labels
with the same prefix by using.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="Priority:High,Medium">
 <input type="submit" name="btn" value="Search"></p>
</form>


<p>You can combine two separate queries into one using the <tt>OR</tt> operator.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="Priority:High OR -has:owner">
 <input type="submit" name="btn" value="Search"></p>
</form>


<p>You can create more complex <tt>OR</tt> queries using parentheses nesting to
distribute search terms across <tt>OR</tt> clauses. A search query may contain as
many sets of parentheses and levels of parentheses nesting as needed.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="Pri:0,1 (status:Untriaged OR -has:owner)">
 <input type="submit" name="btn" value="Search"></p>
</form>


<h3>Exact value search</h3>

<p>You can search for issues that exactly match the given term by using
the search operator <tt>=</tt>.</p>

<p>For example, searching for <tt>Milestone=2009</tt> only matches issues with the
label <tt>Milestone-2009</tt>, while searching for <tt>Milestone:2009</tt> matches
issues with the labels <tt>Milestone-2009</tt>, <tt>Milestone-2009-Q1</tt>, <tt>Milestone-2009-Q3</tt>,
etc.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="Milestone=2009">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>Similarly, using exact matching on components will get you only those issues
that are in that component, not including any of its descendants.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="component=UI">
 <input type="submit" name="btn" value="Search"></p>
</form>

<h3>Star search</h3>

<p>Any logged in user can mark any issue with a star.  The star
indicates interest in the issue.</p>

<p>For example, to quickly see all the issues in this project that you
have starred, you could use the following:</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="is:starred">
 <input type="submit" name="btn" [if-any logged_in_user][else]disabled="disabled"[end] value="Search">
 [if-any logged_in_user][else]
   <span style="white-space:nowrap"><a href="[login_url]"
   >Sign in</a> to try this example</span>
 [end]</p>
</form>

<p>And, to see the issues that more than ten users have starred, use the following:</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="stars>10">
 <input type="submit" name="btn" value="Search"></p>
</form>


<h3>Jump to issue and numeric search</h3>

<p>You can jump directly to a specific issue by entering its ID in the
search field.</p>

<p>For example, to jump to issue 1, just search for 1.  If there is no
existing issue with that ID, the system will search for issues that
contain that number anywhere in the issue.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="1">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>If you just want to search for issues that contain the number 1, without
jumping to issue 1, enclose the number in quotation marks.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="&quot;1&quot;">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>Searching for a list of specific issue IDs is one way to
communicate a set of issues to someone that you are working with.  Be
sure to set the search scope to "All issues" if the issues might be
closed.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="ID=1,2,3,4">
 <input type="hidden" name="can" value="1">
 <input type="submit" name="btn" value="Search"></p>
</form>


<h3>Attachment search</h3>

<p>Users can attach files to any issues, either when issues are created or as
part of issue comments.</p>

<p>To quickly see all the issues that have attachments, use the following:</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="has:attachments">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>Or, you can search for a specific filename of the attachment.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="attachment:screenshot">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>You can also search for the file extension of the attachment.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="attachment:png">
 <input type="submit" name="btn" value="Search"></p>
</form>


<p>You can also search for issues with a certain number of  attachments.</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="attachments>10">
 <input type="submit" name="btn" value="Search"></p>
</form>


<h3>Date range search</h3>

<p>You can perform searches based on date ranges.</p>

<p>This search syntax is divided into two parts, the action and the date,
[[]action]:[[]date]</p>

<p>Built-in date operators include <tt>opened</tt>,
<tt>modified</tt>, and <tt>closed</tt>. Each can be paired with an
inequality operator <tt>&lt</tt> or <tt>&gt</tt>. The date must to be
specified as YYYY-MM-DD, YYYY/MM/DD or today-N.</p>

<p>For example, if you want to search for issues opened after 2009/4/1, you
could do the following:</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="opened>2009/4/1">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>Or, if you want to search for issues modified 20 days before today's date,
you could do the following:</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="modified<today-20">
 <input type="submit" name="btn" value="Search"></p>
</form>

<p>You can search for issues that had specific fields modified
recently by using ownermodified:, statusmodified:, componentmodified:.
For example:</p>

<form action="list" method="GET">
 <p><input type="text" size="45" name="q" value="ownermodified>today-20">
 <input type="submit" name="btn" value="Search"></p>
</form>


</div>

[include "../framework/footer.ezt"]