Cleanup queries.md (#41)
Jed Fox
created 7 years ago
* Improve grammar
* Improve clock-vs-timestamp message
* Fix whitespace
* Add some explanations
* Move the clock-vs-timestamp message to the top of the sorting section
* Clarify wording more
* Fix my misconception
Change summary
doc/queries.md | 27 ++++++++++++---------------
1 file changed, 12 insertions(+), 15 deletions(-)
Detailed changes
@@ -1,6 +1,6 @@
# Searching bugs
-You can search bugs using a micro query language for both filtering and sorting. A query could looks like this:
+You can search bugs using a micro query language for both filtering and sorting. A query could look like this:
```
status:open sort:edit
@@ -8,9 +8,9 @@ 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.
+- queries are case insensitive.
+- you can combine as many qualifiers as you want.
+- you can use double quotes for multi-word search terms. For example, `author:"René Descartes"` searches for bugs opened by René Descartes, whereas `author:René Descartes` will throw an error since full-text search is not yet supported.
## Filtering
@@ -35,7 +35,7 @@ You can filter based on the person who opened the bug.
### Filtering by label
-You can filter based on bug's label.
+You can filter based on the bug's label.
| Qualifier | Example |
| --- | --- |
@@ -46,16 +46,17 @@ You can filter based on bug's label.
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.
+You can sort results by adding a `sort:` qualifier to your query. “Descending” means most recent time or largest ID first, whereas “Ascending” means oldest time or smallest ID first.
+
+Note: to deal with differently-set clocks on distributed computers, `git-bug` uses a logical clock internally rather than timestamps to order bug changes 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)
-### Sort by Id
+### Sort by Id
| Qualifier | Example |
| --- | --- |
@@ -66,20 +67,16 @@ You can sort result by adding a `sort:` qualifier to your query.
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.
+### Sort by Edit 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)
+You can sort bugs by their edit time.
| 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 |
+| `sort:edit-asc` | `sor:edit-asc` will sort bugs by their ascending last edition time |