summaryrefslogtreecommitdiff
path: root/hledger_timedot.5
blob: 6d06f17d5c360bcee58dd98299e8ce5a60d7b916 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199

.TH "HLEDGER_TIMEDOT" "5" "December 2020" "hledger-lib-1.20.4 " "hledger User Manuals"



.SH NAME
.PP
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 --tree
                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-2020 Simon Michael.
.br
Released under GNU GPL v3 or later.

.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)

hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5)