From fd21de5632fda2bbc030d34c28e9dfc1403d2497 Mon Sep 17 00:00:00 2001 From: Jed Fox Date: Mon, 10 Sep 2018 06:49:31 -0400 Subject: Cleanup queries.md (#41) * 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 --- doc/queries.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) (limited to 'doc/queries.md') diff --git a/doc/queries.md b/doc/queries.md index 27cfda21..93135070 100644 --- a/doc/queries.md +++ b/doc/queries.md @@ -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 | \ No newline at end of file +| `sort:edit-asc` | `sor:edit-asc` will sort bugs by their ascending last edition time | -- cgit