202 lines
5.0 KiB
Groff
202 lines
5.0 KiB
Groff
|
|
.TH "hledger_timedot" "5" "March 2020" "hledger 1.17.99" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
Timedot - hledger\[aq]s human-friendly time logging format
|
|
.SH DESCRIPTION
|
|
.PP
|
|
Timedot is a plain text format for logging dated, categorised quantities
|
|
(of time, usually), supported by hledger.
|
|
It is convenient for approximate and retroactive time logging, eg when
|
|
the real-time clock-in/out required with a timeclock file is too precise
|
|
or too interruptive.
|
|
It can be formatted like a bar chart, making clear at a glance where
|
|
time was spent.
|
|
.PP
|
|
Though called \[dq]timedot\[dq], this format is read by hledger as
|
|
commodityless quantities, so it could be used to represent dated
|
|
quantities other than time.
|
|
In the docs below we\[aq]ll assume it\[aq]s time.
|
|
.PP
|
|
A timedot file contains a series of day entries.
|
|
A day entry begins with a non-indented hledger-style simple date (Y-M-D,
|
|
Y/M/D, Y.M.D..) Any additional text on the same line is used as a
|
|
transaction description for this day.
|
|
.PP
|
|
This is followed by optionally-indented timelog items for that day, one
|
|
per line.
|
|
Each timelog item is a note, usually a hledger:style:account:name
|
|
representing a time category, followed by two or more spaces, and a
|
|
quantity.
|
|
Each timelog item generates a hledger transaction.
|
|
.PP
|
|
Quantities can be written as:
|
|
.IP \[bu] 2
|
|
dots: a sequence of dots (.) representing quarter hours.
|
|
Spaces may optionally be used for grouping.
|
|
Eg: ....
|
|
\&..
|
|
.IP \[bu] 2
|
|
an integral or decimal number, representing hours.
|
|
Eg: 1.5
|
|
.IP \[bu] 2
|
|
an integral or decimal number immediately followed by a unit symbol
|
|
\f[C]s\f[R], \f[C]m\f[R], \f[C]h\f[R], \f[C]d\f[R], \f[C]w\f[R],
|
|
\f[C]mo\f[R], or \f[C]y\f[R], representing seconds, minutes, hours, days
|
|
weeks, months or years respectively.
|
|
Eg: 90m.
|
|
The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m,
|
|
1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
|
|
.PP
|
|
There is some flexibility allowing notes and todo lists to be kept right
|
|
in the time log, if needed:
|
|
.IP \[bu] 2
|
|
Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are
|
|
ignored.
|
|
.IP \[bu] 2
|
|
Lines not ending with a double-space and quantity are parsed as items
|
|
taking no time, which will not appear in balance reports by default.
|
|
(Add -E to see them.)
|
|
.IP \[bu] 2
|
|
Org mode headlines (lines beginning with one or more \f[C]*\f[R]
|
|
followed by a space) can be used as date lines or timelog items (the
|
|
stars are ignored).
|
|
Also all org headlines before the first date line are ignored.
|
|
This means org users can manage their timelog as an org outline (eg
|
|
using org-mode/orgstruct-mode in Emacs), for organisation, faster
|
|
navigation, controlling visibility etc.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
|
|
2016/2/1
|
|
inc:client1 .... .... .... .... .... ....
|
|
fos:haskell .... ..
|
|
biz:research .
|
|
|
|
2016/2/2
|
|
inc:client1 .... ....
|
|
biz:research .
|
|
\f[R]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2016/2/3
|
|
inc:client1 4
|
|
fos:hledger 3
|
|
biz:research 1
|
|
\f[R]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
* Time log
|
|
** 2020-01-01
|
|
*** adm:time .
|
|
*** adm:finance .
|
|
\f[R]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
* 2020 Work Diary
|
|
** Q1
|
|
*** 2020-02-29
|
|
**** DONE
|
|
0700 yoga
|
|
**** UNPLANNED
|
|
**** BEGUN
|
|
hom:chores
|
|
cleaning ...
|
|
water plants
|
|
outdoor - one full watering can
|
|
indoor - light watering
|
|
**** TODO
|
|
adm:planning: trip
|
|
*** LATER
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Reporting:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$ hledger -f t.timedot print date:2016/2/2
|
|
2016-02-02 *
|
|
(inc:client1) 2.00
|
|
|
|
2016-02-02 *
|
|
(biz:research) 0.25
|
|
\f[R]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$ hledger -f t.timedot bal --daily --tree
|
|
Balance changes in 2016-02-01-2016-02-03:
|
|
|
|
|| 2016-02-01d 2016-02-02d 2016-02-03d
|
|
============++========================================
|
|
biz || 0.25 0.25 1.00
|
|
research || 0.25 0.25 1.00
|
|
fos || 1.50 0 3.00
|
|
haskell || 1.50 0 0
|
|
hledger || 0 0 3.00
|
|
inc || 6.00 2.00 4.00
|
|
client1 || 6.00 2.00 4.00
|
|
------------++----------------------------------------
|
|
|| 7.75 2.25 8.00
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
I prefer to use period for separating account components.
|
|
We can make this work with an account alias:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
2016/2/4
|
|
fos.hledger.timedot 4
|
|
fos.ledger ..
|
|
\f[R]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$ hledger -f t.timedot --alias /\[rs]\[rs]./=: bal date:2016/2/4
|
|
4.50 fos
|
|
4.00 hledger:timedot
|
|
0.50 ledger
|
|
--------------------
|
|
4.50
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Here is a sample.timedot.
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger IRC channel or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2019 Simon Michael.
|
|
.br
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
|
|
ledger(1)
|
|
|
|
http://hledger.org
|