Time Tracking

Documentation in progress.

Doing entries always have a start date, and --- unless you specify otherwise --- when you mark an entry as @done, the @done tag gets a date value. Doing can then calculate the interval between start and finish to show how long you spent on any given entry.

All of the display commands (show, view, etc.) have a template option to show %interval in the output. When this is present, any entry listed that has a non-zero interval will display its elapsed time.

You can also use the --totals option with various commands (grep, on, recent, show, since, today, view, yesterday) to total up times based on @tags. The output will show the total time recorded for all items containing each tag. Times are listed in DD:HH:MM.

For example, if you'd been adding entries as you worked last week and wanted to see where you spent your time during the work week, you could run doing show --from "mon to fri" --times --totals. The output would include a block at the end like this:

--- Tag Totals ---
bunch:           00:00:33
coding:          00:06:58
communication:   00:00:24
contentcreation: 00:01:05
design:          00:00:44
doing:           00:02:34
meetings:        00:03:42
wiki:            00:00:25
writing:         00:01:13

I use local config files to automatically tag projects and activities based on what directory I'm running Doing from, so this gives me a pretty good idea where I've been. You can easily create a local config with a default_tags key by running doing tag_dir TAG, which will create/update a .doingrc in the current directory with your TAG arguments as an array. You can easily generate a local configuration file with a default_tags key using doing tag_dir [tag...].

Modifying the Start Date of an Entry

Start dates are set when creating an entry, based on the current time and any flags that modify it (--back, --took, --at, etc.). If you want to update a start date, there are a couple of commands that make it easy.

doing reset

doing reset will reset the start date of the last entry to the current time. You can choose a different time by providing a date string, e.g. doing reset yesterday 5pm. The reset command accepts search and tag filters to allow it to act on an entry further back in the history, or you can use --interactive to select an entry to reset from a menu.

doing reset --tag working,project1 --bool AND 12:30pm

doing reset also accepts a --from flag, allowing you to specify both a start and end time in one string, specified as a range. For example, to reset the start date to 12:30pm and add or update a @done tag at 1pm for the last entry, you would use doing reset --from "12:30pm to 1pm".

Editing Manually

You can also manually edit the start times of entries. Any command that opens an editor will include the start time in the editable text. You can modify this, and when you save, the start time will be parsed and updated. You don't have to use Doing formatting for the date, any natural language date/time string that Doing can parse will work.

doing last --tag working,project1 --bool AND --editor

Edit multiple entries using doing select --editor. All start times for the selected entries can be modified.

Note: when modifying dates in an editor, you can also use natural language in @done tags, e.g. @done(yesterday 3pm) The content of the tag will be parsed and updated when the entry is saved. To configure doing to expand dates in other tags, add an array of tag names/patterns to the date_tags key in your Configuration.

End Dates

When you finish an entry with doing done or doing finish, the current time is applied to the @done tag. This can be adjusted using flags like --took (specify a duration from start date) and --at (specify a day/time). You can open an entry in your editor after the fact (e.g. doing last -e) and update the @done tag value manually. Remember that you can use natural language (e.g. @done(mon 3pm)) and it will be converted to a timestamp when you save.

If you want to adjust an end date, you can use doing finish --update, which will overwrite any existing @done tag. This will update it to the current time, or use --at 1pm or --took 30m to manually adjust the end date.

When using doing finish or doing done, if the total elapsed time that would be recorded is greater than 5 hours (configured with interaction.confirm_longer_than), you will be presented with a confirmation request (assuming Doing is running in an interactive session). If you answer No to the confirmation, you can enter a duration manually (natural language) to override the @done value that will be added. You can adjust the maximum time that triggers the dialog in your config under interaction.confirm_longer_than.

interaction:
	confirm_longer_than: 2h

Skipping time tracking for an entry

You can use --no-date with tag/finish/done to avoid adding a timestamp to the @done tag. This means that in time totals reports the entry will show no elapsed interval. When you use doing cancel, it adds a dateless @done.

If you have occasion to frequently create entries that should not be timed, you can use the never_time config setting to prevent a date from being included with the @done tag based on section or tags. This will prevent any time interval from being recorded for the entry. In your ~/.doingrc file, include an array of tags or sections which should never be timed. Tags should begin with @, anything without an @ will be assumed to be a section.

never_time: [@idea, @reminder, Ideas]

With the above config, any entry tagged "@idea" or "@reminder", or in the section "Ideas" would never be timed. If a command is called which finishes them, they'll receive a "@done" tag with no date value.

In the above example, I'm using the "@idea" tag to track ideas. I might add an idea for future reference and leave it for days. When I finally get around to doing something with it, I don't want 72 hours of time to be tracked in my reports. With the never_time setting, I'll know that I can just use doing finish with a search argument to mark it complete and it won't be dated.

You can also prevent an entry from ever being marked @done with the never_finish key (using the same parameters).