include::include/header.adoc[]

== Name

bite-redmine-search - search issues

== Synopsis

*bite redmine <search|s>* [<options>] [<terms>]::
    Query and output issues.

*bite redmine <search|s>* [-h|--help]::
    Output help information.

== Description

Search issues.

include::include/global-options.adoc[]

== Search options

*-b, --browser*::
    Open in a browser.
+
This uses `$BROWSER` to open URLs, falling back to `xdg-open` if undefined.
+
.Open search for all issues updated in the last week in a browser:
 bite redmine search -s @any --updated 1w -b

*--json*::
    Output in JSON format.
+
.Return all open issues created in the past day rendered in JSON:
 bite redmine search --created 1d --json

include::include/template-options.adoc[]

== Query options

*-f, --fields <field[,...]>*::
    Restrict the data fields returned by the query.
+
By default, only the id and subject fields are returned. This can be altered by
specifying a custom list of comma-separated values that changes the output format to
a space-separated list of the field values.
+
.Output the ID and author for open issues created in the last week:
 bite redmine search -c 1w --fields id,author
+
.Possible values:
- *assignee*: user the issue is assigned to
- *author*: user who created the issue
- *closed*: time when the issue was closed
- *created*: time when the issue was created
- *id*: issue ID
- *priority*: issue priority
- *status*: issue status
- *subject*: issue subject
- *tracker*: issue type
- *updated*: time when the issue was last updated

*-l, --limit <value>*::
    Limit the number of results.
+
If the value is higher than the maximum limit that value is used instead and if
the limit is set to zero, the default limit is used. Note that the maximum and
default limits are generally not equal, with most instances using 100 and 25,
respectively.
+
Note that setting an explicit limit will disable result paging unless `--paged`
is used.

*-O, --offset <value>*::
    Set the starting position for results.
+
Used in conjunction with the `-l/--limit`, offset defines the starting position
for the search. For example, given a search that would return 100 results, setting
limit to 10 and offset to 10 would return results 11 through 20 from the set
of 100.

*-o, --order <field[,...]>*::
    Order the query results.
+
Fields can be prefixed with `-` or `+` to sort in descending or ascending
order, respectively. Unprefixed fields use ascending order.
+
Multiple fields can be specifying in a comma-separated list which sort the
results by each field in order.
+
If an invalid sorting request is made, the default ordering will be used.
+
.Issues closed in the last day ordered by modification time:
 bite redmine search -s @closed -u 1d -o updated
+
.Highest priority issues:
 bite redmine search -l 10 --order=-priority
+
.Possible values:
- *assignee*: user the issue is assigned to
- *author*: user who created the issue
- *closed*: time when the issue was closed
- *created*: time when the issue was created
- *id*: issue ID
- *priority*: issue priority
- *status*: issue status
- *subject*: issue subject
- *tracker*: issue type
- *updated*: time when the issue was last updated

*--paged [<bool>]*::
    Enable result paging support.
+
Forcibly enable paging with `-l/--limit` using the given limit value as the
number of results per page.
+
This allows setting a smaller page size to get quicker, initial results for
large queries.
+
.All closed issues using 25 items per page:
 bite redmine search -s @closed -l 25 --paged

== Attribute options

*-a, --assignee [<bool>]*::
    Restrict by assignee status.
+
With no argument, all matches with assignees are returned. If the value is
`true` or `false`, all matches with or without assignees are returned,
respectively.
+
.Assigned issues:
 bite redmine search --assignee
+
.Unassigned issues:
 bite redmine search --assignee false

*-@, --attachments [<value>[,...]]*::
    Restrict by attachments.
+
With no argument, all matches with attachments are returned. If the
value is `true` or `false`, all matches with or without attachments
are returned, respectively.
+
Regular string values search for matching substrings in an
attachment's file name.
+
Multiple values can be specified in a comma-separated list and will
match if all of the specified values match.
+
.With attachments:
 bite redmine search -@
+
.Without attachments:
 bite redmine search --attachments false
+
.With file names containing `test`:
 bite redmine search --attachments test
+
.With file names containing `test` and `log`:
 bite redmine search --attachments test,log

*-B, --blocks [<ID>[,...]]*::
    Restrict by blockers.
+
With no argument, all blocking matches are returned. If the value is `true` or
`false`, all blocking and non-blocking matches are returned, respectively.
+
.With blockers:
 bite redmine search --blocks
+
.Without blockers:
 bite redmine search --blocks false
+
Regular values search for matching blockers and multiple values can be
specified in a comma-separated list, matching if any of the specified blockers
match.
+
.Blocking issue #10:
 bite redmine search --blocks 10
+
.Blocking issues #10 or #11:
 bite redmine search --blocks 10,11
+
Values are taken from standard input when `-`.

*-D, --blocked [<ID>[,...]]*::
    Restrict by dependencies.
+
With no argument, all matches with dependencies are returned. If the value is
`true` or `false`, all matches with or without dependencies are returned,
respectively.
+
.With dependencies:
 bite redmine search --blocked
+
.Without dependencies:
 bite redmine search --blocked false
+
Regular values search for matching dependencies and multiple values can be
specified in a comma-separated list, matching if any of the specified
dependencies match.
+
.Blocked on issue #10:
 bite redmine search --blocked 10
+
.Blocked on issues #10 or #11:
 bite redmine search --blocked 10,11
+
Values are taken from standard input when `-`.

*-R, --relates [<ID>[,...]]*::
    Restrict by relations.
+
With no argument, all matches with relations are returned. If the value is
`true` or `false`, all matches with or without relations are returned,
respectively.
+
.With relations:
 bite redmine search --relates
+
.Without relations:
 bite redmine search --relates false
+
Regular values search for matching relations and multiple values can be
specified in a comma-separated list, matching if any of the specified
relations match.
+
.Related to issue #10:
 bite redmine search --relates 10
+
.Related to issues #10 or #11:
 bite redmine search --relates 10,11
+
Values are taken from standard input when `-`.

*--id*::
    Restrict by ID.
+
Values search for matching issue IDs and multiple values can be
specified in a comma-separated list, matching if any of the specified
IDs match.
+
Values are taken from standard input when `-`.

*-s, --status*::
    Restrict by status.
+
Query issue status from the following options: @open, @closed, and @any.

== Time options

// TODO: include external doc describing time value format

*-c, --created*::
    Restrict by creation time.

*-u, --updated*::
    Restrict by update time.

*-c, --closed*::
    Restrict by closed time.

== Arguments

*[<terms>]*::
    Restrict by subject content.
+
Taken from standard input when `-`.
+
.With `test` in the subject:
 bite redmine search test

== See Also

linkcmd:bite-redmine[1]
