Skip to content

Timewarrior

Source documentation for Timewarrior.

Timewarrior is one of the most flexible tools. Thanks to its flexibility there is no built-in/dedicated way to mark an entry billable/unbillable, set client, project, or task.

Therefore, several assumptions were made to integrate with Timewarrior, though the goal was to keep the maximum flexibility.

Warning

Timewarrior has no built-in support for marking an entry billable/unbillable. Therefore, every entry will be treated as billable unless it is not forced by force-billed-duration or a matching tag for timewarrior-unbillable-tag.

Warning

When timewarrior-client-tag-regex or timewarrior-project-tag-regex is matching multiple tags, the last tag will be used.

Warning

To extract tasks from tags, set the tags-as-tasks-regex.

Field mappings

The source makes the following special mappings.

From To Description
Annotation Notes, Summary, Task (optionally) Annotations are used to set Notes and Summary; if no task regex is set, it will be used for Task as well
Tags Client, Project, Task Depending on the client, project, and task regex, tags will be used accordingly

CLI flags

The source provides to following extra CLI flags.

Flags:
    --timewarrior-arguments strings          set additional arguments
    --timewarrior-client-tag-regex string    regex of client tag pattern
    --timewarrior-command string             set the executable name (default "timew")
    --timewarrior-project-tag-regex string   regex of project tag pattern
    --timewarrior-unbillable-tag string      set the unbillable tag (default "unbillable")

Configuration options

The source provides the following extra configuration options.

Config option Kind Description Example
timewarrior-arguments []string Set additional arguments for the export command timewarrior-arguments = "reviewed"
timewarrior-client-tag-regex string Set the regular expression for extracting Client names from tags timewarrior-client-tag-regex = '^(CLIENT-\w+)$'
timewarrior-command string Set the timewarrior command timewarrior-command = "timew"
timewarrior-project-tag-regex string Set the regular expression for extracting Project names from tags timewarrior-project-tag-regex = '^PROJ-DEV-\w+$'
timewarrior-unbillable-tag string Set the regular expression to identify which entries are unbillable timewarrior-unbillable-tag = "unbillable"

Limitations

No known limitations.

Example configuration

# Source config
source = "timewarrior"
source-user = "-"  # Timewarrior does not support multiple users

# Timewarrior config
timewarrior-arguments = ["log"]
timewarrior-client-tag-regex = '^(oc)$'
timewarrior-project-tag-regex = '^(log)$'

# Target config
target = "tempo"
target-user = "<jira username>"

# Tempo config
tempo-url = "https://<org>.atlassian.net"
tempo-username = "<jira username>"
tempo-password = "<jira password>"

# General config
tags-as-tasks-regex = '[A-Z]{2,7}-\d{1,6}'
round-to-closest-minute = true
force-billed-duration = true