From a5f62a55a17992842d13ee5bb327bf4b515c9261 Mon Sep 17 00:00:00 2001 From: Paul Date: Thu, 24 Sep 2026 09:14:20 +0100 Subject: [PATCH 1/3] Correct out-of-date passages in the task(1) man page Document the exit status of _get for invalid references and missing values, describe sow/som/soq/soy as the start of the current period, and update the 'or' example now that the command line filter is parenthesized before it is combined with the report filter. Add an example of where parentheses are still needed. Closes #4196 --- doc/man/task.1.in | 36 ++++++++++++++++-------------------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/doc/man/task.1.in b/doc/man/task.1.in index d03bb3fc7..e1a696af1 100644 --- a/doc/man/task.1.in +++ b/doc/man/task.1.in @@ -749,8 +749,9 @@ from tasks, or the system. Supported DOM references are: Note that the 'rc.' reference may need to be escaped using '--' to prevent the reference from being interpreted as an override. -Note that if the DOM reference is not valid, or the reference evaluates to a -missing value, the command exits with 1. +Note that if the DOM reference is not valid, the command exits with 2. If the +reference evaluates to a missing value, such as an unset attribute or a task +that does not exist, the output is empty and the command exits with 0. Additionally, some components of the attributes of particular types may be extracted by DOM references. @@ -1103,15 +1104,14 @@ and respectively. The negation operator is .IR ! . -Note that the parentheses are required when using a logical operator other than -the 'and' operator. The reason is that some reports contain filters that must -be combined with the command line. Consider this example: +Some reports contain filters that are combined with the command line filter. +Consider this example: .nf task project:Home or project:Garden list .fi -While this looks correct, it is not. The 'list' report contains a filter of: +The 'list' report contains a filter of: .nf task show report.list.filter @@ -1121,29 +1121,25 @@ While this looks correct, it is not. The 'list' report contains a filter of: report.list.filter status:pending .fi -Which means the example is really: +Taskwarrior puts parentheses around the command line filter before combining +it with the report filter, so the example is really: .nf - task status:pending project:Home or project:Garden list -.fi - -The implied 'and' operator makes it: - -.nf - task status:pending and project:Home or project:Garden list + task status:pending and ( project:Home or project:Garden ) list .fi -This is a precedence error - the 'and' and 'or' need to be grouped using -parentheses, like this: +No parentheses are needed here. They are still needed when you mix 'and' +and 'or' in your own filter, because 'and' binds more tightly than 'or'. +This example lists all Home tasks, but only the Garden tasks tagged 'weekend': .nf - task status:pending and ( project:Home or project:Garden ) list + task project:Home or project:Garden +weekend list .fi -The original example therefore must be entered as: +To list the 'weekend' tasks in either project, group the 'or': .nf - task '( project:Home or project:Garden )' list + task '( project:Home or project:Garden )' +weekend list .fi This includes quotes to escape the parentheses, so that the shell doesn't @@ -1201,7 +1197,7 @@ Day number with ordinal .fi .TP -Start of next (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year +Start of current (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year .nf task ... due:sow task ... due:soww From 22ac9b407a65a50766e7f82ae447236e49144e64 Mon Sep 17 00:00:00 2001 From: Paul Date: Thu, 24 Sep 2026 09:18:39 +0100 Subject: [PATCH 2/3] Remove the unsupported socw and eocw named dates They appear in the man page and the zsh and fish completions, but Taskwarrior no longer recognizes them. 'sow' and 'eow' already cover the current week, so remove them rather than add a third notion of week. Also state which day each remaining week-relative date falls on. Closes #3628 --- doc/man/task.1.in | 8 ++++---- scripts/fish/task.fish | 2 -- scripts/zsh/_task | 2 -- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/doc/man/task.1.in b/doc/man/task.1.in index e1a696af1..de6d17bb1 100644 --- a/doc/man/task.1.in +++ b/doc/man/task.1.in @@ -1197,27 +1197,27 @@ Day number with ordinal .fi .TP -Start of current (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year +Start of current week or work week (Monday), month, quarter and year .nf task ... due:sow task ... due:soww - task ... due:socw task ... due:som task ... due:soq task ... due:soy .fi .TP -End of current (work) week (Friday), calendar week (Saturday or Sunday), month, quarter and year +End of current week (Sunday), work week (Friday), month, quarter and year .nf task ... due:eow task ... due:eoww - task ... due:eocw task ... due:eom task ... due:eoq task ... due:eoy .fi +On a Sunday, soww and eoww refer to the work week that starts the next day. + .TP At some point or later .nf diff --git a/scripts/fish/task.fish b/scripts/fish/task.fish index f3cb62e1d..6b6764750 100644 --- a/scripts/fish/task.fish +++ b/scripts/fish/task.fish @@ -389,13 +389,11 @@ set __fish_task_static_dates 'today:Today' \ 'tomorrow:Tomorrow' \ 'sow:Start of week' \ 'soww:Start of work week' \ - 'socw:Start of calendar week' \ 'som:Start of month' \ 'soq:Start of quarter' \ 'soy:Start of year' \ 'eow:End of week' \ 'eoww:End of work week' \ - 'eocw:End of calendar week' \ 'eom:End of month' \ 'eoq:End of quarter' \ 'eoy:End of year' \ diff --git a/scripts/zsh/_task b/scripts/zsh/_task index 013e2065d..7d76bae95 100644 --- a/scripts/zsh/_task +++ b/scripts/zsh/_task @@ -43,13 +43,11 @@ _task_filter() { 'tom*orrow:Tomorrow' \ 'sow:Start of week' \ 'soww:Start of work week' \ - 'socw:Start of calendar week' \ 'som:Start of month' \ 'soq:Start of quarter' \ 'soy:Start of year' \ 'eow:End of week' \ 'eoww:End of work week' \ - 'eocw:End of calendar week' \ 'eom:End of month' \ 'eoq:End of quarter' \ 'eoy:End of year' \ From e3dbd2dd183e292f3a043baa3d771d7a8fb0e33b Mon Sep 17 00:00:00 2001 From: Paul Date: Thu, 24 Sep 2026 09:23:09 +0100 Subject: [PATCH 3/3] Describe what the weekstart setting affects The entry only said that it sets the day a week starts, which suggests that sow, eow and the WEEK virtual tag follow it. They don't: they always use a Monday to Sunday week. weekstart only changes the calendar layout, week numbers and the meaning of week dates. --- doc/man/taskrc.5.in | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/man/taskrc.5.in b/doc/man/taskrc.5.in index e6db3abd6..4144a86c8 100644 --- a/doc/man/taskrc.5.in +++ b/doc/man/taskrc.5.in @@ -667,7 +667,11 @@ Enables ISO-8601 date support. The default value is "1". .TP .B weekstart=Sunday Determines the day a week starts. Valid values are Sunday or Monday only. The -default value is "Sunday". +default value is "Sunday". This affects the layout of the "task calendar" +command, week numbers, and the day that a week date such as 2026-W02 refers to. +With Monday, week numbers follow ISO-8601. It does not affect named dates +such as sow and eow, or the WEEK virtual tag, which always use a week from +Monday to Sunday. .TP .B displayweeknumber=1