Cook selections

As you can see if you enter it in your terminal, tofu invoked alone always prints the whole todo list. The first thing we will see is thus how to make more precise selections.

The easiest way to get a set of tasks is to call them by their position in the todo, enter this in your terminal:

$ tofu 3 2 5

You can also use a negative way, specifying the tasks you want to exclude and getting the others:

$ tofu -3 -2 -5

But let discover what's happens when we use the both mechanisms:

$ tofu 1 2 3 -3 -4 -5

As you can see, you get the two first tasks and the five last ones. We can deduce two things from this: 1) the -n (de-)selector is stonger than n, 2) when the selection is made exclusively from n selectors, this one is limited to the tasks selected by this way, but it's not the case when selector with a larger scope (-n means "all but") are introduced.

The first point is easy to understand and just illustrates the fact that tofu always takes the selection the most restrictive it can define. The second is more obscure though, has it any sense to use n with other ones? It has, let use them with the max=amount selector, which limits the amount of tasks selectedi, and the all one, which just call all the tasks in the selection:

$ tofu 7 8 9 all max=4

It results a selection composed from the first task plus the tasks we've explicitely selected. This shows the role of the n selectors when they are mixed with others: they create exceptions, so that the tasks selected by this way are never removed from the selection unless it's precisely requested.

Order your todo

With tofu, the tasks are sorted by decreasing order of priority, so change the priority of a tasks is the same as change its position in the todo. The action to perform that is jump=position, try:

$ tofu 2 5 6 jump=1
$ tofu

tofu first extracts the tasks from the todo and makes a sub-list with them (it means that you could have write 6 5 2, the results would have been the same), then it inserts this one at the requested position in the remaining list. This means that the requested position doesn't refer to the one of the task which is currently at this one, but to the final position of the sub-list in the final todo. Illustration:

$ tofu 2 3 5 jump=4
$ tofu

You can see that the tasks 2, 3 and 5 are at the good position (fourth) in the current todo, but the task which was at the fourth in the previous todo is now the second one. So, keep in mind that the position are absolutely defined, not relatively to a task. It could seem not very handy at first glance, but in general it's not a problem (it's only unintuitive when the same jump both decreases and increases the priority of selected tasks).

Nevertheless, there are cases were it's handier to place the tasks relatively to another one. This can be achieved with the ride=task action:

$ tofu 2 3 8 ride=6
$ tofu

In the example above, the selection is inserted before the sixth task (which is now the seventh, due to the eighth which took a place before it). To get the same result with an absolute placing, the selection should have been sent to the fourth position.

Edit and feed your tasks

Until now, a task has appeared to us as a mere line of text, but tofu does not limit you to this narrow format. Indeed, you have the possibility to append to each task as much further text as you want. This is very useful, for example when you know the algorithm you plan to use to realize a certain functionnality or when there are points you have absolutely to keep in mind when you modifying a certain part of code. Append text is performed with the edit action. Enter this an add some text after the first line:

$ tofu 1 edit

If, as usual, you type tofu on the command line after your editor's closed, you won't see much changes. This is normal, because default display of tofu tries to be concise. To recover the text you have entered, you have to use another display which is specified through the read action:

$ tofu 1 read
$ tofu 1 4 7 read

The first command above displays what you've written precedently, the second just aims to show you how tofu display several tasks in this mode. You can note that before each task header is inserted the position of the task, so that you can easily retrieve the ones interesting you in further tofu commands.

When things are got done

Once you have realized a task in your todo, this one becomes useless. In the world of tofu, the way to process with such tasks is merely to definitively wipe them out. This is made through the delete action:

$ tofu 11 delete

To avoid precipitate trashing, tofu will always ask to you a confirmation and give you the possibility to read entirely the task a last time before throwing it back to the null dimension. This temperate behaviour also allows to strip a selection of tasks, deleting some and keeping others.

Several operations on a single line

You've maybe remarked that the command lines we presented until now always put the selectors before the actions. This is merely because you can perform several selection-then-action cycles on the same line. Each time tofu detects a selector after a set of actions, it begins a new cycle. Look at this:

$ tofu 1 2 list 2 jump=1 1 2 list

As you can see, the two first tasks are primarily listed, then the second is moved to the first position, and endly we get an updated list. Trivial to understand, isn't it? Well, there is although a little subtlety, try this:

$ tofu 1 jump=7 list 1 list

Do you see the problem? in the second selection, the task should be different, as we have sent the first task to the seventh position, but it shows precisely this one at the seventh position. In fact, this is not a problem, but a solution. As matter of fact, when you begin to write a complex command line you generally know which task is which task, but after one or two jump or/and deletion it can rapidly become tricky to anticipate the position of each one. That's why tofu chooses to always refer to the initial positions in the todo, the only ones you can really know. So when you use n or -n, you can safely do it all along the line, you're sure of the task it will point on.

Getting the right thing to work on now

The command to use to add tags is stamp=tags, let's add some on our tasks:

$ tofu 2 3 8 stamp=myproject,code
$ tofu 6 stamp=myotherproject,code
$ tofu 8 9 stamp=bug
$ tofu 7 10 stamp=read
$ tofu 1 4 stamp=life,pointless all

As you can see, the tags now appear in the digest of the tasks they are put on. This allows to easily retrieve our tasks accoding to the type of things we want to do at the moment. For example, if you want to code:

$ tofu wi=code

or, on the contrary, if after passing the day to do it, you want to do anything but not debugging nor coding:

$ tofu wo=code,bug

The new wi=tags and wo=tags we introduced respectively select and reject any task which bears at least one of the specified tags. There are also variants of them that select or reject any task which bears all of the specified tags:

$ tofu wil=bug,myproject digest wol=bug,myproject digest wo=read 10

As expected, the first cycle above shows you the eighth task while the second prints the ninth. The third cycle merely recalls you the characteristic of the individual selectors (the tenth task bears "read"), which becomes very handy used in conjonction with the tags.

To remove tags, use the erase=tags command:

$ tofu 1 4 erase=pointless

A todo can hide another one

Tagging is a mechanism which quitely helps to deal with a large todo list. But it reaches its limits soon. For example, when you work on a project, you really don't care about the rest of your todo list and it's quickly annoying to have to remember to explicitely include or exclude this or this tag in commands. The queue=tag selector aims precisely to resolv such problems:

$ tofu queue=myproject

It creates a new list with all the tasks bearing the requested tag and masks the others. Moreover, tofu will stay in this queue as long as you don't order a change and automatically add its associated tag to the new tasks, so you can safely keep the nose in your project for hours, you don't risk to mess tasks that are not related. To get back the whole todo, simply request the main queue, which is a reserved item:

$ tofu queue=main

Note that change queue in the middle of a command line reset the individual selector references, so avoid to use them both or choose your queue in the first cycle:

$ tofu queue=read 1 list queue=bug 1 list 1 queue=main list

As you can see, each cycle above shows a different task for the same selector.