I use a lot of tasks that recur once a month, once every three months, once a year, etc. The underlying date implementations support syntax for other time periods, like months and years.

GNU implementation
$ date -d "2015-08-29 3 months" +%Y-%m-%d
2015-11-29

BSD implementation
$ date -j -v3m -f %Y-%m-%d 2015-08-29 +%Y-%m-%d
2015-11-29 (untested; according to documentation)

I think it would make sense to add support for this to again.

Why not use just use the number of days in a month/year?
Some recurring tasks, like "pay rent," are always due on the same day of the month. Since months have different numbers of days, I'd have to think too hard each month about whether to add 28 (February), 29 (leap year February), 30 (some months), or 31 (most months). I'd rather just type "todo.sh again N 1m" to increment the month but leave the day alone.

Problem with late dates
What should be the result of (2015-08-31 + 1 month)? 2015-09-31 is not a valid date. BSD will decrement the day number and return 2015-09-30. Over time, this will result in later days (29, 30, 31) drifting to 30 (short months) and eventually to 28 (February). GNU will always increment by 31 days if the day number would not be valid in the next month, which in this case returns 2015-10-01.

I personally like the BSD behavior better; I don't mind as much if my dates are early by a couple of days, but missing a task deadline is bad. So, again might have to build in some extra smarts to provide the BSD behavior (using awk/sed?) even when the GNU implementation is present.

When completing a recurring task with again, the new instance of the task gets the two dates from the originating task prepended to it:

~$ t again 17 
17 x 2018-03-14 2018-02-14 pay cable @laptop +bills t:2018-03-14 rec:+1m due:2018-03-14                                                                               
TODO: 17 marked as done.
x 2018-03-14 2018-02-14 pay cable @laptop +bills t:2018-03-14 rec:+1m due:2018-03-14                                                                                  
TODO: /home/rav/Nextcloud/Todo/todo.txt archived.
48 (B) 2018-03-14 2018-02-14 pay cable @laptop +bills t:2018-04-14 rec:+1m due:2018-04-14
TODO: 48 added.

Hi,
I often find myself using 'do' instead of 'again' for tasks that have an again attribute in them, therefore not creating the next instance of the task.

Is there a way to have 'again' ignore tasks that don't have an again tag and just mark them done, so 'again' can be a drop in replacement for 'do'?

The Usage section of README.md is good, but I think an Examples section would also be helpful. I didn't immediately grasp the difference between the DAYS and the +DAYS syntax.

I'm imagining something that starts with an example recurring task, then runs 'todo.sh again' a few times with different arguments, showing the output from todo.sh after each step.

I intend to work on this, but just wanted to open an issue to encourage feedback before I get too far.

The suggestion

I would like to suggest a change in behavior when the again action adds a new task. The new task's due: date should be calculated based on the offset between the t: deferral date and due: date of the original task. With the current behavior, a new task is sometimes created with identical deferral and due dates (even when the original task's deferral and due dates were not identical).

Example 1: current behavior, works

This scenario works well with the current behavior. I want to pay the bills on the 14th of each month and complete the task within one week. Because this task is tied to the calendar, the deferral and due dates are both incremented from the original values with again:+1m.

$ todo add "(A) Pay bills t:2021-09-14 due:2021-09-21 again:+1m"
TODO: 1 added.
$ todo again 1
1 (A) Pay bills t:2021-10-14 due:2021-10-21 again:+1m

Both dates are incremented and the offset between the dates is retained in the new task.

Example 2: current behavior, does not work

This scenario does not work with the current behavior. I want to service the car every six months and complete it within one month. This time the new task dates should be based on the completion date instead.

$ todo add "(A) Service car t:2021-09-10 due:2021-10-10 again:6m"
TODO: 1 added
$ date -I
2021-09-13
$ todo again 1
1 (A) Service car t:2022-03-13 due:2022-03-13 again:6m

In this case, the dates are incremented, but the offset between the deferral date and the due date is lost. The due: value is garbage now.

Example 3: suggested behavior

This is the same as example 2 but shows the suggested behavior instead.

$ todo add "(A) Service car t:2021-09-10 due:2021-10-10 again:6m"
TODO: 1 added
$ date -I
2021-09-13
$ todo again 1
1 (A) Service car t:2022-03-13 due:2022-04-13 again:6m

Here, the due date is 1 month after the deferral date just like in the original task.

More discussion

This change is relevant in the following scenario only:

1. the again: adjustment has no + and thus is computed from today,
2. a deferral date has been specified, and
3. a due date has been specified.

Further reasoning for the above:

1. If a + is used, the user has specified an explicit offset to use for new deferral and due dates. The current behavior, shown in example 1 above, is what the user expects.
2. If no deferral date is specified, then the user intends for the again: adjustment to apply to the due date directly. The current behavior is what the user expects.
3. This suggestion is not relevant to a case where no due date is specified.

Thanks for reading this far. Any thoughts?

OS X ships with the BSD variant of the date command which has different options than the GNU version. Currently running again with a second parameter to adjust the due date causes it to fail with an error displaying the usage info for the date command (it doesn't like the days parameter). There needs to be some OS detection to determine if it should use the GNU or BSD configuration options. It looks like instead of using days the value needs to be passed using the -v flag and appending d to the value.

Issue reported by Dylan Lee.

Hi, I use again as my do, with the TODO_NO_AGAIN_IF_NOT_TAGGED option on. When you have a task with text that includes the AGAIN_TAG as part of a word, again detects it, triggering itself even though the pattern appears not as a key/value pair.

Example:
if I have my AGAIN_TAG set to "rec", when I have a task that includes the word "reconcile", it gets re-added automatically, which it shouldn't since I have the TODO_NO_AGAIN_IF_NOT_TAGGED option on.

Since I use SimpleTask on my Android phone, I set the rec tag for recurring tasks; again should be updated to be able to recognize these tags as well (perhaps controllable with an environment variable).

Also, if again supports this feature, then it needs to support the extensions as well. More specifically, the SimpleTask specific b recurrence modifier (business day) needs to be supported. Also, investigate if there are any more secret-sauce modifiers that should be supported. Also make sure that any introduced features are backwards compatible as to not introduce any regression.

Many of my tasks always recur with the same interval. To save me extra manual work each time a task recurs, I'd rather annotate the task with an interval, then call again with no extra arguments. again would scan the line, notice the interval, and use that as the DAYS argument.

Something like this:
$ todo.sh list
5 a weekly task t:2015-08-10 due:2015-08-11 again:+7
$ todo.sh again 5

Mark task 5 done.

Create new task as:

6 a weekly task t:2015-08-17 due:2015-08-18 again:+7

If no again tag is present, the current "no arguments" behavior remains the same.