Sort

sort.pl sorts the tasks in your todo.txt file. By default it sorts your tasks based on priority (descending), but you can specify your own sort order based on various fields. You can specify the sort order using the -s flag and a comma separated list of fields to sort on. The following fields are supported:

• creation
• description
• due
• priority
• completion
• start (or just t)
• length (or just l)
• importance (defined below)
• importance-no-wknd
• importance-average
• importance-average-no-wknd

You can prefix each field with asc: or desc: for ascending or descending sort respectively. For instance you can invoke sort.pl as follows:

./sort.pl -s desc:importance,asc:creation

Note that asc: is the default so it is not necessary to write it down explicitly.

Importance

Importance is a derived field based on the priority, due date and the fact whether a task is 'starred'. Those who used the Toodledo task manager may recognize this. The metric is defined as 2 + P + S + D where:

• P is the priority (A=3, B=2, C=1, otherwise value 0, you can adjust the hash at the top of sort.pl to override)
• S is 1 if the task is starred. This is an attribute used within Toodledo to raise extra attention to a certain task, the importance value would be increased by one. You can emulate this in your todo.txt file by adding the star:1 tag to your item.
• D depends on the due date:
  • 0 there is no due date or more than 14 days ahead in the future;
  • 1 if the due date is within 7 and 14 days;
  • 2 if the due date is within 2 and 7 days;
  • 3 if the due date is tomorrow;
  • 5 if the due date is today;
  • 6 if the task is overdue.

importance-no-wknd can be used to ignore weekends when calculating the importance of a task. Assume it's Friday today and there's a task due next Monday, then that task will be treated as if it had to be done tomorrow.

importance-average takes the importance of the parent tasks into account, in case you use dependencies. Consider two low priority tasks A and B. A has a low priority parent while B has a high-priority parent. Because of this, B will get a higher importance than A. The task's importance value is obtained by calculating the average importance of all ancestors of that task (including itself). Note that the maximal importance is used, choosing between the task's importance and the average importance of its ancestors. This means that a task won't get a lower importance because it happens to have low priority ancestors.

importance-average-no-wknd is the combination of the two keywords described above.