hledger/hledger-lib/hledger_timedot.5

.TH "hledger_timedot" "5" "December 2017" "hledger 1.5" "hledger User Manuals"



.SH NAME
.PP
Timedot \- hledger'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 \[lq]timedot\[rq], 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'll assume it's time.
.SH FILE FORMAT
.PP
A timedot file contains a series of day entries.
A day entry begins with a date, and is followed by category/quantity
pairs, one per line.
Dates are hledger\-style simple dates (see hledger_journal(5)).
Categories are hledger\-style account names, optionally indented.
As in a hledger journal, there must be at least two spaces between the
category (account name) and the quantity.
.PP
Quantities can be written as:
.IP \[bu] 2
a sequence of dots (.) representing quarter hours.
Spaces may optionally be used for grouping and readability.
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[], \f[C]m\f[], \f[C]h\f[], \f[C]d\f[], \f[C]w\f[], \f[C]mo\f[],
or \f[C]y\f[], 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
Blank lines and lines beginning with #, ; or * are ignored.
An example:
.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[]
.fi
.PP
Or with numbers:
.IP
.nf
\f[C]
2016/2/3
inc:client1\ \ \ 4
fos:hledger\ \ \ 3
biz:research\ \ 1
\f[]
.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[]
.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[]
.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[]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50\ \ fos
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.00\ \ \ \ hledger:timedot
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0.50\ \ \ \ ledger
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50
\f[]
.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-2016 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