aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMichael Muré <batolettre@gmail.com>2018-09-09 22:16:00 +0200
committerMichael Muré <batolettre@gmail.com>2018-09-09 22:16:00 +0200
commit28ee08af0d649a32b0e0bd4b06aee11ef8a8c2f9 (patch)
treef7c258ba1c837f0e7b4fdc7ece4a00147c2cb753 /doc
parentdd0823dd2ba68a9c778e81b26e53600b159b5a7d (diff)
downloadgit-bug-28ee08af0d649a32b0e0bd4b06aee11ef8a8c2f9.tar.gz
doc: document the query DSL
Diffstat (limited to 'doc')
-rw-r--r--doc/queries.md85
1 files changed, 85 insertions, 0 deletions
diff --git a/doc/queries.md b/doc/queries.md
new file mode 100644
index 00000000..27cfda21
--- /dev/null
+++ b/doc/queries.md
@@ -0,0 +1,85 @@
+# Searching bugs
+
+You can search bugs using a micro query language for both filtering and sorting. A query could looks like this:
+
+```
+status:open sort:edit
+```
+
+A few tips:
+
+- query are case insensitive.
+- you can combine as much qualifier as you want.
+- you can use quotation for multi-word search term. For example, use `author:"René Descartes"` to search with a complete name.
+
+
+## Filtering
+
+### Filtering by status
+
+You can filter bugs based on their status.
+
+| Qualifier | Example |
+| --- | --- |
+| `status:open` | `status:open` matches open bugs |
+| `status:closed` | `status:closed` matches closed bugs |
+
+### Filtering by author
+
+You can filter based on the person who opened the bug.
+
+| Qualifier | Example |
+| --- | --- |
+| `author:QUERY` | `author:descartes` matches bugs opened by `René Descartes` or `Robert Descartes` |
+| | `author:"rené descartes"` matches bugs opened by `René Descartes` |
+
+### Filtering by label
+
+You can filter based on bug's label.
+
+| Qualifier | Example |
+| --- | --- |
+| `label:LABEL` | `label:prod` matches bugs with the label `prod` |
+| | `label:"Good first issue"` matches bugs with the label `Good first issue` |
+
+### Filtering by missing feature
+
+You can filter bugs based on the absence of something.
+
+
+| Qualifier | Example |
+| --- | --- |
+| `no:label` | `no:label` matches bugs with no labels |
+
+## Sorting
+
+You can sort result by adding a `sort:` qualifier to your query.
+
+### Sort by Id
+
+| Qualifier | Example |
+| --- | --- |
+| `sort:id-desc` | `sor:id-desc` will sort bugs by their descending Ids |
+| `sort:id` or `sort:id-asc` | `sor:id` will sort bugs by their ascending Ids |
+
+### Sort by Creation time
+
+You can sort bugs by their creation time.
+
+Note: to deal with badly set clocks in a distributed system, `git-bug` use a logical clock internally rather than timestamp to order bugs edition over time. That means that the timestamps recorded might not match the returned ordering. More on that in [the documentation](model.md#you-cant-rely-on-the-time-provided-by-other-people-their-clock-might-by-off-for-anything-other-than-just-display)
+
+| Qualifier | Example |
+| --- | --- |
+| `sort:creation` or `sort:creation-desc` | `sor:creation` will sort bugs by their descending creation time |
+| `sort:creation-asc` | `sor:creation-asc` will sort bugs by their ascending creation time |
+
+### Sort by Edition time
+
+You can sort bugs by their edition time.
+
+Note: to deal with badly set clocks in a distributed system, `git-bug` use a logical clock internally rather than timestamp to order bugs edition over time. That means that the timestamps recorded might not match the returned ordering. More on that in [the documentation](model.md#you-cant-rely-on-the-time-provided-by-other-people-their-clock-might-by-off-for-anything-other-than-just-display)
+
+| Qualifier | Example |
+| --- | --- |
+| `sort:edit` or `sort:edit-desc` | `sor:edit` will sort bugs by their descending last edition time |
+| `sort:edit-asc` | `sor:edit-asc` will sort bugs by their ascending last edition time | \ No newline at end of file