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

bal/etc.: document html output, move to options section

Browse Source
This commit is contained in:
Simon Michael 2018-01-23 17:08:19 -08:00
parent 37555617b7
commit e657e96591
6 changed files with 367 additions and 350 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
hledger/hledger.1
View File

@ -987,6 +987,33 @@ directives, not transaction prices (unlike Ledger).
Using \-B/\[en]cost and \-V/\[en]value together is currently allowed,
but the results are probably not meaningful.
Let us know if you find a use for this.
.SS Output destination
.PP
Some commands (print, register, stats, the balance commands) can write
their output to a destination other than the console.
This is controlled by the \f[C]\-o/\-\-output\-file\f[] option.
.IP
.nf
\f[C]
$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default)
$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE
\f[]
.fi
.SS Output format
.PP
Some commands can write their output in other formats.
Eg print and register can output CSV, and the balance commands can
output CSV or HTML.
This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with
\f[C]\-o/\-\-output\-file\f[].
.IP
.nf
\f[C]
$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout
$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv
\f[]
.fi
.SS Regular expressions
.PP
hledger uses regular expressions in a number of places:
@ -1448,7 +1475,7 @@ in single\-column balance reports: use this custom line format
.TP
.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[]
select the output format.
Supported formats: txt, csv.
Supported formats: txt, csv, html.
.RS
.RE
.TP
@ -1798,8 +1825,8 @@ Balance\ changes\ in\ 2017/11/01\-2017/12/31:
For more examples and details, see Budgeting and Forecasting.
.SS Custom balance output
.PP
In simple (non\-multi\-column) balance reports, you can customise the
output with \f[C]\-\-format\ FMT\f[]:
You can customise the layout of simple (non\-tabular) balance reports
with \f[C]\-\-format\ FMT\f[]:
.IP
.nf
\f[C]
@ -1867,6 +1894,8 @@ rendered on one line
.IP \[bu] 2
\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
format for the single\-column balance report
.PP
This command also supports output destination and output formats.
.SS Colour support
.PP
The balance command shows negative amounts in red, if:
@ -1874,33 +1903,6 @@ The balance command shows negative amounts in red, if:
the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
.IP \[bu] 2
the output is not being redirected or piped anywhere
.SS Output destination
.PP
The balance, print, register and stats commands can write their output
to a destination other than the console.
This is controlled by the \f[C]\-o/\-\-output\-file\f[] option.
.IP
.nf
\f[C]
$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default)
$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE
\f[]
.fi
.SS CSV output
.PP
The balance, print and register commands can write their output as CSV.
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet.
This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by
specifying a \f[C]\&.csv\f[] file extension with
\f[C]\-o/\-\-output\-file\f[].
.IP
.nf
\f[C]
$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout
$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv
\f[]
.fi
.SS balancesheet
.PP
This command displays a simple balance sheet, showing historical ending
@ -2011,6 +2013,8 @@ As with multicolumn balance reports, you can alter the report mode with
Normally balancesheet shows historical ending balances, which is what
you need for a balance sheet; note this means it ignores report begin
dates.
.PP
This command also supports output destination and output formats.
.SS balancesheetequity
.PP
Just like balancesheet, but also reports Equity (which it assumes is
@ -2146,6 +2150,8 @@ report period.
Normally cashflow shows changes in assets per period, though as with
multicolumn balance reports you can alter the report mode with
\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[].
.PP
This command also supports output destination and output formats.
.SS check\-dates
.PP
Check that transactions are sorted by increasing date.
@ -2343,6 +2349,8 @@ report period.
Normally incomestatement shows revenues/expenses per period, though as
with multicolumn balance reports you can alter the report mode with
\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[].
.PP
This command also supports output destination and output formats.
.SS prices
.PP
Print all market prices from the journal.
@ -2455,7 +2463,7 @@ increasing dates, and that transactions on the same day do not get
reordered.
See also the import command.
.PP
The print command also supports output destination and CSV output.
This command also supports output destination and output formats.
Here's an example of print's CSV output:
.IP
.nf
@ -2667,9 +2675,7 @@ $\ hledger\ reg\ \-w\ $COLUMNS,40\ \ \ \ \ \ #\ use\ terminal\ width,\ and\ set\
\f[]
.fi
.PP
The register command also supports the \f[C]\-o/\-\-output\-file\f[] and
\f[C]\-O/\-\-output\-format\f[] options for controlling output
destination and CSV output.
This command also supports output destination and output formats.
.SS register\-match
.PP
Print the one posting whose transaction description is closest to DESC,
@ -2708,8 +2714,7 @@ The stats command displays summary information for the whole journal, or
a matched part of it.
With a reporting interval, it shows a report for each report period.
.PP
The stats command also supports \f[C]\-o/\-\-output\-file\f[] for
controlling output destination.
This command also supports output destination and output formats.
.SS tags
.PP
List all the tag names used in the journal.

282
hledger/hledger.info
View File

@ -681,6 +681,37 @@ File: hledger.info, Node: Combining -B and -V, Next: Regular expressions, Pre
Using -B/-cost and -V/-value together is currently allowed, but the
results are probably not meaningful. Let us know if you find a use for
this.
* Menu:
* Output destination::
* Output format::

File: hledger.info, Node: Output destination, Next: Output format, Up: Combining -B and -V
2.15.1 Output destination
-------------------------
Some commands (print, register, stats, the balance commands) can write
their output to a destination other than the console. This is
controlled by the '-o/--output-file' option.
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE

File: hledger.info, Node: Output format, Prev: Output destination, Up: Combining -B and -V
2.15.2 Output format
--------------------
Some commands can write their output in other formats. Eg print and
register can output CSV, and the balance commands can output CSV or
HTML. This is controlled by the '-O/--output-format' option, or by
specifying a '.csv' or '.html' file extension with '-o/--output-file'.
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv

File: hledger.info, Node: Regular expressions, Prev: Combining -B and -V, Up: OPTIONS
@ -1084,7 +1115,7 @@ Show accounts and their balances. Aliases: b, bal.
in single-column balance reports: use this custom line format
'-O FMT --output-format=FMT'
select the output format. Supported formats: txt, csv.
select the output format. Supported formats: txt, csv, html.
'-o FILE --output-file=FILE'
write output to FILE. A file extension matching one of the above
@ -1159,8 +1190,6 @@ $ hledger balance -p 2008/6 expenses --no-total
* Budgets::
* Custom balance output::
* Colour support::
* Output destination::
* CSV output::

File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance
@ -1393,8 +1422,8 @@ File: hledger.info, Node: Custom balance output, Next: Colour support, Prev:
4.4.5 Custom balance output
---------------------------
In simple (non-multi-column) balance reports, you can customise the
output with '--format FMT':
You can customise the layout of simple (non-tabular) balance reports
with '--format FMT':
$ hledger balance --format "%20(account) %12(total)"
assets $-1
@ -1447,8 +1476,10 @@ may be needed to get pleasing results.
* '%20(total) %2(depth_spacer)%-(account)' - the default format for
the single-column balance report
This command also supports output destination and output formats.

File: hledger.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance
File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance
4.4.6 Colour support
--------------------
@ -1458,34 +1489,6 @@ The balance command shows negative amounts in red, if:
* the 'TERM' environment variable is not set to 'dumb'
* the output is not being redirected or piped anywhere

File: hledger.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance
4.4.7 Output destination
------------------------
The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the
'-o/--output-file' option.
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE

File: hledger.info, Node: CSV output, Prev: Output destination, Up: balance
4.4.8 CSV output
----------------
The balance, print and register commands can write their output as CSV.
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the '-O/--output-format'
option, or by specifying a '.csv' file extension with
'-o/--output-file'.
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv

File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
@ -1569,6 +1572,8 @@ the report mode with '--change'/'--cumulative'/'--historical'. Normally
balancesheet shows historical ending balances, which is what you need
for a balance sheet; note this means it ignores report begin dates.
This command also supports output destination and output formats.

File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS
@ -1679,6 +1684,8 @@ each report period. Normally cashflow shows changes in assets per
period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'.
This command also supports output destination and output formats.

File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS
@ -1856,6 +1863,8 @@ each report period. Normally incomestatement shows revenues/expenses
per period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'.
This command also supports output destination and output formats.

File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS
@ -1951,7 +1960,7 @@ $ hledger -f bank1.csv print --new
increasing dates, and that transactions on the same day do not get
reordered. See also the import command.
The print command also supports output destination and CSV output.
This command also supports output destination and output formats.
Here's an example of print's CSV output:
$ hledger print -Ocsv
@ -2122,9 +2131,7 @@ $ export COLUMNS=100; hledger reg # set till session end (or window resize)
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
The register command also supports the '-o/--output-file' and
'-O/--output-format' options for controlling output destination and CSV
output.
This command also supports output destination and output formats.

File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS
@ -2173,8 +2180,7 @@ Commodities : 1 ($)
or a matched part of it. With a reporting interval, it shows a report
for each report period.
The stats command also supports '-o/--output-file' for controlling
output destination.
This command also supports output destination and output formats.

File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS
@ -2418,103 +2424,103 @@ Node: Market value21197
Ref: #market-value21332
Node: Combining -B and -V22515
Ref: #combining--b-and--v22679
Node: Regular expressions22826
Ref: #regular-expressions22969
Node: QUERIES24330
Ref: #queries24432
Node: COMMANDS28399
Ref: #commands28511
Node: accounts29493
Ref: #accounts29591
Node: activity30837
Ref: #activity30947
Node: add31307
Ref: #add31406
Node: balance34067
Ref: #balance34178
Node: Flat mode37658
Ref: #flat-mode37783
Node: Depth limited balance reports38203
Ref: #depth-limited-balance-reports38404
Node: Multicolumn balance reports38824
Ref: #multicolumn-balance-reports39019
Node: Budgets43708
Ref: #budgets43855
Node: Custom balance output47686
Ref: #custom-balance-output47848
Node: Colour support49941
Ref: #colour-support50100
Node: Output destination50273
Ref: #output-destination50429
Node: CSV output50699
Ref: #csv-output50816
Node: balancesheet51213
Ref: #balancesheet51349
Node: balancesheetequity53581
Ref: #balancesheetequity53730
Node: cashflow54267
Ref: #cashflow54395
Node: check-dates56439
Ref: #check-dates56566
Node: check-dupes56683
Ref: #check-dupes56807
Node: close56944
Ref: #close57051
Node: help57381
Ref: #help57481
Node: import58555
Ref: #import58669
Node: incomestatement59399
Ref: #incomestatement59533
Node: prices61858
Ref: #prices61973
Node: print62016
Ref: #print62126
Node: print-unique67011
Ref: #print-unique67137
Node: register67205
Ref: #register67332
Node: Custom register output71833
Ref: #custom-register-output71962
Node: register-match73259
Ref: #register-match73393
Node: rewrite73576
Ref: #rewrite73693
Node: stats73762
Ref: #stats73865
Node: tags74747
Ref: #tags74845
Node: test75081
Ref: #test75165
Node: ADD-ON COMMANDS75533
Ref: #add-on-commands75643
Node: Official add-ons76930
Ref: #official-add-ons77070
Node: api77157
Ref: #api77246
Node: ui77298
Ref: #ui77397
Node: web77455
Ref: #web77544
Node: Third party add-ons77590
Ref: #third-party-add-ons77765
Node: diff77900
Ref: #diff77997
Node: iadd78096
Ref: #iadd78210
Node: interest78293
Ref: #interest78414
Node: irr78509
Ref: #irr78607
Node: Experimental add-ons78685
Ref: #experimental-add-ons78837
Node: autosync79128
Ref: #autosync79240
Node: budget79479
Ref: #budget79601
Node: chart79667
Ref: #chart79784
Node: check79855
Ref: #check79957
Node: Output destination22876
Ref: #output-destination23026
Node: Output format23309
Ref: #output-format23449
Node: Regular expressions23834
Ref: #regular-expressions23977
Node: QUERIES25338
Ref: #queries25440
Node: COMMANDS29407
Ref: #commands29519
Node: accounts30501
Ref: #accounts30599
Node: activity31845
Ref: #activity31955
Node: add32315
Ref: #add32414
Node: balance35075
Ref: #balance35186
Node: Flat mode38634
Ref: #flat-mode38759
Node: Depth limited balance reports39179
Ref: #depth-limited-balance-reports39380
Node: Multicolumn balance reports39800
Ref: #multicolumn-balance-reports39995
Node: Budgets44684
Ref: #budgets44831
Node: Custom balance output48662
Ref: #custom-balance-output48824
Node: Colour support50981
Ref: #colour-support51113
Node: balancesheet51286
Ref: #balancesheet51422
Node: balancesheetequity53724
Ref: #balancesheetequity53873
Node: cashflow54410
Ref: #cashflow54538
Node: check-dates56652
Ref: #check-dates56779
Node: check-dupes56896
Ref: #check-dupes57020
Node: close57157
Ref: #close57264
Node: help57594
Ref: #help57694
Node: import58768
Ref: #import58882
Node: incomestatement59612
Ref: #incomestatement59746
Node: prices62141
Ref: #prices62256
Node: print62299
Ref: #print62409
Node: print-unique67293
Ref: #print-unique67419
Node: register67487
Ref: #register67614
Node: Custom register output72115
Ref: #custom-register-output72244
Node: register-match73465
Ref: #register-match73599
Node: rewrite73782
Ref: #rewrite73899
Node: stats73968
Ref: #stats74071
Node: tags74932
Ref: #tags75030
Node: test75266
Ref: #test75350
Node: ADD-ON COMMANDS75718
Ref: #add-on-commands75828
Node: Official add-ons77115
Ref: #official-add-ons77255
Node: api77342
Ref: #api77431
Node: ui77483
Ref: #ui77582
Node: web77640
Ref: #web77729
Node: Third party add-ons77775
Ref: #third-party-add-ons77950
Node: diff78085
Ref: #diff78182
Node: iadd78281
Ref: #iadd78395
Node: interest78478
Ref: #interest78599
Node: irr78694
Ref: #irr78792
Node: Experimental add-ons78870
Ref: #experimental-add-ons79022
Node: autosync79313
Ref: #autosync79425
Node: budget79664
Ref: #budget79786
Node: chart79852
Ref: #chart79969
Node: check80040
Ref: #check80142

End Tag Table

288
hledger/hledger.txt
View File

@ -635,59 +635,76 @@ OPTIONS
results are probably not meaningful. Let us know if you find a use for
this.
Output destination
Some commands (print, register, stats, the balance commands) can write
their output to a destination other than the console. This is con-
trolled by the -o/--output-file option.
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
Output format
Some commands can write their output in other formats. Eg print and
register can output CSV, and the balance commands can output CSV or
HTML. This is controlled by the -O/--output-format option, or by spec-
ifying a .csv or .html file extension with -o/--output-file.
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
Regular expressions
hledger uses regular expressions in a number of places:
o query terms, on the command line and in the hledger-web search form:
o query terms, on the command line and in the hledger-web search form:
REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
o CSV rules conditional blocks: if REGEX ...
o account alias directives and options: alias /REGEX/ = REPLACEMENT,
o account alias directives and options: alias /REGEX/ = REPLACEMENT,
--alias /REGEX/=REPLACEMENT
hledger's regular expressions come from the regex-tdfa library. In
hledger's regular expressions come from the regex-tdfa library. In
general they:
o are case insensitive
o are infix matching (do not need to match the entire thing being
o are infix matching (do not need to match the entire thing being
matched)
o are POSIX extended regular expressions
o also support GNU word boundaries (\<, \>, \b, \B)
o and parenthesised capturing groups and numeric backreferences in
o and parenthesised capturing groups and numeric backreferences in
replacement strings
o do not support mode modifiers like (?s)
Some things to note:
o In the alias directive and --alias option, regular expressions must
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
o In the alias directive and --alias option, regular expressions must
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
these are not required.
o In queries, to match a regular expression metacharacter like $ as a
literal character, prepend a backslash. Eg to search for amounts
o In queries, to match a regular expression metacharacter like $ as a
literal character, prepend a backslash. Eg to search for amounts
with the dollar sign in hledger-web, write cur:\$.
o On the command line, some metacharacters like $ have a special mean-
o On the command line, some metacharacters like $ have a special mean-
ing to the shell and so must be escaped at least once more. See Spe-
cial characters.
QUERIES
One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres-
sion, written as arguments after the command name, to filter the data
by date, account name or other criteria. The syntax is similar to a
One of hledger's strengths is being able to quickly report on precise
subsets of your data. Most commands accept an optional query expres-
sion, written as arguments after the command name, to filter the data
by date, account name or other criteria. The syntax is similar to a
web search: one or more space-separated search terms, quotes to enclose
whitespace, prefixes to match specific fields, a not: prefix to negate
whitespace, prefixes to match specific fields, a not: prefix to negate
the match.
We do not yet support arbitrary boolean combinations of search terms;
instead most commands show transactions/postings/accounts which match
We do not yet support arbitrary boolean combinations of search terms;
instead most commands show transactions/postings/accounts which match
(or negatively match):
o any of the description terms AND
@ -708,32 +725,32 @@ QUERIES
o match all the other terms.
The following kinds of search terms can be used. Remember these can
The following kinds of search terms can be used. Remember these can
also be prefixed with not:, eg to exclude a particular subaccount.
REGEX match account names by this regular expression. (No prefix is
REGEX match account names by this regular expression. (No prefix is
equivalent to acct:).
acct:REGEX
same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
match postings with a single-commodity amount that is equal to,
less than, or greater than N. (Multi-commodity amounts are not
match postings with a single-commodity amount that is equal to,
less than, or greater than N. (Multi-commodity amounts are not
tested, and will always match.) The comparison has two modes: if
N is preceded by a + or - sign (or is 0), the two signed numbers
are compared. Otherwise, the absolute magnitudes are compared,
are compared. Otherwise, the absolute magnitudes are compared,
ignoring sign.
code:REGEX
match by transaction code (eg check number)
cur:REGEX
match postings or transactions including any amounts whose cur-
rency/commodity symbol is fully matched by REGEX. (For a par-
match postings or transactions including any amounts whose cur-
rency/commodity symbol is fully matched by REGEX. (For a par-
tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend
\. And when using the command line you need to add one more
\. And when using the command line you need to add one more
level of quoting to hide it from the shell, so eg do:
hledger print cur:'\$' or hledger print cur:\\$.
@ -742,20 +759,20 @@ QUERIES
date:PERIODEXPR
match dates within the specified period. PERIODEXPR is a period
expression (with no report interval). Examples: date:2016,
date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
--date2 command line flag is present, this matches secondary
expression (with no report interval). Examples: date:2016,
date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
--date2 command line flag is present, this matches secondary
dates instead.
date2:PERIODEXPR
match secondary dates within the specified period.
depth:N
match (or display, depending on command) accounts at or above
match (or display, depending on command) accounts at or above
this depth
note:REGEX
match transaction notes (part of description right of |, or
match transaction notes (part of description right of |, or
whole description when there's no |)
payee:REGEX
@ -769,38 +786,38 @@ QUERIES
match unmarked, pending, or cleared transactions respectively
tag:REGEX[=REGEX]
match by tag name, and optionally also by tag value. Note a
tag: query is considered to match a transaction if it matches
any of the postings. Also remember that postings inherit the
match by tag name, and optionally also by tag value. Note a
tag: query is considered to match a transaction if it matches
any of the postings. Also remember that postings inherit the
tags of their parent transaction.
The following special search term is used automatically in hledger-web,
only:
inacct:ACCTNAME
tells hledger-web to show the transaction register for this
tells hledger-web to show the transaction register for this
account. Can be filtered further with acct etc.
Some of these can also be expressed as command-line options (eg depth:2
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
is equivalent to --depth 2). Generally you can mix options and query
arguments, and the resulting query will be their intersection (perhaps
excluding the -p/--period option).
COMMANDS
hledger provides a number of subcommands; hledger with no arguments
hledger provides a number of subcommands; hledger with no arguments
shows a list.
If you install additional hledger-* packages, or if you put programs or
scripts named hledger-NAME in your PATH, these will also be listed as
scripts named hledger-NAME in your PATH, these will also be listed as
subcommands.
Run a subcommand by writing its name as first argument (eg
Run a subcommand by writing its name as first argument (eg
hledger incomestatement). You can also write one of the standard short
aliases displayed in parentheses in the command list (hledger b), or
aliases displayed in parentheses in the command list (hledger b), or
any any unambiguous prefix of a command name (hledger inc).
Here are all the builtin commands in alphabetical order. See also
hledger for a more organised command list, and hledger CMD -h for
Here are all the builtin commands in alphabetical order. See also
hledger for a more organised command list, and hledger CMD -h for
detailed command help.
accounts
@ -818,12 +835,12 @@ COMMANDS
--drop=N
in flat mode: omit N leading account name parts
This command lists account names, either declared with account direc-
tives (-declared), posted to (-used), or both (default). With query
arguments, only matched account names and account names referenced by
matched postings are shown. It shows a flat list by default. With
--tree, it uses indentation to show the account hierarchy. In flat
mode you can add --drop N to omit the first few account name compo-
This command lists account names, either declared with account direc-
tives (-declared), posted to (-used), or both (default). With query
arguments, only matched account names and account names referenced by
matched postings are shown. It shows a flat list by default. With
--tree, it uses indentation to show the account hierarchy. In flat
mode you can add --drop N to omit the first few account name compo-
nents. Account names can be depth-clipped with --depth N or depth:N.
Examples:
@ -866,8 +883,8 @@ COMMANDS
activity
Show an ascii barchart of posting counts per interval.
The activity command displays an ascii histogram showing transaction
counts by day, week, month or other reporting interval (by day is the
The activity command displays an ascii histogram showing transaction
counts by day, week, month or other reporting interval (by day is the
default). With query arguments, it counts only matched transactions.
$ hledger activity --quarterly
@ -880,24 +897,24 @@ COMMANDS
Prompt for transactions and add them to the journal.
--no-new-accounts
don't allow creating new accounts; helps prevent typos when
don't allow creating new accounts; helps prevent typos when
entering account names
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (if there are multiple
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (if there are multiple
-f FILE options, the first file is used.) Existing transactions are not
changed. This is the only hledger command that writes to the journal
changed. This is the only hledger command that writes to the journal
file.
To use it, just run hledger add and follow the prompts. You can add as
many transactions as you like; when you are finished, enter . or press
many transactions as you like; when you are finished, enter . or press
control-d or control-c to exit.
Features:
o add tries to provide useful defaults, using the most similar recent
o add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
o You can also set the initial defaults with command line arguments.
@ -905,20 +922,20 @@ COMMANDS
o Readline-style edit keys can be used during data entry.
o The tab key will auto-complete whenever possible - accounts, descrip-
tions, dates (yesterday, today, tomorrow). If the input area is
tions, dates (yesterday, today, tomorrow). If the input area is
empty, it will insert the default value.
o If the journal defines a default commodity, it will be added to any
o If the journal defines a default commodity, it will be added to any
bare numbers entered.
o A parenthesised transaction code may be entered following a date.
o Comments and tags may be entered following a description or amount.
o If you make a mistake, enter < at any prompt to restart the transac-
o If you make a mistake, enter < at any prompt to restart the transac-
tion.
o Input prompts are displayed in a different colour when the terminal
o Input prompts are displayed in a different colour when the terminal
supports it.
Example (see the tutorial for a detailed explanation):
@ -955,7 +972,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
show balance change accumulated across periods (in multicolumn
show balance change accumulated across periods (in multicolumn
reports)
-H --historical
@ -987,28 +1004,28 @@ COMMANDS
in single-column balance reports: use this custom line format
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
select the output format. Supported formats: txt, csv, html.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
--pretty-tables
use unicode to display prettier tables.
--sort-amount
sort by amount instead of account code/name (in flat mode).
sort by amount instead of account code/name (in flat mode).
With multiple columns, sorts by the row total, or by row average
if that is displayed.
--budget
show performance compared to budget goals defined by periodic
show performance compared to budget goals defined by periodic
transactions
--show-unbudgeted
with -budget, show unbudgeted accounts also
The balance command displays accounts and balances. It is hledger's
The balance command displays accounts and balances. It is hledger's
most featureful and versatile command.
$ hledger balance
@ -1025,28 +1042,28 @@ COMMANDS
--------------------
0
More precisely, the balance command shows the change to each account's
More precisely, the balance command shows the change to each account's
balance caused by all (matched) postings. In the common case where you
do not filter by date and your journal sets the correct opening bal-
do not filter by date and your journal sets the correct opening bal-
ances, this is the same as the account's ending balance.
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with
-S/--sort-amount, by their balance amount.
"Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com-
balance of their own, are elided into the following line for more com-
pact output. (Not yet supported in tabular reports.) Use --no-elide to
prevent this.
Account balances are "inclusive" - they include the balances of any
Account balances are "inclusive" - they include the balances of any
subaccounts.
Accounts which have zero balance (and no non-zero subaccounts) are
Accounts which have zero balance (and no non-zero subaccounts) are
omitted. Use -E/--empty to show them.
A final total is displayed by default; use -N/--no-total to suppress
A final total is displayed by default; use -N/--no-total to suppress
it:
$ hledger balance -p 2008/6 expenses --no-total
@ -1056,9 +1073,9 @@ COMMANDS
Flat mode
To see a flat list of full account names instead of the default hierar-
chical display, use --flat. In this mode, accounts (unless
chical display, use --flat. In this mode, accounts (unless
depth-clipped) show their "exclusive" balance, excluding any subaccount
balances. In this mode, you can also use --drop N to omit the first
balances. In this mode, you can also use --drop N to omit the first
few account name components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
@ -1066,9 +1083,9 @@ COMMANDS
$1 supplies
Depth limited balance reports
With --depth N, balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less
detail. In flat mode, balances from accounts below the depth limit
With --depth N, balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less
detail. In flat mode, balances from accounts below the depth limit
will be shown as part of a parent account at the depth limit.
$ hledger balance -N --depth 1
@ -1078,12 +1095,12 @@ COMMANDS
$1 liabilities
Multicolumn balance reports
With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column balance
With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column balance
report, showing different information:
1. By default: each column shows the sum of postings in that period, ie
the account's change of balance in that period. This is useful eg
the account's change of balance in that period. This is useful eg
for a monthly income statement:
$ hledger balance --quarterly income expenses -E
@ -1098,8 +1115,8 @@ COMMANDS
-------------------++---------------------------------
|| $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
2. With --cumulative: each column shows the ending balance for that
period, accumulating the changes across periods, starting from 0 at
the report start date:
$ hledger balance --quarterly income expenses -E --cumulative
@ -1115,8 +1132,8 @@ COMMANDS
|| $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending
balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is
balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is
useful eg for a multi-period balance sheet, and when you are showing
only the data after a certain start date:
@ -1132,26 +1149,26 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
Multi-column balance reports display accounts in flat mode by default;
Multi-column balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass
the displayed report periods. This is so that the first and last peri-
ods will be "full" and comparable to the others.
The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report
period (without -E, leading and trailing columns with all zeroes are
not shown). Second, all accounts which existed at the report start
date will be considered, not just the ones with activity during the
report period (use -E to include low-activity accounts which would oth-
erwise would be omitted).
The -T/--row-total flag adds an additional column showing the total for
each row.
The -A/--average flag adds a column showing the average value in each
The -A/--average flag adds a column showing the average value in each
row.
Here's an example of all three:
@ -1173,13 +1190,13 @@ COMMANDS
# Average is rounded to the dollar here since all journal amounts are
Budgets
With --budget and a report interval, all periodic transactions in your
journal with that interval, active during the requested report period,
are interpreted as recurring budget goals for the specified accounts
(and subaccounts), and the report will show the difference between
With --budget and a report interval, all periodic transactions in your
journal with that interval, active during the requested report period,
are interpreted as recurring budget goals for the specified accounts
(and subaccounts), and the report will show the difference between
actual and budgeted balances.
For example, you can take average monthly expenses in the common
For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
;; Budget
@ -1238,8 +1255,8 @@ COMMANDS
-----------------------++-------------------------------------------------
|| 0 0
Accounts with no budget goals (not mentioned in the periodic transac-
tions) will be aggregated under <unbudgeted>, unless you add the
Accounts with no budget goals (not mentioned in the periodic transac-
tions) will be aggregated under <unbudgeted>, unless you add the
--show-unbudgeted flag to display them normally:
$ hledger balance --budget --show-unbudgeted
@ -1260,8 +1277,8 @@ COMMANDS
For more examples and details, see Budgeting and Forecasting.
Custom balance output
In simple (non-multi-column) balance reports, you can customise the
output with --format FMT:
You can customise the layout of simple (non-tabular) balance reports
with --format FMT:
$ hledger balance --format "%20(account) %12(total)"
assets $-1
@ -1278,7 +1295,7 @@ COMMANDS
0
The FMT format string (plus a newline) specifies the formatting applied
to each account/balance pair. It may contain any suitable text, with
to each account/balance pair. It may contain any suitable text, with
data fields interpolated like so:
%[MIN][.MAX](FIELDNAME)
@ -1289,14 +1306,14 @@ COMMANDS
o FIELDNAME must be enclosed in parentheses, and can be one of:
o depth_spacer - a number of spaces equal to the account's depth, or
o depth_spacer - a number of spaces equal to the account's depth, or
if MIN is specified, MIN * depth spaces.
o account - the account's name
o total - the account's balance/posted total, right justified
Also, FMT can begin with an optional prefix to control how multi-com-
Also, FMT can begin with an optional prefix to control how multi-com-
modity amounts are rendered:
o %_ - render on multiple lines, bottom-aligned (the default)
@ -1305,7 +1322,7 @@ COMMANDS
o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results.
@ -1313,16 +1330,18 @@ COMMANDS
o %(total) - the account's total
o %-20.20(account) - the account's name, left justified, padded to 20
o %-20.20(account) - the account's name, left justified, padded to 20
characters and clipped at 20 characters
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
o %,%-50(account) %25(total) - account name padded to 50 characters,
total padded to 20 characters, with multiple commodities rendered on
one line
o %20(total) %2(depth_spacer)%-(account) - the default format for the
o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report
This command also supports output destination and output formats.
Colour support
The balance command shows negative amounts in red, if:
@ -1330,23 +1349,6 @@ COMMANDS
o the output is not being redirected or piped anywhere
Output destination
The balance, print, register and stats commands can write their output
to a destination other than the console. This is controlled by the
-o/--output-file option.
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
CSV output
The balance, print and register commands can write their output as CSV.
This is useful for exporting data to other applications, eg to make
charts in a spreadsheet. This is controlled by the -O/--output-format
option, or by specifying a .csv file extension with -o/--output-file.
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
balancesheet
This command displays a simple balance sheet, showing historical ending
balances of asset and liability accounts (ignoring any report begin
@ -1422,6 +1424,8 @@ COMMANDS
ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
This command also supports output destination and output formats.
balancesheetequity
Just like balancesheet, but also reports Equity (which it assumes is
under a top-level equity account).
@ -1519,6 +1523,8 @@ COMMANDS
though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical.
This command also supports output destination and output formats.
check-dates
Check that transactions are sorted by increasing date. With a query,
only matched transactions' dates are checked.
@ -1662,6 +1668,8 @@ COMMANDS
period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
This command also supports output destination and output formats.
prices
Print all market prices from the journal.
@ -1745,7 +1753,7 @@ COMMANDS
increasing dates, and that transactions on the same day do not get
reordered. See also the import command.
The print command also supports output destination and CSV output.
This command also supports output destination and output formats.
Here's an example of print's CSV output:
$ hledger print -Ocsv
@ -1899,12 +1907,11 @@ COMMANDS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
The register command also supports the -o/--output-file and -O/--out-
put-format options for controlling output destination and CSV output.
This command also supports output destination and output formats.
register-match
Print the one posting whose transaction description is closest to DESC,
in the style of the register command. Helps ledger-autosync detect
in the style of the register command. Helps ledger-autosync detect
already-seen transactions when importing.
rewrite
@ -1914,7 +1921,7 @@ COMMANDS
Show some journal statistics.
-o FILE --output-file=FILE
write output to FILE. A file extension matching one of the
write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger stats
@ -1929,12 +1936,11 @@ COMMANDS
Accounts : 8 (depth 3)
Commodities : 1 ($)
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
The stats command also supports -o/--output-file for controlling output
destination.
This command also supports output destination and output formats.
tags
List all the tag names used in the journal. With a TAGREGEX argument,

30
hledger/hledger_balance.m4.md
View File

@ -36,7 +36,7 @@ Show accounts and their balances. Aliases: b, bal.
`-O FMT --output-format=FMT `
: select the output format. Supported formats:
txt, csv.
txt, csv, html.
`-o FILE --output-file=FILE`
: write output to FILE. A file extension matching one of the above formats selects that format.
@ -336,8 +336,7 @@ For more examples and details, see [Budgeting and Forecasting](budgeting-and-for
### Custom balance output
In simple (non-multi-column) balance reports, you can customise the
output with `--format FMT`:
You can customise the layout of simple (non-tabular) balance reports with `--format FMT`:
```shell
$ hledger balance --format "%20(account) %12(total)"
@ -391,6 +390,8 @@ Some example formats:
- `%,%-50(account) %25(total)` - account name padded to 50 characters, total padded to 20 characters, with multiple commodities rendered on one line
- `%20(total) %2(depth_spacer)%-(account)` - the default format for the single-column balance report
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
### Colour support
The balance command shows negative amounts in red, if:
@ -398,27 +399,4 @@ The balance command shows negative amounts in red, if:
- the `TERM` environment variable is not set to `dumb`
- the output is not being redirected or piped anywhere
### Output destination
The balance, print, register and stats commands can write their output to a
destination other than the console. This is controlled by the
`-o/--output-file` option.
```shell
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
```
### CSV output
The balance, print and register commands can write their output as
CSV. This is useful for exporting data to other applications, eg to
make charts in a spreadsheet. This is controlled by the
`-O/--output-format` option, or by specifying a `.csv` file extension
with `-o/--output-file`.
```shell
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
```

18
hledger/hledger_commands.m4.md
View File

@ -250,6 +250,8 @@ Normally balancesheet shows historical ending balances, which is what
you need for a balance sheet; note this means it ignores report begin
dates.
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
## balancesheetequity
Just like [balancesheet](#balancesheet), but also reports Equity
(which it assumes is under a top-level `equity` account).
@ -349,6 +351,8 @@ Normally cashflow shows changes in assets per period, though
as with [multicolumn balance reports](#multicolumn-balance-reports)
you can alter the report mode with `--change`/`--cumulative`/`--historical`.
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
## check-dates
Check that transactions are sorted by increasing date.
With a query, only matched transactions' dates are checked.
@ -499,6 +503,8 @@ Normally incomestatement shows revenues/expenses per period, though
as with [multicolumn balance reports](#multicolumn-balance-reports)
you can alter the report mode with `--change`/`--cumulative`/`--historical`.
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
## prices
Print all [market prices](/manual#market-prices) from the journal.
@ -579,10 +585,7 @@ This assumes that transactions added to FILE always have same or increasing date
and that transactions on the same day do not get reordered.
See also the [import](#import) command.
The print command also supports
[output destination](#output-destination)
and
[CSV output](#csv-output).
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
Here's an example of print's CSV output:
```shell
$ hledger print -Ocsv
@ -737,9 +740,7 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
```
The register command also supports the
`-o/--output-file` and `-O/--output-format` options for controlling
[output destination](#output-destination) and [CSV output](#csv-output).
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
## register-match
Print the one posting whose transaction description is closest to DESC,
@ -773,8 +774,7 @@ The stats command displays summary information for the whole journal, or
a matched part of it. With a [reporting interval](#reporting-interval),
it shows a report for each report period.
The stats command also supports `-o/--output-file`
for controlling [output destination](#output-destination).
This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats).
## tags
List all the tag names used in the journal. With a TAGREGEX argument,

22
hledger/hledger_options.m4.md
View File

@ -414,6 +414,28 @@ not [transaction prices](journal.html#transaction-prices) (unlike Ledger).
Using -B/--cost and -V/--value together is currently allowed, but the
results are probably not meaningful. Let us know if you find a use for this.
### Output destination
Some commands (print, register, stats, the balance commands)
can write their output to a destination other than the console.
This is controlled by the `-o/--output-file` option.
```shell
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
```
### Output format
Some commands can write their output in other formats.
Eg print and register can output CSV, and the balance commands can output CSV or HTML.
This is controlled by the `-O/--output-format` option, or by specifying a `.csv` or `.html` file extension with `-o/--output-file`.
```shell
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
```
## Regular expressions
hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places: