timewarrior-timeclock

An extention for Timewarrior to export your activity into the timeclock format used by Plain Text Accounting tools like ledger and hledger.

Quick Start

1. Copy the timeclock.pl script into your Timewarrior extensions directory (usually something like ~/.timewarrior/extensions and make sure that it's executable.
2. Run timew timeclock to generate your report! You can add any filters you want, like timew timeclock today

Configuration

Other extensions manage their own config files, but I realised you can add custom settings within the Timewarrior config itself! These be directly added to timewarrior.cfg or using the command timewarrior config SETTING_NAME VALUE

The configuration variables for this script are described below.

ext.timeclock.accounts

This is the long setting that maps Timewarrior tags to timeclock-style accounts. The way Timewarrior parses settings they have to be on a single line, so the format for this is pairs of TAG = ACCOUNT separated by semicolons (;). For example, this setting

doing work=Life:Work;play=Life:Play

would set the following mappings:

• tag doing work to account Life:Work
• tag play to account Life:Play

You can add whitespaces around the = and ;; they will be stripped automatically before parsing. Note that this means tags with spaces at the end like play will not be supported.

If a timewarrior entry has multiple tags, this srcript will attempt to match against each one. If none of the tags match, the behaviour specified by ext.timeclock.unknown_tags will be used.

Default: empty

ext.timeclock.unknown_tags

Define how to handle unknown tags.

This setting defines how to handle tags that are not mapped to accounts in the ext.timeclock.accounts setting defined above. The default behaviour is to "guess" the unknown tag, i.e. use the tag name as the account name. This way you can just use whatever account names you want when tracking time with Timewarrior, and it'll automatically be passed on to your timeclock file.

There are four possible settings in total:

• guess - "guess" the account name based on the tag name (in other words, take the first tag and use that as the account name). If the record is untagged, the default tag (from ext.timeclock.default_tag, described below) is used instead. If no default tag is set, an error is thrown.
• default - use a "default" tag from the ext.timeclock.default_account setting when a record with no known tags is found. This default tag is also used for untagged records. Note that "default" doesn't mean this is the default setting; it just describes what account name is to be used!
• fail - fail immediately whenever an unknown tag or a record with no tags is encountered. This is the strictest behaviour and forces you to either define the tags or tell Timewarrior to filter them out.
• ignore - silently ignore records where the tags are blank or the account names can't be matched. This is the most permissive, but you should be careful while using this to make sure you don't accidentally miss out on some records! When possible, try to use some other setting and choose which records you want using timewarrior filters instead.

Default: guess

ext.timeclock.default_account

A default account to set records to if a record is untagged or if a tag mapping is not specified.

This setting is used in one of the following situations:

• an untagged record comes up, and ext.timeclock.unknown_tags is set to guess or default
• no matching tag is found, and ext.timeclock.unknown_tags is set to default

Default: empty (needs to be set)

Contributing

It's just me right now but any feedback and contributions are welcome :)

You can also find me on the Fediverse as @badrihippo@fosstodon.org.

Licence

This script is licensed under the GNU General Public License version 3, or at your convenience, any later version. For details check the LICENCE file.