Details
Here's a summary of the commands in Busy.
Output commands:
describe
tells the most about an item or set of itemssimple
includes less detail thandescribe
base
includes even less detailresource
shows the URL (if any) associated with an itemlist
is likedescribe
but with sequence numbersqueues
to lists all the queuestags
to lists tags from a queue
Commands that make changes:
add
adds a new itemdone
marks an item as 'done' and gives the option of iterating - "done for today"defer
puts a task or set of items on the plan for a future datepop
moves a task or set of items to the top of a queue - "pop it to the top"drop
moves a task or set of items to the bottom of a queue - "drop it to the bottom"pick
moves one random item from the filtered set to the top of the queue - "pick one for me"delete
permanently removes a task or set of items from a queueedit
opens a text editor to edit items - the default is to edit only the top itemmanage
is the same asedit
, but defaults to edit the whole collectionactivate
finds everything planned for today and adds it to the list - "activate my day"
Here are some of the options which apply to some or all of the commands:
- filters to designate items to be acted upon, using sequence numbers or tags
- the
add
command requires a description of the new item instead of filters --queue
if not the defaulttasks
queue--help
to find out which options apply--yes
to skip confirmation of any command that requires it--state
to work on Items of a different state (todo
,plan
,done
)--when
applies to thedefer
command--defer
applies to thedone
command
Sequence numbers
Sequence numbers appear in the output from the list
command. Note that the numbering starts with 1, and is not an ID -- the number of a item will change when the collection is modified. So always reference the most recent output from the list
command.
Sequence numbers are used with filters. To designate more than one item, separate the sequence numbers with a space.
Another choice is ranges. A range of sequence numbers is separated by a hyphen, with no whitespace, and is inclusive. For example, 4-6
designates items 4, 5, and 6. A hyphen without a number after it includes all the items from that item to the end of the queue. A hyphen on its own indicates the last item in the queue.
Below are some examples of task designations by sequence number.
busy pop 5
pops item number 5busy drop 3-7
drops items 3 through 7 (4 items)busy list 3-
lists all the items from number 3 through the end of the listbusy delete 3 5 7 9
deletes only the items designatedbusy defer -
defers the last taskbusy edit -4
is an error! Usebusy edit 1-4
insteadbusy manage
allows you to edit the entire queue
Items will always be handled in the order they appear in the queue, regardless of the order the filter are provided. So for example, if a pop
command designates some items, they will be moved to the top of the queue in the order, relative to each other, they currently appear in the queue.
The sequence numbers in the list
command output are from the collection itself. So the list
command does not modify the sequence numbers, even when item designation is applied.
Tags
BusyML includes tags as words in item descriptions starting with #
.
Tags may be used as filter in addition to sequence numbers. For example, the following command will move all the items with the #errands
tag to the top of the queue.
busy pop errands
Numerical filters use OR logic with each other, and tag filters use OR logic with each other. But AND logic applies between the two types. For example, the command below deletes tasks in the range 1-10 that have either the admin or sales tag.
busy delete 1-10 admin sales
To use AND logic with tags in filters, combine them with a plus (+). For example, the command below lists tasks that are tagged both daily and admin.
busy list daily+admin
Named Filters
Specific filters can be named for the plan
and done
queues to specify date ranges. Use a colon.
planmin:2024-09-28
planmax:2024-09-28
donemin:2024-09-28
donemax:2024-09-28
Default item designations
For the most part, commands that accept item designations default to only act on the top item in the queue. The exceptions are:
list
andmanage
default to handle the entire collectionpop
defaults to pop the last item in the collection to the topactivate
defaults to activateplan
items for today (more on that below)add
adds to the bottom of thetodo
queue
Alternate queues
Busy will manage any number of queues, which are entirely separate sets of items. For example, you might have a shopping
queue for items to buy at the store, and a movies
queue for films you'd like to watch. The default queue is called tasks
.
To designate an alternate queue, use the --queue
or -q
option. For example:
busy add --queue shopping -d "Skimmed Milk"
busy list -q movies
Managing plans
Busy supports several specific commands related to planning -- that is, scheduling tasks for the future. They are done
, defer
, and activate
. The task-specific commands handle items in the plan
state and, in some cases, the done
state.
The task commands accept filters. The done
and defer
commands reference the todo
collection; the activate
command references the plan
collection. The default for done
and defer
is the top item in the collection; the default for activate
is to activate only plans deferred to today or earlier.
Planning by date
Planning is by date, not time, and is relative to the current date according to the system clock.
In the done
command, the date can be specified using the --defer
option (or by inputting a value after issuing the command). If the option is omitted, then the date can be provided as input during confirmation.
The date may take any of the following forms:
- A specific date in
YYYY-MM-DD
format, such as2018-10-28
. Slashes are also acceptable, but the order is always year, then month, then day. - A specific date without the year in
MM-DD
format, such as7-4
, which will defer the item to that date in the future (even if it's in the next year). - A specific day of the month as a simple integer, such as
12
, which will defer the item to that day of the month, in either the current month or the next month. - An integer, a space, and the word
day
ordays
, such as4 days
, which will defer the item to that number of days from today. - An integer without a space and the letter
d
, such as4d
, which is a short form of4 days
. - The word
tomorrow
, which is also the default if no date is provided. - The word
today
, which is useful for activating tasks later in the day.
As an example, the following command will defer tasks 4, 5, and 6 from the todo
collection to the date 4 days from today, keeping them in the plan
collection until that date.
busy defer 4-6 -t "4 days"
Note that the plan
collection keep the task information from the todo
collection along with the date information (as an absolute date).
To pull tasks from the plan
collection and put them back into the todo
collection, use the activate
command. There are two ways to use the activate
command:
- With no filter, in which case Busy activates all the tasks scheduled for today or earlier, bringing the
todo
list up to date - With designated items from the
plan
collection; note that theactivate
command accepts item designation from theplan
queue itself so usebusy list -s plan
first to get the right list.
Finishing and iterating
The done
command removes the designated Task (or the top task if none is designated) from the todo
state and adds it to the done
state, with today's date to indicate when it was completed.
Optionally, a task can have a repeat value by adding a right angle bracket and the word "repeat" with a time value.
check email > repeat in 1 day
phone mom > repeat on sunday
balance the checkbook > repeat on 6
The exact syntax for a Repeat is the word "repeat" followed by either "on" or "in" and a relative date phrase -- the same phrases that work with the defer
command.
The done
command uses the repeat value as the default for its iteration.
Editing items
The edit
and manage
commands launch the user's default text editor to directly edit a task, the whole queue, or part of a queue. Note that edit
and manage
are identical commands except for their default filter.
A text editor can be designated in a configuration file (.busy.yml
) otherwise Busy uses Emacs.
The edit
command with no filter will edit the top item in the list, and the manage
command with no filter will edit the entire list. But it's also possible to designate items to be edited with both commands using a filter. The commands do their best to replace the edited items in place in the list order. So if you edit
or manage
a tag whose items are recently popped (at the top of the collection), then the edited items will still appear at the top. Even if you add items, they will be inserted after the last item in the edited set, not at the end of the queue. But all the items brought up in the editor will be edited. So if you remove an item in the editor, it will be deleted and the others will be moved up to take its place.
The editing process includes the full descriptions in BusyML.
Data storage
Busy keeps the collections in plain text files, so if the tool doesn't do something you want, you may edit the files. The files are in a directory together, referred to as the "root". Each file is the named according to the following convention:
<queue>.<state>.psv
If a required file is missing, it will be created automatically. So typically, the root includes tasks.todo.psv
, tasks.plan.psv
, tasks.done.txt
, and any number of custom queue files.
Technically, Busy data files are pipe-delimited data files, though the todo
collections only have one field ("description") while the plan
and done
files have only two fields (date and description).
Busy is not a database (yet). There is no support for managing separate fields in the Busy tool itself.
The default location for the files is a directory at ~/.busy
, which will be generated as needed. Specify an alternative location using the --config
option referencing a YAML file with the following format:
busy:
storage:
directory: /some/other/directory
Note that Busy does not support concurrency or locking in any form. If two commands are executing at the same time, they might overwrite each other. Overwriting is especially risky with the edit
and manage
commands, which keeps the user's editor open until they close it.
The format is designed to be simple but not idiot-proof. Experimentation might result in unintended consequences.