Merge pull request #3340 from obsidian-tasks-group/task.lineNumber

claremacrae · web-flow · commit 3f05bc43101b · 2025-02-18T16:58:19.000Z
docs: Document `task.lineNumber` for sorting by line number
diff --git a/docs/Queries/Filters.md b/docs/Queries/Filters.md
@@ -1279,6 +1279,19 @@ For example, this could be used to extract information from `task.originalMarkdo
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
+### Line Number
+
+There is no built-in instruction to filter by the task's line number.
+
+Since Tasks X.Y.Z, **[[Custom Filters|custom filtering]] by the task's line number** is now possible, using `task.lineNumber`.
+
+> [!tip]
+> With `task.lineNumber`, the first line in the file is on line number `0` (zero), not `1` (one).
+
+<!-- placeholder to force blank line before included text --><!-- include: CustomFilteringExamples.test.other_properties_task.lineNumber_docs.approved.md -->
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
 ## Filters for File Properties
 
 These filters allow searching for tasks in particular files and sections of files.
diff --git a/docs/Queries/Grouping.md b/docs/Queries/Grouping.md
@@ -828,6 +828,19 @@ group by function task.originalMarkdown.replace(/^[^\[\]]+\[.\] */, '')
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
+### Line Number
+
+There is no built-in instruction to group by the task's line number.
+
+Since Tasks X.Y.Z, **[[Custom Grouping|custom grouping]] by the task's line number** is now possible, using `task.lineNumber`.
+
+> [!tip]
+> With `task.lineNumber`, the first line in the file is on line number `0` (zero), not `1` (one).
+
+<!-- placeholder to force blank line before included text --><!-- include: CustomGroupingExamples.test.other_properties_task.lineNumber_docs.approved.md -->
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
 ## Group by File Properties
 
 ### File Path
diff --git a/docs/Queries/Sorting.md b/docs/Queries/Sorting.md
@@ -50,6 +50,8 @@ However, any `sort by` instructions in queries take precedence over these defaul
 > To sort the results of a query differently from the default, you must add at least one `sort by` line to the query. The sort instructions you supply will take priority over the appended defaults.
 >
 > Adding `sort by` lines to the [[Global Query]] provides a way override to the default sort order for **all** searches (except those that [[Global Query#Ignoring the global query|ignore the global query]]).
+>
+> You may also find `sort by function task.lineNumber` to be useful to override the default sort order. See [[#Override the Tasks plugin's default sort order]] below.
 
 ## Custom Sorting
 
@@ -504,6 +506,26 @@ sort by function task.originalMarkdown
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
+### Line Number
+
+There is no built-in instruction to sort by the task's line number.
+
+Since Tasks X.Y.Z, **[[Custom Sorting|custom sorting]] by the task's line number** is now possible, using `task.lineNumber`.
+
+> [!tip]
+> With `task.lineNumber`, the first line in the file is on line number `0` (zero), not `1` (one).
+
+<!-- placeholder to force blank line before included text --><!-- include: CustomSortingExamples.test.other_properties_task.lineNumber_docs.approved.md -->
+
+```javascript
+sort by function task.lineNumber
+```
+
+- Sort by the line number of the task's original line in the MarkDown file.
+- This is useful if you are unhappy with the [[Sorting#default sort order]].
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
 ### Random sorting
 
 > [!released]
@@ -677,21 +699,46 @@ For example, when you `sort by done reverse` and your query results contain task
 
 ## Examples
 
+### Sort tasks by due date, from oldest to newest
+
     ```tasks
     not done
     due today
     sort by due
     ```
 
+### Sort tasks by due date, from newest to oldest
+
     ```tasks
     done
     sort by done reverse
     ```
 
+### Override the Tasks plugin's default sort order
+
+If you are unhappy with the [[#default sort order]], this is one way to override it:
+
+1. sort by the Markdown file's full path,
+2. then sort by the task's line number in that file.
+
+    ```tasks
+    not done
+    sort by path
+    sort by function task.lineNumber
+    ```
+
+Any other sort instructions can be added before these two, such as `sort by priority` or `sort by happens`
+
+### Sort by multiple properties
+
+1. task's status type (Sorted in the order `IN_PROGRESS`, `TODO`, `DONE`, `CANCELLED` then `NON_TASK`),
+2. then the task's description, in reverse alphabetical order
+3. then by the Markdown file's path.
+
     ```tasks
     not done
     due before next monday
