hledger/hledger-lib/hledger_timedot.5

.TH "hledger_timedot" "5" "March 2019" "hledger 1.14.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.
.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[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
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[R]
.fi
.PP
Or with numbers:
.IP
.nf
\f[C]
2016/2/3
inc:client1   4
fos:hledger   3
biz:research  1
\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-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