slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-09-03 20:22:46 +01:00
parent 8be3e85676
commit 82552b4ea8
13 changed files with 644 additions and 402 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
m4_define({{_monthyear_}}, {{September 2025}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
m4_define({{_monthyear_}}, {{September 2025}})m4_dnl

4
hledger-ui/hledger-ui.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "June 2025" "hledger-ui-1.43.99 " "hledger User Manuals"
.TH "HLEDGER\-UI" "1" "September 2025" "hledger-ui-1.50.99 " "hledger User Manuals"
@ -17,7 +17,7 @@ or
.PD
\f[CR]hledger ui [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.43.99.
This manual is for hledger\[aq]s terminal interface, version 1.50.99.
See also the hledger manual for common concepts and file formats.
.PP
hledger is a robust, user\-friendly, cross\-platform set of programs for

2
hledger-ui/hledger-ui.info
View File

@ -18,7 +18,7 @@ plain text accounting app.
or
'hledger ui [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.43.99.
This manual is for hledger's terminal interface, version 1.50.99.
See also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs

4
hledger-ui/hledger-ui.txt
View File

@ -11,7 +11,7 @@ SYNOPSIS
hledger ui [OPTS] [QUERYARGS]
DESCRIPTION
This manual is for hledger's terminal interface, version 1.43.99. See
This manual is for hledger's terminal interface, version 1.50.99. See
also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for
@ -471,4 +471,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.43.99 June 2025 HLEDGER-UI(1)
hledger-ui-1.50.99 September 2025 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
m4_define({{_monthyear_}}, {{September 2025}})m4_dnl

4
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "June 2025" "hledger-web-1.43.99 " "hledger User Manuals"
.TH "HLEDGER\-WEB" "1" "September 2025" "hledger-web-1.50.99 " "hledger User Manuals"
@ -17,7 +17,7 @@ or
.PD
\f[CR]hledger web [OPTS] [QUERY]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.43.99.
This manual is for hledger\[aq]s web interface, version 1.50.99.
See also the hledger manual for common concepts and file formats.
.PP
hledger is a robust, user\-friendly, cross\-platform set of programs for

2
hledger-web/hledger-web.info
View File

@ -18,7 +18,7 @@ plain text accounting app.
or
'hledger web [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.43.99. See
This manual is for hledger's web interface, version 1.50.99. See
also the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs

4
hledger-web/hledger-web.txt
View File

@ -11,7 +11,7 @@ SYNOPSIS
hledger web [OPTS] [QUERY]
DESCRIPTION
This manual is for hledger's web interface, version 1.43.99. See also
This manual is for hledger's web interface, version 1.50.99. See also
the hledger manual for common concepts and file formats.
hledger is a robust, user-friendly, cross-platform set of programs for
@ -480,4 +480,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.43.99 June 2025 HLEDGER-WEB(1)
hledger-web-1.50.99 September 2025 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{June 2025}})m4_dnl
m4_define({{_monthyear_}}, {{September 2025}})m4_dnl

193
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "HLEDGER" "1" "June 2025" "hledger-1.43.99 " "hledger User Manuals"
.TH "HLEDGER" "1" "September 2025" "hledger-1.50.99 " "hledger User Manuals"
@ -28,7 +28,7 @@ hledger is inspired by and largely compatible with ledger(1), and
largely interconvertible with beancount(1).
.PP
This manual is for hledger\[aq]s command line interface, version
1.43.99.
1.50.99.
It also describes the common options, file formats and concepts used by
all hledger programs.
It might accidentally teach you some bookkeeping/accounting as well!
@ -4165,6 +4165,11 @@ T}@T{
optionally declare which file to read data from
T}
T{
\f[B]\f[CB]archive\f[B]\f[R]
T}@T{
optionally enable an archive of imported files
T}
T{
\f[B]\f[CB]encoding\f[B]\f[R]
T}@T{
optionally declare which text encoding the data has
@ -4285,31 +4290,69 @@ All this enables a convenient workflow where can you just download CSV
files, then run \f[CR]hledger import rules/*\f[R].
.PP
See also \[dq]Working with CSV > Reading files specified by rule\[dq].
.SS Data cleaning / generating commands
After \f[CR]source\f[R]\[aq]s file pattern, you can write \f[CR]|\f[R]
(pipe) and a data cleaning command.
If hledger\[aq]s CSV rules aren\[aq]t enough, you can pre\-process the
downloaded data here with a shell command or script, to make it more
suitable for conversion.
The command will be executed by your default shell, in the directory of
the rules file, will receive the data file\[aq]s content as standard
input, and should output zero or more lines of
character\-separated\-values, suitable for conversion by the CSV rules.
.PP
The \f[CR]archive\f[R] rule adds a few more features to
\f[CR]source\f[R]; see below.
Examples:
.IP
.EX
source ./paypal.json | paypalcsv
source data/simplefin.json | simplefincsv \- \[aq]chase.*card\[aq]
source OfxDownload*.csv | grep \-vE \[aq]\[ha](([\[ha],]*,){6}[\[ha],]*|)$\[aq] | sort \-t, \-n +2
source History_for_Account_Z20144832*.csv # | grep \-E \[aq]\[ha]([\[ha],]*,){12}[\[ha],]*$\[aq] | sed \-E \-e \[aq]s/\[ha] //\[aq] \-e \[aq]s/\[rs].([0\-9]),/.\[rs]10,/g\[aq] \-e \[aq]s/,([0\-9]+),/,\[rs]1.00,/g\[aq]
.EE
.PP
Or, after \f[CR]source\f[R] you can write \f[CR]|\f[R] and a data
generating command (with no file pattern before the \f[CR]|\f[R]).
This command receives no input, and should output zero or more lines of
character\-separated values, suitable for conversion by the CSV rules.
.PP
Examples:
.IP
.EX
source | paypaljson | paypalcsv
source | paypalcsv data/paypal.json
source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json \[aq]chase.*card\[aq]
source | simplefincsv data/simplefin.json \[aq]unify.*checking\[aq]
.EE
.PP
(\f[CR]paypal*\f[R] and \f[CR]simplefin*\f[R] scripts are in bin/)
.PP
Whenever hledger runs one of these commands, it will echo the command on
stderr.
If the command produces error output, but exits successfully, hledger
will show the error output as a warning.
If the command fails, hledger will fail and show the error output in the
error message.
.PP
\f[I]Added in 1.50; experimental.\f[R]
.SS \f[CR]archive\f[R]
Adding the \f[CR]archive\f[R] rule to your rules file affects importing
or reading files specified by \f[CR]source\f[R]:
.IP \[bu] 2
After successfully importing, \f[CR]import\f[R] will move the data file
to an archive directory (\f[CR]data/\f[R] next to the rules file,
auto\-created), renamed to
\f[CR]RULESFILEBASENAME.DATAFILEMODDATE.DATAFILEEXT\f[R].
Archiving data files is optional, but it can be useful for
troubleshooting, detecting variations in your banks\[aq] CSV data,
regenerating entries with improved rules, etc.
.IP \[bu] 2
\f[CR]import\f[R] will pick the oldest of \f[CR]source\f[R] glob
matches, rather than the newest.
So if you have multiple versions of a download, repeated imports will
process them in chronological order.
.IP \[bu] 2
For commands other than \f[CR]import\f[R], when the \f[CR]source\f[R]
path or glob pattern matches no files, hledger will try to read the
latest archived data file instead.
This is convenient for working with the downloaded data again, even
after it has been imported.
With \f[CR]archive\f[R] added to a rules file, the \f[CR]import\f[R]
command will archive each successfully processed data file or data
command output in a nearby \f[CR]data/\f[R] directory.
The archive file name will be based on the rules file and the data
file\[aq]s modification date and extension (or for a data\-generating
command, the current date and the \[dq].csv\[dq] extension).
The original data file, if any, will be removed.
.PP
Also, in this mode \f[CR]import\f[R] will prefer the oldest file matched
by the \f[CR]source\f[R] rule\[aq]s glob pattern, not the newest.
(So if there are multiple downloads, they will be imported and archived
oldest first.)
.PP
Archiving is optional, but it can be useful for troubleshooting your CSV
rules, regenerating entries with improved rules, checking for variations
in your bank\[aq]s CSV, etc.
.PP
\f[I]Added in 1.50; experimental.\f[R]
.SS \f[CR]encoding\f[R]
.IP
.EX
@ -5515,7 +5558,6 @@ This is all done by the CSV reader, one of several readers hledger can
use to read transactions from an input file.
When all input files have been read successfully, their transactions are
passed to whichever hledger command the user specified.
.PP
.SS Well factored rules
Some things than can help reduce duplication and complexity in rules
files:
@ -5823,19 +5865,75 @@ $ hledger \-f paypal\-custom.csv print
revenues:foss donations:darcshub $\-10.00 ; business:
expenses:banking:paypal $0.59 ; business:
.EE
.SH Timeclock
The time logging format of timeclock.el, as read by hledger.
.PP
hledger can read time logs in timeclock format.
As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
containing clock\-in and clock\-out entries as in the example below.
The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ].
Seconds and timezone are optional.
The timezone, if present, must be four digits and is ignored (currently
the time is always interpreted as a local time).
Lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] or \f[CR]*\f[R], and
blank lines, are ignored.
.SH Timeclock
hledger can read time logs in the timeclock time logging format of
timeclock.el.
As with Ledger, hledger\[aq]s timeclock format is a subset/variant of
timeclock.el\[aq]s.
.PP
hledger\[aq]s timeclock format was updated in hledger 1.43 and 1.50.
If your old time logs are rejected, you should adapt them to modern
hledger; for now, you can restore the pre\-1.43 behaviour with the
\f[CR]\-\-old\-timeclock\f[R] flag.
.PP
Here the timeclock format in hledger 1.50+:
.IP
.EX
# Comment lines like these, and blank lines, are ignored:
# comment line
; comment line
* comment line
# Lines beginning with b, h, or capital O are also ignored, for compatibility:
b SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT]
h SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT]
O SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT]
# Lines beginning with i or o are are clock\-in / clock\-out entries:
i SIMPLEDATE HH:MM[:SS][+\-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]]
o SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ ACCOUNT][;COMMENT]
.EE
.PP
The date is a hledger simple date (YYYY\-MM\-DD or similar).
The time parts must use two digits.
The seconds are optional.
A + or \- four\-digit time zone is accepted for compatibility, but
currently ignored; times are always interpreted as a local time.
.PP
In clock\-in entries (\f[CR]i\f[R]), the account name is required.
A transaction description, separated from the account name by 2+ spaces,
is optional.
A transaction comment, beginning with \f[CR];\f[R], is also optional.
(Indented following comment lines are also allowed, as in journal
format.)
.PP
In clock\-out entries (\f[CR]o\f[R]) have no description, but can have a
comment if you wish.
A clock\-in and clock\-out pair form a \[dq]transaction\[dq] posting
some number of hours to an account \- also known as a session.
Eg:
.IP
.EX
i 2015/03/30 09:00:00 session1
o 2015/03/30 10:00:00
.EE
.IP
.EX
$ hledger \-f a.timeclock print
2015\-03\-30 * 09:00\-10:00
(session1) 1.00h
.EE
.PP
Clock\-ins and clock\-outs are matched by their account/session name.
If a clock\-out does not specify a name, the most recent unclosed
clock\-in is closed.
You can have multiple sessions active simultaneously.
Entries are processed in the order they are parsed.
Sessions spanning more than one day are automatically split at day
boundaries.
.PP
Eg, the following time log:
.IP
.EX
i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags:
@ -5848,16 +5946,7 @@ o 2015/04/02 14:00:00
o 2015/04/02 15:00:00 another:account
.EE
.PP
hledger treats each clock\-in/clock\-out pair as a transaction posting
some number of hours to an account.
Entries are paired by the account name if the same name is given for a
clock\-in/clock\-out pair.
If no name is given for a clock\-out, then it is paired with the most
recent clock\-in entry.
If the session spans more than one day, it is split into several
transactions, one for each day.
For the above time log, \f[CR]hledger print\f[R] generates these journal
entries:
generates these transactions:
.IP
.EX
$ hledger \-f t.timeclock print
@ -7818,10 +7907,10 @@ More specifically:
For single period reports (including normal print and register reports):
.RS 2
.IP \[bu] 2
If an explicit report end date is specified, that is used
If an explicit report end date is specified, that is used.
.IP \[bu] 2
Otherwise the latest transaction date or P directive date is used (even
if it\[aq]s in the future)
Otherwise the latest transaction date or non\-future P directive date is
used.
.RE
.IP \[bu] 2
For multiperiod reports, each period is valued on its last day.
@ -7829,8 +7918,6 @@ For multiperiod reports, each period is valued on its last day.
This can be customised with the \-\-value option described below, which
can select either \[dq]then\[dq], \[dq]end\[dq], \[dq]now\[dq], or
\[dq]custom\[dq] dates.
(Note, this has a bug in hledger\-ui <=1.31: turning on valuation with
the \f[CR]V\f[R] key always resets it to \[dq]end\[dq].)
.SS Finding market price
To convert a commodity A to its market value in another commodity B,
hledger looks for a suitable market price (exchange rate) as follows, in

676
hledger/hledger.info
View File

@ -24,7 +24,7 @@ accounting and a simple, editable file format. hledger is inspired by
and largely compatible with ledger(1), and largely interconvertible with
beancount(1).
This manual is for hledger's command line interface, version 1.43.99.
This manual is for hledger's command line interface, version 1.50.99.
It also describes the common options, file formats and concepts used by
all hledger programs. It might accidentally teach you some
bookkeeping/accounting as well! You don't need to know everything in
@ -4143,6 +4143,7 @@ The following kinds of rule can appear in the rules file, in any order.
*'source'* optionally declare which file to read data
from
*'archive'* optionally enable an archive of imported files
*'encoding'* optionally declare which text encoding the
data has
*'separator'* declare the field separator, instead of
@ -4215,7 +4216,53 @@ CSV files, then run 'hledger import rules/*'.
See also "Working with CSV > Reading files specified by rule".
The 'archive' rule adds a few more features to 'source'; see below.
* Menu:
* Data cleaning / generating commands::

File: hledger.info, Node: Data cleaning / generating commands, Up: source
9.2.1 Data cleaning / generating commands
-----------------------------------------
After 'source''s file pattern, you can write '|' (pipe) and a data
cleaning command. If hledger's CSV rules aren't enough, you can
pre-process the downloaded data here with a shell command or script, to
make it more suitable for conversion. The command will be executed by
your default shell, in the directory of the rules file, will receive the
data file's content as standard input, and should output zero or more
lines of character-separated-values, suitable for conversion by the CSV
rules.
Examples:
source ./paypal.json | paypalcsv
source data/simplefin.json | simplefincsv - 'chase.*card'
source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2
source History_for_Account_Z20144832*.csv # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g'
Or, after 'source' you can write '|' and a data generating command
(with no file pattern before the '|'). This command receives no input,
and should output zero or more lines of character-separated values,
suitable for conversion by the CSV rules.
Examples:
source | paypaljson | paypalcsv
source | paypalcsv data/paypal.json
source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card'
source | simplefincsv data/simplefin.json 'unify.*checking'
('paypal*' and 'simplefin*' scripts are in bin/)
Whenever hledger runs one of these commands, it will echo the command
on stderr. If the command produces error output, but exits
successfully, hledger will show the error output as a warning. If the
command fails, hledger will fail and show the error output in the error
message.
_Added in 1.50; experimental._

File: hledger.info, Node: archive, Next: encoding, Prev: source, Up: CSV
@ -4223,25 +4270,22 @@ File: hledger.info, Node: archive, Next: encoding, Prev: source, Up: CSV
9.3 'archive'
=============
Adding the 'archive' rule to your rules file affects importing or
reading files specified by 'source':
With 'archive' added to a rules file, the 'import' command will archive
each successfully processed data file or data command output in a nearby
'data/' directory. The archive file name will be based on the rules
file and the data file's modification date and extension (or for a
data-generating command, the current date and the ".csv" extension).
The original data file, if any, will be removed.
* After successfully importing, 'import' will move the data file to
an archive directory ('data/' next to the rules file,
auto-created), renamed to
'RULESFILEBASENAME.DATAFILEMODDATE.DATAFILEEXT'. Archiving data
files is optional, but it can be useful for troubleshooting,
detecting variations in your banks' CSV data, regenerating entries
with improved rules, etc.
Also, in this mode 'import' will prefer the oldest file matched by
the 'source' rule's glob pattern, not the newest. (So if there are
multiple downloads, they will be imported and archived oldest first.)
* 'import' will pick the oldest of 'source' glob matches, rather than
the newest. So if you have multiple versions of a download,
repeated imports will process them in chronological order.
Archiving is optional, but it can be useful for troubleshooting your
CSV rules, regenerating entries with improved rules, checking for
variations in your bank's CSV, etc.
* For commands other than 'import', when the 'source' path or glob
pattern matches no files, hledger will try to read the latest
archived data file instead. This is convenient for working with
the downloaded data again, even after it has been imported.
_Added in 1.50; experimental._

File: hledger.info, Node: encoding, Next: separator, Prev: archive, Up: CSV
@ -5770,15 +5814,62 @@ File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top
10 Timeclock
************
The time logging format of timeclock.el, as read by hledger.
hledger can read time logs in the timeclock time logging format of
timeclock.el. As with Ledger, hledger's timeclock format is a
subset/variant of timeclock.el's.
hledger can read time logs in timeclock format. As with Ledger,
these are (a subset of) timeclock.el's format, containing clock-in and
clock-out entries as in the example below. The date is a simple date.
The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are
optional. The timezone, if present, must be four digits and is ignored
(currently the time is always interpreted as a local time). Lines
beginning with '#' or ';' or '*', and blank lines, are ignored.
hledger's timeclock format was updated in hledger 1.43 and 1.50. If
your old time logs are rejected, you should adapt them to modern
hledger; for now, you can restore the pre-1.43 behaviour with the
'--old-timeclock' flag.
Here the timeclock format in hledger 1.50+:
# Comment lines like these, and blank lines, are ignored:
# comment line
; comment line
* comment line
# Lines beginning with b, h, or capital O are also ignored, for compatibility:
b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
# Lines beginning with i or o are are clock-in / clock-out entries:
i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]]
o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT]
The date is a hledger simple date (YYYY-MM-DD or similar). The time
parts must use two digits. The seconds are optional. A + or -
four-digit time zone is accepted for compatibility, but currently
ignored; times are always interpreted as a local time.
In clock-in entries ('i'), the account name is required. A
transaction description, separated from the account name by 2+ spaces,
is optional. A transaction comment, beginning with ';', is also
optional. (Indented following comment lines are also allowed, as in
journal format.)
In clock-out entries ('o') have no description, but can have a
comment if you wish. A clock-in and clock-out pair form a "transaction"
posting some number of hours to an account - also known as a session.
Eg:
i 2015/03/30 09:00:00 session1
o 2015/03/30 10:00:00
$ hledger -f a.timeclock print
2015-03-30 * 09:00-10:00
(session1) 1.00h
Clock-ins and clock-outs are matched by their account/session name.
If a clock-out does not specify a name, the most recent unclosed
clock-in is closed. You can have multiple sessions active
simultaneously. Entries are processed in the order they are parsed.
Sessions spanning more than one day are automatically split at day
boundaries.
Eg, the following time log:
i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags:
o 2015/03/30 09:20:00
@ -5789,13 +5880,7 @@ i 2015/04/02 13:00:00 some account
o 2015/04/02 14:00:00
o 2015/04/02 15:00:00 another:account
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account. Entries are paired by the account
name if the same name is given for a clock-in/clock-out pair. If no
name is given for a clock-out, then it is paired with the most recent
clock-in entry. If the session spans more than one day, it is split
into several transactions, one for each day. For the above time log,
'hledger print' generates these journal entries:
generates these transactions:
$ hledger -f t.timeclock print
2015-03-30 * optional description after 2 spaces ; optional comment, tags:
@ -7694,16 +7779,14 @@ hledger uses "end" dates for valuation. More specifically:
* For single period reports (including normal print and register
reports):
* If an explicit report end date is specified, that is used
* Otherwise the latest transaction date or P directive date is
used (even if it's in the future)
* If an explicit report end date is specified, that is used.
* Otherwise the latest transaction date or non-future P
directive date is used.
* For multiperiod reports, each period is valued on its last day.
This can be customised with the -value option described below, which
can select either "then", "end", "now", or "custom" dates. (Note, this
has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key
always resets it to "end".)
can select either "then", "end", "now", or "custom" dates.

File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting
@ -13099,263 +13182,264 @@ Node: Other Ledger directives149795
Node: Other cost/lot notations150557
Node: CSV153398
Node: CSV rules cheatsheet155564
Node: source157591
Node: archive159012
Node: encoding160103
Node: separator161146
Node: skip161799
Node: date-format162449
Node: timezone163394
Node: newest-first164520
Node: intra-day-reversed165233
Node: decimal-mark165835
Node: fields list166315
Node: Field assignment168123
Node: Field names169342
Node: date field170674
Node: date2 field170838
Node: status field171033
Node: code field171223
Node: description field171411
Node: comment field171628
Node: account field172185
Node: amount field172903
Node: currency field175742
Node: balance field176150
Node: if block176673
Node: Matchers178200
Node: Multiple matchers180190
Node: Match groups180998
Node: if table181891
Node: balance-type183954
Node: include184781
Node: Working with CSV185350
Node: Rapid feedback185902
Node: Valid CSV186485
Node: File Extension187361
Node: Reading CSV from standard input188096
Node: Reading multiple CSV files188482
Node: Reading files specified by rule188958
Node: Valid transactions190355
Node: Deduplicating importing191180
Node: Setting amounts192409
Node: Amount signs194936
Node: Setting currency/commodity196001
Node: Amount decimal places197377
Node: Referencing other fields198634
Node: How CSV rules are evaluated199742
Node: Well factored rules202459
Node: CSV rules examples202949
Node: Bank of Ireland203147
Node: Coinbase204744
Node: Amazon205927
Node: Paypal207769
Node: Timeclock215519
Node: Timedot218344
Node: Timedot examples221821
Node: PART 3 REPORTING CONCEPTS224098
Node: Time periods224262
Node: Report start & end date224535
Node: Smart dates226011
Node: Report intervals228134
Node: Date adjustments228708
Node: Start date adjustment228928
Node: End date adjustment229831
Node: Period headings230612
Node: Period expressions231545
Node: Period expressions with a report interval233450
Node: More complex report intervals233898
Node: Multiple weekday intervals236014
Node: Depth237025
Node: Queries238863
Node: Query types241535
Node: acct query241910
Node: amt query242221
Node: code query242918
Node: cur query243113
Node: desc query243719
Node: date query243902
Node: date2 query244298
Node: depth query244589
Node: note query244925
Node: payee query245191
Node: real query245472
Node: status query245677
Node: type query245917
Node: tag query246450
Node: Negative queries247079
Node: not query247261
Node: Space-separated queries247548
Node: Boolean queries248236
Node: expr query249554
Node: any query250234
Node: all query250687
Node: Queries and command options251269
Node: Queries and account aliases251717
Node: Queries and valuation252042
Node: Pivoting252404
Node: Generating data254680
Node: Forecasting256480
Node: --forecast257136
Node: Inspecting forecast transactions258237
Node: Forecast reports259570
Node: Forecast tags260679
Node: Forecast period in detail261299
Node: Forecast troubleshooting262387
Node: Budgeting263458
Node: Amount formatting264018
Node: Commodity display style264262
Node: Rounding266103
Node: Trailing decimal marks266708
Node: Amount parseability267641
Node: Cost reporting269250
Node: Recording costs270081
Node: Reporting at cost271808
Node: Equity conversion postings272573
Node: Inferring equity conversion postings275218
Node: Combining costs and equity conversion postings276360
Node: Requirements for detecting equity conversion postings277585
Node: Infer cost and equity by default ?279107
Node: Value reporting279544
Node: -V Value280480
Node: -X Value in specified commodity280807
Node: Valuation date281157
Node: Finding market price282117
Node: --infer-market-prices market prices from transactions283497
Node: Valuation commodity286541
Node: --value Flexible valuation287974
Node: Valuation examples289817
Node: Interaction of valuation and queries291961
Node: Effect of valuation on reports292678
Node: PART 4 COMMANDS300576
Node: Help commands303365
Node: commands303551
Node: demo303759
Node: help304852
Node: User interface commands306557
Node: repl306768
Node: Examples309032
Node: run309590
Node: Examples 2312005
Node: ui313029
Node: web313166
Node: Data entry commands313294
Node: add313555
Node: add and balance assertions316129
Node: add and balance assignments316853
Node: import317414
Node: Import dry run318493
Node: Overlap detection319441
Node: First import322327
Node: Importing balance assignments323522
Node: Import and commodity styles324577
Node: Import archiving325011
Node: Import special cases325836
Node: Deduplication326054
Node: Varying file name326545
Node: Multiple versions326929
Node: Basic report commands328036
Node: accounts328337
Node: codes330983
Node: commodities332005
Node: descriptions332762
Node: files333222
Node: notes333519
Node: payees334031
Node: prices334943
Node: stats335835
Node: tags337576
Node: Standard report commands339113
Node: print339418
Node: print explicitness342232
Node: print amount style343152
Node: print parseability344390
Node: print other features345309
Node: print output format346270
Node: aregister349555
Node: aregister and posting dates354119
Node: register355020
Node: Custom register output362261
Node: balancesheet363446
Node: balancesheetequity368411
Node: cashflow373746
Node: incomestatement378559
Node: Advanced report commands383408
Node: balance383616
Node: balance features389037
Node: Simple balance report391140
Node: Balance report line format392950
Node: Filtered balance report395310
Node: List or tree mode395829
Node: Depth limiting397342
Node: Dropping top-level accounts398109
Node: Showing declared accounts398619
Node: Sorting by amount399349
Node: Percentages400203
Node: Multi-period balance report400910
Node: Balance change end balance403662
Node: Balance report modes405299
Node: Calculation mode405978
Node: Accumulation mode406682
Node: Valuation mode407783
Node: Combining balance report modes409127
Node: Budget report411157
Node: Using the budget report413457
Node: Budget date surprises415733
Node: Selecting budget goals417097
Node: Budgeting vs forecasting418045
Node: Balance report layout419722
Node: Wide layout420927
Node: Tall layout423332
Node: Bare layout424638
Node: Tidy layout426702
Node: Balance report output428246
Node: Some useful balance reports429020
Node: roi430280
Node: Spaces and special characters in --inv and --pnl432527
Node: Semantics of --inv and --pnl433253
Node: IRR and TWR explained435340
Node: Chart commands438751
Node: activity438932
Node: Data generation commands439429
Node: close439635
Node: close --clopen442198
Node: close --close444372
Node: close --open444896
Node: close --assert445146
Node: close --assign445473
Node: close --retain446152
Node: close customisation447009
Node: close and balance assertions448653
Node: close examples450175
Node: Retain earnings450412
Node: Migrate balances to a new file450915
Node: More detailed close examples452277
Node: rewrite452499
Node: Re-write rules in a file455059
Node: Diff output format456360
Node: rewrite vs print --auto457630
Node: Maintenance commands458344
Node: check458563
Node: Basic checks459645
Node: Strict checks460666
Node: Other checks461603
Node: Custom checks463355
Node: diff463810
Node: setup465018
Node: test467885
Node: PART 5 COMMON TASKS468788
Node: Getting help469021
Node: Constructing command lines469930
Node: Starting a journal file470775
Node: Setting LEDGER_FILE472159
Node: Setting opening balances473417
Node: Recording transactions476739
Node: Reconciling477464
Node: Reporting479853
Node: Migrating to a new file483967
Node: BUGS484416
Node: Troubleshooting485129
Node: source157663
Node: Data cleaning / generating commands159062
Node: archive160924
Node: encoding161852
Node: separator162895
Node: skip163548
Node: date-format164198
Node: timezone165143
Node: newest-first166269
Node: intra-day-reversed166982
Node: decimal-mark167584
Node: fields list168064
Node: Field assignment169872
Node: Field names171091
Node: date field172423
Node: date2 field172587
Node: status field172782
Node: code field172972
Node: description field173160
Node: comment field173377
Node: account field173934
Node: amount field174652
Node: currency field177491
Node: balance field177899
Node: if block178422
Node: Matchers179949
Node: Multiple matchers181939
Node: Match groups182747
Node: if table183640
Node: balance-type185703
Node: include186530
Node: Working with CSV187099
Node: Rapid feedback187651
Node: Valid CSV188234
Node: File Extension189110
Node: Reading CSV from standard input189845
Node: Reading multiple CSV files190231
Node: Reading files specified by rule190707
Node: Valid transactions192104
Node: Deduplicating importing192929
Node: Setting amounts194158
Node: Amount signs196685
Node: Setting currency/commodity197750
Node: Amount decimal places199126
Node: Referencing other fields200383
Node: How CSV rules are evaluated201491
Node: Well factored rules204208
Node: CSV rules examples204698
Node: Bank of Ireland204896
Node: Coinbase206493
Node: Amazon207676
Node: Paypal209518
Node: Timeclock217268
Node: Timedot221321
Node: Timedot examples224798
Node: PART 3 REPORTING CONCEPTS227075
Node: Time periods227239
Node: Report start & end date227512
Node: Smart dates228988
Node: Report intervals231111
Node: Date adjustments231685
Node: Start date adjustment231905
Node: End date adjustment232808
Node: Period headings233589
Node: Period expressions234522
Node: Period expressions with a report interval236427
Node: More complex report intervals236875
Node: Multiple weekday intervals238991
Node: Depth240002
Node: Queries241840
Node: Query types244512
Node: acct query244887
Node: amt query245198
Node: code query245895
Node: cur query246090
Node: desc query246696
Node: date query246879
Node: date2 query247275
Node: depth query247566
Node: note query247902
Node: payee query248168
Node: real query248449
Node: status query248654
Node: type query248894
Node: tag query249427
Node: Negative queries250056
Node: not query250238
Node: Space-separated queries250525
Node: Boolean queries251213
Node: expr query252531
Node: any query253211
Node: all query253664
Node: Queries and command options254246
Node: Queries and account aliases254694
Node: Queries and valuation255019
Node: Pivoting255381
Node: Generating data257657
Node: Forecasting259457
Node: --forecast260113
Node: Inspecting forecast transactions261214
Node: Forecast reports262547
Node: Forecast tags263656
Node: Forecast period in detail264276
Node: Forecast troubleshooting265364
Node: Budgeting266435
Node: Amount formatting266995
Node: Commodity display style267239
Node: Rounding269080
Node: Trailing decimal marks269685
Node: Amount parseability270618
Node: Cost reporting272227
Node: Recording costs273058
Node: Reporting at cost274785
Node: Equity conversion postings275550
Node: Inferring equity conversion postings278195
Node: Combining costs and equity conversion postings279337
Node: Requirements for detecting equity conversion postings280562
Node: Infer cost and equity by default ?282084
Node: Value reporting282521
Node: -V Value283457
Node: -X Value in specified commodity283784
Node: Valuation date284134
Node: Finding market price284967
Node: --infer-market-prices market prices from transactions286347
Node: Valuation commodity289391
Node: --value Flexible valuation290824
Node: Valuation examples292667
Node: Interaction of valuation and queries294811
Node: Effect of valuation on reports295528
Node: PART 4 COMMANDS303426
Node: Help commands306215
Node: commands306401
Node: demo306609
Node: help307702
Node: User interface commands309407
Node: repl309618
Node: Examples311882
Node: run312440
Node: Examples 2314855
Node: ui315879
Node: web316016
Node: Data entry commands316144
Node: add316405
Node: add and balance assertions318979
Node: add and balance assignments319703
Node: import320264
Node: Import dry run321343
Node: Overlap detection322291
Node: First import325177
Node: Importing balance assignments326372
Node: Import and commodity styles327427
Node: Import archiving327861
Node: Import special cases328686
Node: Deduplication328904
Node: Varying file name329395
Node: Multiple versions329779
Node: Basic report commands330886
Node: accounts331187
Node: codes333833
Node: commodities334855
Node: descriptions335612
Node: files336072
Node: notes336369
Node: payees336881
Node: prices337793
Node: stats338685
Node: tags340426
Node: Standard report commands341963
Node: print342268
Node: print explicitness345082
Node: print amount style346002
Node: print parseability347240
Node: print other features348159
Node: print output format349120
Node: aregister352405
Node: aregister and posting dates356969
Node: register357870
Node: Custom register output365111
Node: balancesheet366296
Node: balancesheetequity371261
Node: cashflow376596
Node: incomestatement381409
Node: Advanced report commands386258
Node: balance386466
Node: balance features391887
Node: Simple balance report393990
Node: Balance report line format395800
Node: Filtered balance report398160
Node: List or tree mode398679
Node: Depth limiting400192
Node: Dropping top-level accounts400959
Node: Showing declared accounts401469
Node: Sorting by amount402199
Node: Percentages403053
Node: Multi-period balance report403760
Node: Balance change end balance406512
Node: Balance report modes408149
Node: Calculation mode408828
Node: Accumulation mode409532
Node: Valuation mode410633
Node: Combining balance report modes411977
Node: Budget report414007
Node: Using the budget report416307
Node: Budget date surprises418583
Node: Selecting budget goals419947
Node: Budgeting vs forecasting420895
Node: Balance report layout422572
Node: Wide layout423777
Node: Tall layout426182
Node: Bare layout427488
Node: Tidy layout429552
Node: Balance report output431096
Node: Some useful balance reports431870
Node: roi433130
Node: Spaces and special characters in --inv and --pnl435377
Node: Semantics of --inv and --pnl436103
Node: IRR and TWR explained438190
Node: Chart commands441601
Node: activity441782
Node: Data generation commands442279
Node: close442485
Node: close --clopen445048
Node: close --close447222
Node: close --open447746
Node: close --assert447996
Node: close --assign448323
Node: close --retain449002
Node: close customisation449859
Node: close and balance assertions451503
Node: close examples453025
Node: Retain earnings453262
Node: Migrate balances to a new file453765
Node: More detailed close examples455127
Node: rewrite455349
Node: Re-write rules in a file457909
Node: Diff output format459210
Node: rewrite vs print --auto460480
Node: Maintenance commands461194
Node: check461413
Node: Basic checks462495
Node: Strict checks463516
Node: Other checks464453
Node: Custom checks466205
Node: diff466660
Node: setup467868
Node: test470735
Node: PART 5 COMMON TASKS471638
Node: Getting help471871
Node: Constructing command lines472780
Node: Starting a journal file473625
Node: Setting LEDGER_FILE475009
Node: Setting opening balances476267
Node: Recording transactions479589
Node: Reconciling480314
Node: Reporting482703
Node: Migrating to a new file486817
Node: BUGS487266
Node: Troubleshooting487979

End Tag Table

149
hledger/hledger.txt
View File

@ -16,7 +16,7 @@ DESCRIPTION
and largely compatible with ledger(1), and largely interconvertible
with beancount(1).
This manual is for hledger's command line interface, version 1.43.99.
This manual is for hledger's command line interface, version 1.50.99.
It also describes the common options, file formats and concepts used by
all hledger programs. It might accidentally teach you some bookkeep-
ing/accounting as well! You don't need to know everything in here to
@ -3254,6 +3254,7 @@ CSV
source optionally declare which file to read data
from
archive optionally enable an archive of imported files
encoding optionally declare which text encoding the
data has
separator declare the field separator, instead of rely-
@ -3318,27 +3319,61 @@ CSV
See also "Working with CSV > Reading files specified by rule".
The archive rule adds a few more features to source; see below.
Data cleaning / generating commands
After source's file pattern, you can write | (pipe) and a data cleaning
command. If hledger's CSV rules aren't enough, you can pre-process the
downloaded data here with a shell command or script, to make it more
suitable for conversion. The command will be executed by your default
shell, in the directory of the rules file, will receive the data file's
content as standard input, and should output zero or more lines of
character-separated-values, suitable for conversion by the CSV rules.
Examples:
source ./paypal.json | paypalcsv
source data/simplefin.json | simplefincsv - 'chase.*card'
source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2
source History_for_Account_Z20144832*.csv # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g'
Or, after source you can write | and a data generating command (with no
file pattern before the |). This command receives no input, and should
output zero or more lines of character-separated values, suitable for
conversion by the CSV rules.
Examples:
source | paypaljson | paypalcsv
source | paypalcsv data/paypal.json
source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card'
source | simplefincsv data/simplefin.json 'unify.*checking'
(paypal* and simplefin* scripts are in bin/)
Whenever hledger runs one of these commands, it will echo the command
on stderr. If the command produces error output, but exits success-
fully, hledger will show the error output as a warning. If the command
fails, hledger will fail and show the error output in the error mes-
sage.
Added in 1.50; experimental.
archive
Adding the archive rule to your rules file affects importing or reading
files specified by source:
With archive added to a rules file, the import command will archive
each successfully processed data file or data command output in a
nearby data/ directory. The archive file name will be based on the
rules file and the data file's modification date and extension (or for
a data-generating command, the current date and the ".csv" extension).
The original data file, if any, will be removed.
o After successfully importing, import will move the data file to an
archive directory (data/ next to the rules file, auto-created), re-
named to RULESFILEBASENAME.DATAFILEMODDATE.DATAFILEEXT. Archiving
data files is optional, but it can be useful for troubleshooting, de-
tecting variations in your banks' CSV data, regenerating entries with
improved rules, etc.
Also, in this mode import will prefer the oldest file matched by the
source rule's glob pattern, not the newest. (So if there are multiple
downloads, they will be imported and archived oldest first.)
o import will pick the oldest of source glob matches, rather than the
newest. So if you have multiple versions of a download, repeated im-
ports will process them in chronological order.
Archiving is optional, but it can be useful for troubleshooting your
CSV rules, regenerating entries with improved rules, checking for vari-
ations in your bank's CSV, etc.
o For commands other than import, when the source path or glob pattern
matches no files, hledger will try to read the latest archived data
file instead. This is convenient for working with the downloaded
data again, even after it has been imported.
Added in 1.50; experimental.
encoding
encoding ENCODING
@ -4574,15 +4609,59 @@ CSV
expenses:banking:paypal $0.59 ; business:
Timeclock
The time logging format of timeclock.el, as read by hledger.
hledger can read time logs in the timeclock time logging format of
timeclock.el. As with Ledger, hledger's timeclock format is a sub-
set/variant of timeclock.el's.
hledger can read time logs in timeclock format. As with Ledger, these
are (a subset of) timeclock.el's format, containing clock-in and
clock-out entries as in the example below. The date is a simple date.
The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op-
tional. The timezone, if present, must be four digits and is ignored
(currently the time is always interpreted as a local time). Lines be-
ginning with # or ; or *, and blank lines, are ignored.
hledger's timeclock format was updated in hledger 1.43 and 1.50. If
your old time logs are rejected, you should adapt them to modern
hledger; for now, you can restore the pre-1.43 behaviour with the
--old-timeclock flag.
Here the timeclock format in hledger 1.50+:
# Comment lines like these, and blank lines, are ignored:
# comment line
; comment line
* comment line
# Lines beginning with b, h, or capital O are also ignored, for compatibility:
b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
# Lines beginning with i or o are are clock-in / clock-out entries:
i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]]
o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT]
The date is a hledger simple date (YYYY-MM-DD or similar). The time
parts must use two digits. The seconds are optional. A + or -
four-digit time zone is accepted for compatibility, but currently ig-
nored; times are always interpreted as a local time.
In clock-in entries (i), the account name is required. A transaction
description, separated from the account name by 2+ spaces, is optional.
A transaction comment, beginning with ;, is also optional. (Indented
following comment lines are also allowed, as in journal format.)
In clock-out entries (o) have no description, but can have a comment if
you wish. A clock-in and clock-out pair form a "transaction" posting
some number of hours to an account - also known as a session. Eg:
i 2015/03/30 09:00:00 session1
o 2015/03/30 10:00:00
$ hledger -f a.timeclock print
2015-03-30 * 09:00-10:00
(session1) 1.00h
Clock-ins and clock-outs are matched by their account/session name. If
a clock-out does not specify a name, the most recent unclosed clock-in
is closed. You can have multiple sessions active simultaneously. En-
tries are processed in the order they are parsed. Sessions spanning
more than one day are automatically split at day boundaries.
Eg, the following time log:
i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags:
o 2015/03/30 09:20:00
@ -4593,13 +4672,7 @@ Timeclock
o 2015/04/02 14:00:00
o 2015/04/02 15:00:00 another:account
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account. Entries are paired by the account
name if the same name is given for a clock-in/clock-out pair. If no
name is given for a clock-out, then it is paired with the most recent
clock-in entry. If the session spans more than one day, it is split
into several transactions, one for each day. For the above time log,
hledger print generates these journal entries:
generates these transactions:
$ hledger -f t.timeclock print
2015-03-30 * optional description after 2 spaces ; optional comment, tags:
@ -6101,17 +6174,15 @@ Value reporting
o For single period reports (including normal print and register re-
ports):
o If an explicit report end date is specified, that is used
o If an explicit report end date is specified, that is used.
o Otherwise the latest transaction date or P directive date is used
(even if it's in the future)
o Otherwise the latest transaction date or non-future P directive
date is used.
o For multiperiod reports, each period is valued on its last day.
This can be customised with the --value option described below, which
can select either "then", "end", "now", or "custom" dates. (Note, this
has a bug in hledger-ui <=1.31: turning on valuation with the V key al-
ways resets it to "end".)
can select either "then", "end", "now", or "custom" dates.
Finding market price
To convert a commodity A to its market value in another commodity B,
@ -10614,4 +10685,4 @@ LICENSE
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.43.99 June 2025 HLEDGER(1)
hledger-1.50.99 September 2025 HLEDGER(1)