-    sort by status
+    sort by status.type
     sort by description reverse
     sort by path
     ```
diff --git a/docs/Quick Reference.md b/docs/Quick Reference.md
@@ -51,7 +51,7 @@ This table summarizes the filters and other options available inside a `tasks` b
 | `description (includes, does not include) <string>`<br>`description (regex matches, regex does not match) /regex/i`                                                                                                                                                                                                                                  | `sort by description`                       |                        |                        | `task.description`<br>`task.descriptionWithoutTags`                                                                                                                      |
 | `has tags`<br>`no tags`<br>`tag (includes, does not include) <tag>`<br>`tags (include, do not include) <tag>`<br>`tag (regex matches, regex does not match) /regex/i`<br>`tags (regex matches, regex does not match) /regex/i`                                                                                                                       | `sort by tag`<br>`sort by tag <tag_number>` | `group by tags`        | `hide tags`            | `task.tags`                                                                                                                                                              |
 |                                                                                                                                                                                                                                                                                                                                                      |                                             |                        | `show tree`            |                                                                                                                                                                          |
-|                                                                                                                                                                                                                                                                                                                                                      |                                             |                        |                        | `task.originalMarkdown`                                                                                                                                                  |
+|                                                                                                                                                                                                                                                                                                                                                      |                                             |                        |                        | `task.originalMarkdown`<br>`task.lineNumber`                                                                                                                             |
 |                                                                                                                                                                                                                                                                                                                                                      | `sort by random`                            |                        |                        |                                                                                                                                                                          |
 | **[[About Scripting\|Scripting]]**                                                                                                                                                                                                                                                                                                                   |                                             |                        |                        |                                                                                                                                                                          |
 | `filter by function`                                                                                                                                                                                                                                                                                                                                 | `sort by function`                          | `group by function`    |                        |                                                                                                                                                                          |
diff --git a/docs/Scripting/Task Properties.md b/docs/Scripting/Task Properties.md
@@ -148,6 +148,7 @@ For more information, including adding your own customised statuses, see [[Statu
 | `task.onCompletion` | `string` | `'delete'` | `string` | `''` |
 | `task.tags` | `string[]` | `['#todo', '#health']` | `any[]` | `[]` |
 | `task.originalMarkdown` | `string` | `'  - [ ] Do exercises #todo #health 🆔 abcdef ⛔ 123456,abc123 🔼 🔁 every day when done 🏁 delete ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ^dcf64c'` | `string` | `'- [/] minimal task'` |
+| `task.lineNumber` | `number` | `17` | `number` | `0` |
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 
diff --git a/docs/What is New/Changelog.md b/docs/What is New/Changelog.md
@@ -12,6 +12,10 @@ _In recent [Tasks releases](https://github.com/obsidian-tasks-group/obsidian-tas
 
 ## 7.x releases
 
+- X.Y.Z:
+  - Add `task.lineNumber`.
+    - This enables `sort by function task.lineNumber` to override the [[Sorting#Default sort order|default sort order]].
+    - See [[Filters#Line Number|filters]], [[Sorting#Line Number|sorting]] and [[Grouping#Line Number|grouping]].
 - 7.15.0:
   - Tasks now requires [Obsidian 1.4.0](https://obsidian.md/changelog/2023-08-31-desktop-v1.4.5/) or newer.
   - **Translations**:
diff --git a/resources/sample_vaults/Tasks-Demo/Manual Testing/Smoke Testing the Tasks Plugin.md b/resources/sample_vaults/Tasks-Demo/Manual Testing/Smoke Testing the Tasks Plugin.md
@@ -50,6 +50,7 @@ Work through all the tasks below, until zero tasks remain in this query:
 > not done
 > path includes Smoke Testing the Tasks Plugin
 > description includes **check**:
+> sort by function task.lineNumber
 >
 > short display
 > ```
@@ -191,14 +192,15 @@ hide postpone button
 
 - Non-task checkbox are tasks without the global filter, treated as `ListItems` by the obsidian-tasks plugin
 - [ ] #task Check or uncheck non-task list items with checkbox in the query below this task
-  - [ ] I will have an `x` status  
-  - [x]  I will have a `space` status  
+  - [ ] I will have an `x` status
+  - [x] I will have a `space` status
   - [/] Me too with a `space` status
 
-```tasks  
+```tasks
 filename includes {{query.file.filename}}
 heading includes Toggling non-task checkboxes
