A simple, CLI-based, personal time tracking utility. tid uses Bolt as a storage backend, and
does not require an active daemon to run.
The easiest method is with the installation script:
$ curl -s https://raw.githubusercontent.com/SeerUK/tid/master/install.sh | sh
You can download a pre-built binary for Windows, Linux, or macOS on the Releases page. If you download a release for Linux or macOS you will have to make it executable.
Alternatively build from source using Go:
$ go get -u -v github.com/SeerUK/tid/...
Full usage information can be seen by using the built-in contextual help. This can accessed by running:
$ tid --help
$ # Or for command help:
$ tid start --help
Tid has sub-commands in some places, for example:
$ tid entry create 1h10m "Resolving live issue"
And also has short aliases for some commands:
$ tid e c 1h10m "Resolving live isssue"
Here's some simple general usage:
$ tid start "Working on AI"
Started timer for 'Working on AI' (fdb6f0d)
$ tid status
+------------+---------+------------+------------+---------------+----------+---------+
| DATE | HASH | CREATED | UPDATED | NOTE | DURATION | RUNNING |
+------------+---------+------------+------------+---------------+----------+---------+
| 2017-03-01 | fdb6f0d | 10:41:34AM | 10:41:34AM | Working on AI | 5s | true |
+------------+---------+------------+------------+---------------+----------+---------+
$ tid stop
Stopped timer for 'Working on AI' (fdb6f0d)
# Gone for lunch...
$ tid resume
Resumed timer for 'Working on AI' (fdb6f0d)
# Forgot to add this!
$ tid entry create 15m "Afternoon nap"
Created entry 'Afternoon nap' (3d77f69)
$ tid report
Report for 2017-03-01.
Total Duration: 2h34m37s
Entry Count: 2
+------------+---------+------------+-----------+-----------------+----------+---------+
| DATE | HASH | CREATED | UPDATED | NOTE | DURATION | RUNNING |
+------------+---------+------------+-----------+-----------------+----------+---------+
| 2017-03-01 | fdb6f0d | 10:41:34AM | 1:01:03PM | Working on AI | 2h19m37s | true |
+ +---------+------------+-----------+-----------------+----------+---------+
| | 3d77f69 | 1:26:30PM | 1:26:30PM | Afternoon nap | 15m0s | false |
+------------+---------+------------+-----------+-----------------+----------+---------+
$ tid start "A note"
The note is required, but can by any string value. It's used so when you view the status or the report you know what you've been tracking. Try make it something identifiable. Maybe this will just be an issue ID from your issue tracker?
$ tid stop
Stop always stops the currently active timer, if you don't have an active timer, it won't do anything.
$ tid resume
$ tid resume fdb6f0d
The resume command allows you to resume the most recently stopped entry, or a specific entry by passing in that entry's hash. If you don't have a most recently stopped entry then you would have to pass in an entry hash to use resume (e.g. if you remove the entry being tracked).
$ tid status
$ tid status fdb6f0d
$ tid status --format="{{.Duration}} on '{{.Note}}'"
You can view the status of the currently tracked entry (the most recently started or resumed entry) or you can view the status of a specific entry. The output is similar to the report output.
The --format option uses Go's text/template package, and is passed an Entry.
$ tid report
$ tid report --start=2017-02-01 --end=2017-02-28
$ tid report --start=(tiddate --months=-6)
$ tid report --no-summary
$ tid report --format="{{.Hash}} {{.Note}}" --no-summary
The report command is quite powerful and gives you a lot of different ways to view timesheet data.
By default the output will display a summary, and a table of the entries. You can control the output
by passing other options like --format which is useful for scripting.
The --format option uses Go's text/template package, and is passed an Entry.
Sometimes you just forget to track something, and maybe it was a couple of days ago! Or maybe you realised you've tracked some additional time by mistake. The entry management commands let you create new entries on the fly, or manage existing ones. There's also a listing that's similar to the report view, but without the summary.
$ tid entry create <DURATION> <NOTE>
$ tid entry create 10m "Hello, World"
$ tid e c 10m "Hello, World"
$ tid entry delete <HASH>
$ tid entry delete c24543c
$ tid e d c24543c
$ tid entry list [OPTIONS]
$ tid entry list --start=(tiddate --days=-7) --end=(tiddate) --format="{{.Hash}}"
$ tid entry list --date=(tiddate --days=-7)
$ tid e ls --date=(tiddate --days=-7)
The --format option uses Go's text/template package, and is passed an Entry.
$ tid entry update <HASH> [OPTIONS]
$ tid entry update c24543c --duration=10m --note="More CMS work..."
$ tid entry update c24543c --offset=-2m12s
$ tid e u c24543c --offset=-2m12s
The --duration and --offset options are mutually exclusive. Offset accepts negative values for
updating the duration by the amount given.
$ tid timesheet delete <DATE>
$ tid timesheet delete 2017-04-10
$ tid t d 2017-04-10
$ tid timesheet list [OPTIONS]
$ tid timesheet list --start=(tiddate --days=-7) --end=(tiddate) --format="{{.Hash}}"
$ tid timesheet list --date=(tiddate --days=-7)
$ tid t ls --date=(tiddate --days=-7)
The --format option uses Go's text/template package, and is passed an Timesheet.
Workspaces are separate time-tracking environments designed to segregate unrelated work. You can choose what that means, but one example could be tracking time for personal projects separately to work projects.
$ tid workspace create <NAME>
$ tid workspace create freelance
$ tid w c freelance
$ tid workspace delete <NAME>
$ tid workspace delete freelance
$ tid w d freelance
Deleting a workspace will remove all timesheets and entries within it. There's no recovery from this unless you've backed up your database.
$ tid workspace list
$ tid w ls
The active workspace will be denoted with an asterisk (e.g. default *).
$ tid workspace switch <NAME>
$ tid workspace switch freelance
$ tid w s freelance
Switching workspace will first stop any running timers, meaning you don't have to worry about time wracking up because you've forgotten to stop then switch!
Completions are provided for Bash and Fish and are located with obvious names in the extras/completions/
directory.
A BitBar plugin is available (with installation instructions) in the
extras/bitbar directory.
MIT