-show tree  
+description does not include **check**:
+show tree
 ```
 
 - [ ] #task **check**: Checked all above steps for **toggling non-task list items with checkbox in a query** worked
diff --git a/tests/Scripting/ScriptingReference/CustomFiltering/CustomFilteringExamples.test.other_properties_task.lineNumber_docs.approved.md b/tests/Scripting/ScriptingReference/CustomFiltering/CustomFilteringExamples.test.other_properties_task.lineNumber_docs.approved.md
@@ -0,0 +1,5 @@
+<!-- placeholder to force blank line before included text -->
+
+
+
+<!-- placeholder to force blank line after included text -->
diff --git a/tests/Scripting/ScriptingReference/CustomFiltering/CustomFilteringExamples.test.ts b/tests/Scripting/ScriptingReference/CustomFiltering/CustomFilteringExamples.test.ts
@@ -674,6 +674,14 @@ describe('other properties', () => {
             [],
             SampleTasks.withRepresentativeTags(),
         ],
+
+        [
+            'task.lineNumber',
+            // comment to force line break
+            [],
+            SampleTasks.withRepresentativeLineNumbers(),
+        ],
+
         [
             'task.urgency',
             [
diff --git a/tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.lineNumber_docs.approved.md b/tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.lineNumber_docs.approved.md
@@ -0,0 +1,5 @@
+<!-- placeholder to force blank line before included text -->
+
+
+
+<!-- placeholder to force blank line after included text -->
diff --git a/tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.lineNumber_results.approved.txt b/tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.other_properties_task.lineNumber_results.approved.txt
@@ -0,0 +1,3 @@
+Results of custom groupers
+
+
diff --git a/tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.ts b/tests/Scripting/ScriptingReference/CustomGrouping/CustomGroupingExamples.test.ts
@@ -690,6 +690,13 @@ describe('other properties', () => {
             SampleTasks.withRepresentativeTags(),
         ],
 
+        [
+            'task.lineNumber',
+            // comment to force line break
+            [],
+            SampleTasks.withRepresentativeLineNumbers(),
+        ],
+
         [
             'task.urgency',
             [
diff --git a/tests/Scripting/ScriptingReference/CustomSorting/CustomSortingExamples.test.other_properties_task.lineNumber_docs.approved.md b/tests/Scripting/ScriptingReference/CustomSorting/CustomSortingExamples.test.other_properties_task.lineNumber_docs.approved.md
@@ -0,0 +1,12 @@
+<!-- placeholder to force blank line before included text -->
+
+
+```javascript
+sort by function task.lineNumber
+```
+
+- Sort by the line number of the task's original line in the MarkDown file.
+- This is useful if you are unhappy with the [[Sorting#default sort order]].
+
+
+<!-- placeholder to force blank line after included text -->
diff --git a/tests/Scripting/ScriptingReference/CustomSorting/CustomSortingExamples.test.other_properties_task.lineNumber_results.approved.txt b/tests/Scripting/ScriptingReference/CustomSorting/CustomSortingExamples.test.other_properties_task.lineNumber_results.approved.txt
@@ -0,0 +1,12 @@
+Results of custom sorters
+
+
+
+sort by function task.lineNumber
+Sort by the line number of the task's original line in the MarkDown file.
+This is useful if you are unhappy with the [[Sorting#default sort order]].
+=>
+- [ ] line 0
+- [ ] line 42
+====================================================================================
+
diff --git a/tests/Scripting/ScriptingReference/CustomSorting/CustomSortingExamples.test.ts b/tests/Scripting/ScriptingReference/CustomSorting/CustomSortingExamples.test.ts
@@ -380,6 +380,18 @@ describe('other properties', () => {
             SampleTasks.withRepresentativeTags(),
         ],
 
+        [
+            'task.lineNumber',
+            [
+                [
+                    'sort by function task.lineNumber',
+                    "Sort by the line number of the task's original line in the MarkDown file.",
+                    'This is useful if you are unhappy with the [[Sorting#default sort order]].',
+                ],
+            ],
+            SampleTasks.withRepresentativeLineNumbers(),
+        ],
+
         [
             'task.urgency',
             [
diff --git a/tests/Scripting/TaskProperties.test.task_other_fields.approved.md b/tests/Scripting/TaskProperties.test.task_other_fields.approved.md
@@ -13,6 +13,7 @@
 | `task.onCompletion` | `string` | `'delete'` | `string` | `''` |
 | `task.tags` | `string[]` | `['#todo', '#health']` | `any[]` | `[]` |
 | `task.originalMarkdown` | `string` | `'  - [ ] Do exercises #todo #health 🆔 abcdef ⛔ 123456,abc123 🔼 🔁 every day when done 🏁 delete ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ^dcf64c'` | `string` | `'- [/] minimal task'` |
+| `task.lineNumber` | `number` | `17` | `number` | `0` |
 
 
 <!-- placeholder to force blank line after included text -->
diff --git a/tests/Scripting/TaskProperties.test.ts b/tests/Scripting/TaskProperties.test.ts
@@ -130,6 +130,7 @@ describe('task', () => {
             // 'task.listMarker', // Not a priority to release
             // 'task.blockLink', // Release support for grouping by task.blockLink, after removing the leading space and maybe the carat
             'task.originalMarkdown',
+            'task.lineNumber',
         ]);
     });
 
diff --git a/tests/TestingTools/SampleTasks.ts b/tests/TestingTools/SampleTasks.ts
@@ -103,6 +103,14 @@ export class SampleTasks {
         });
     }
 
+    public static withRepresentativeLineNumbers(): Task[] {
+        const taskBuilders = [
+            new TaskBuilder().lineNumber(42).description('line 42'),
+            new TaskBuilder().lineNumber(0).description('line 0'),
+        ];
+        return taskBuilders.map((builder) => builder.build());
+    }
+
     public static withAllRepresentativeCreatedDates(): Task[] {
         return representativeDates.map((date) => {
             return new TaskBuilder().createdDate(date).build();

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +<!-- placeholder to force blank line before included text -->
++
++
++
 +<!-- placeholder to force blank line after included text -->