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

;regen docs

Browse Source
This commit is contained in:
Simon Michael 2020-03-19 16:05:52 -07:00
parent 35ba2e4e9e
commit 1a606870ca
7 changed files with 531 additions and 502 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
hledger-lib/hledger_journal.5
View File

@ -601,6 +601,12 @@ In summary: amounts will be displayed much as they appear in your
journal, with the max observed number of decimal places. journal, with the max observed number of decimal places.
If you want to see fewer decimal places in reports, use a commodity If you want to see fewer decimal places in reports, use a commodity
directive to override that. directive to override that.
.PP
hledger uses banker\[aq]s rounding: it rounds to the nearest even
number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]).
(Note, prior to hledger 1.17.1 this could vary if hledger happened to be
built with an old version of Decimal (<0.5.1); since 1.17.1 it\[aq]s
guaranteed.)
.SS Transaction prices .SS Transaction prices
.PP .PP
Within a transaction, you can note an amount\[aq]s price in another Within a transaction, you can note an amount\[aq]s price in another
@ -1197,6 +1203,10 @@ The quantity of the amount does not matter; only the format is
significant. significant.
The number must include a decimal mark: either a period or a comma, The number must include a decimal mark: either a period or a comma,
followed by 0 or more decimal digits. followed by 0 or more decimal digits.
.PP
Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with
zero decimal digits is \[dq]0\[dq].
(More at Amount display style.)
.SS Default commodity .SS Default commodity
.PP .PP
The \f[C]D\f[R] directive sets a default commodity, to be used for The \f[C]D\f[R] directive sets a default commodity, to be used for

176
hledger-lib/hledger_journal.info
View File

@ -544,6 +544,11 @@ journal, with the max observed number of decimal places. If you want to
see fewer decimal places in reports, use a commodity directive to see fewer decimal places in reports, use a commodity directive to
override that. override that.
hledger uses banker's rounding: it rounds to the nearest even number,
eg 0.5 displayed with zero decimal places is "0"). (Note, prior to
hledger 1.17.1 this could vary if hledger happened to be built with an
old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.)
 
File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions
@ -1070,6 +1075,9 @@ commodity INR
significant. The number must include a decimal mark: either a period or significant. The number must include a decimal mark: either a period or
a comma, followed by 0 or more decimal digits. a comma, followed by 0 or more decimal digits.
Note hledger normally uses banker's rounding, so 0.5 displayed with
zero decimal digits is "0". (More at Amount display style.)
 
File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
@ -1821,90 +1829,90 @@ Node: Digit group marks16739
Ref: #digit-group-marks16887 Ref: #digit-group-marks16887
Node: Amount display style17825 Node: Amount display style17825
Ref: #amount-display-style17979 Ref: #amount-display-style17979
Node: Transaction prices19140 Node: Transaction prices19417
Ref: #transaction-prices19306 Ref: #transaction-prices19583
Node: Balance Assertions21572 Node: Balance Assertions21849
Ref: #balance-assertions21752 Ref: #balance-assertions22029
Node: Assertions and ordering22785 Node: Assertions and ordering23062
Ref: #assertions-and-ordering22973 Ref: #assertions-and-ordering23250
Node: Assertions and included files23673 Node: Assertions and included files23950
Ref: #assertions-and-included-files23916 Ref: #assertions-and-included-files24193
Node: Assertions and multiple -f options24249 Node: Assertions and multiple -f options24526
Ref: #assertions-and-multiple--f-options24505 Ref: #assertions-and-multiple--f-options24782
Node: Assertions and commodities24637 Node: Assertions and commodities24914
Ref: #assertions-and-commodities24869 Ref: #assertions-and-commodities25146
Node: Assertions and prices26026 Node: Assertions and prices26303
Ref: #assertions-and-prices26240 Ref: #assertions-and-prices26517
Node: Assertions and subaccounts26680 Node: Assertions and subaccounts26957
Ref: #assertions-and-subaccounts26909 Ref: #assertions-and-subaccounts27186
Node: Assertions and virtual postings27233 Node: Assertions and virtual postings27510
Ref: #assertions-and-virtual-postings27475 Ref: #assertions-and-virtual-postings27752
Node: Assertions and precision27617 Node: Assertions and precision27894
Ref: #assertions-and-precision27810 Ref: #assertions-and-precision28087
Node: Balance Assignments28077 Node: Balance Assignments28354
Ref: #balance-assignments28251 Ref: #balance-assignments28528
Node: Balance assignments and prices29415 Node: Balance assignments and prices29692
Ref: #balance-assignments-and-prices29587 Ref: #balance-assignments-and-prices29864
Node: Directives29811 Node: Directives30088
Ref: #directives29970 Ref: #directives30247
Node: Directives and multiple files35651 Node: Directives and multiple files35928
Ref: #directives-and-multiple-files35834 Ref: #directives-and-multiple-files36111
Node: Comment blocks36498 Node: Comment blocks36775
Ref: #comment-blocks36681 Ref: #comment-blocks36958
Node: Including other files36857 Node: Including other files37134
Ref: #including-other-files37037 Ref: #including-other-files37314
Node: Default year37445 Node: Default year37722
Ref: #default-year37614 Ref: #default-year37891
Node: Declaring commodities38021 Node: Declaring commodities38298
Ref: #declaring-commodities38204 Ref: #declaring-commodities38481
Node: Default commodity39877 Node: Default commodity40287
Ref: #default-commodity40053 Ref: #default-commodity40463
Node: Market prices40942 Node: Market prices41352
Ref: #market-prices41107 Ref: #market-prices41517
Node: Declaring accounts41948 Node: Declaring accounts42358
Ref: #declaring-accounts42124 Ref: #declaring-accounts42534
Node: Account comments43049 Node: Account comments43459
Ref: #account-comments43212 Ref: #account-comments43622
Node: Account subdirectives43636 Node: Account subdirectives44046
Ref: #account-subdirectives43831 Ref: #account-subdirectives44241
Node: Account types44144 Node: Account types44554
Ref: #account-types44328 Ref: #account-types44738
Node: Account display order45967 Node: Account display order46377
Ref: #account-display-order46137 Ref: #account-display-order46547
Node: Rewriting accounts47288 Node: Rewriting accounts47698
Ref: #rewriting-accounts47473 Ref: #rewriting-accounts47883
Node: Basic aliases48230 Node: Basic aliases48640
Ref: #basic-aliases48376 Ref: #basic-aliases48786
Node: Regex aliases49080 Node: Regex aliases49490
Ref: #regex-aliases49252 Ref: #regex-aliases49662
Node: Combining aliases49970 Node: Combining aliases50380
Ref: #combining-aliases50163 Ref: #combining-aliases50573
Node: Aliases and multiple files51439 Node: Aliases and multiple files51849
Ref: #aliases-and-multiple-files51648 Ref: #aliases-and-multiple-files52058
Node: end aliases52227 Node: end aliases52637
Ref: #end-aliases52384 Ref: #end-aliases52794
Node: Default parent account52485 Node: Default parent account52895
Ref: #default-parent-account52653 Ref: #default-parent-account53063
Node: Periodic transactions53537 Node: Periodic transactions53947
Ref: #periodic-transactions53712 Ref: #periodic-transactions54122
Node: Periodic rule syntax55584 Node: Periodic rule syntax55994
Ref: #periodic-rule-syntax55790 Ref: #periodic-rule-syntax56200
Node: Two spaces between period expression and description!56494 Node: Two spaces between period expression and description!56904
Ref: #two-spaces-between-period-expression-and-description56813 Ref: #two-spaces-between-period-expression-and-description57223
Node: Forecasting with periodic transactions57497 Node: Forecasting with periodic transactions57907
Ref: #forecasting-with-periodic-transactions57802 Ref: #forecasting-with-periodic-transactions58212
Node: Budgeting with periodic transactions59828 Node: Budgeting with periodic transactions60238
Ref: #budgeting-with-periodic-transactions60067 Ref: #budgeting-with-periodic-transactions60477
Node: Auto postings60516 Node: Auto postings60926
Ref: #auto-postings60656 Ref: #auto-postings61066
Node: Auto postings and multiple files62835 Node: Auto postings and multiple files63245
Ref: #auto-postings-and-multiple-files63039 Ref: #auto-postings-and-multiple-files63449
Node: Auto postings and dates63248 Node: Auto postings and dates63658
Ref: #auto-postings-and-dates63522 Ref: #auto-postings-and-dates63932
Node: Auto postings and transaction balancing / inferred amounts / balance assertions63697 Node: Auto postings and transaction balancing / inferred amounts / balance assertions64107
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64048 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64458
Node: Auto posting tags64390 Node: Auto posting tags64800
Ref: #auto-posting-tags64605 Ref: #auto-posting-tags65015
 
End Tag Table End Tag Table

197
hledger-lib/hledger_journal.txt
View File

@ -429,11 +429,16 @@ FILE FORMAT
see fewer decimal places in reports, use a commodity directive to over- see fewer decimal places in reports, use a commodity directive to over-
ride that. ride that.
hledger uses banker's rounding: it rounds to the nearest even number,
eg 0.5 displayed with zero decimal places is "0"). (Note, prior to
hledger 1.17.1 this could vary if hledger happened to be built with an
old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.)
Transaction prices Transaction prices
Within a transaction, you can note an amount's price in another commod- Within a transaction, you can note an amount's price in another commod-
ity. This can be used to document the cost (in a purchase) or selling ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer- also market prices, which represent prevailing exchange rates on a cer-
tain date. tain date.
@ -462,7 +467,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores). PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price's Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above: Eg here is how -B affects the balance report for the example above:
@ -473,8 +478,8 @@ FILE FORMAT
$-135 assets:dollars $-135 assets:dollars
$135 assets:euros # <- the euros' cost $135 assets:euros # <- the euros' cost
Note -B is sensitive to the order of postings when a transaction price Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last is inferred: the inferred price will be in the commodity of the last
amount. So if example 3's postings are reversed, while the transaction amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different: is equivalent, -B shows something different:
@ -487,9 +492,9 @@ FILE FORMAT
EUR100 assets:euros EUR100 assets:euros
Balance Assertions Balance Assertions
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a amount. Eg here we assert the expected dollar balance in accounts a
and b after each posting: and b after each posting:
2013/1/1 2013/1/1
@ -501,32 +506,32 @@ FILE FORMAT
b $-1 =$-2 b $-1 =$-2
After reading a journal file, hledger will check all balance assertions After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro- and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the cleaning up old entries. You can disable them temporarily with the
-I/--ignore-assertions flag, which can be useful for troubleshooting or -I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files. (Note: this flag currently does not disable for reading Ledger files. (Note: this flag currently does not disable
balance assignments, below). balance assignments, below).
Assertions and ordering Assertions and ordering
hledger sorts an account's postings and assertions first by date and hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif- then (for postings on the same day) by parse order. Note this is dif-
ferent from Ledger, which sorts assertions only by parse order. (Also, ferent from Ledger, which sorts assertions only by parse order. (Also,
Ledger assertions do not see the accumulated effect of repeated post- Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.) ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differently- So, hledger balance assertions keep working if you reorder differently-
dated transactions within the journal. But if you reorder same-dated dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating. transactions or postings, assertions might break and require updating.
This order dependence does bring an advantage: precise control over the This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert intra- order of postings and assertions within a day, so you can assert intra-
day balances. day balances.
Assertions and included files Assertions and included files
With included files, things are a little more complicated. Including With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi- preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same files, and you also want to assert the account's balance on the same
day, you'll have to put the assertion in the right file. day, you'll have to put the assertion in the right file.
Assertions and multiple -f options Assertions and multiple -f options
@ -534,15 +539,15 @@ FILE FORMAT
-f options. Use include or concatenate the files instead. -f options. Use include or concatenate the files instead.
Assertions and commodities Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. This is how assertions (possibly multi-commodity) account balance. This is how assertions
work in Ledger also. We could call this a "partial" balance assertion. work in Ledger also. We could call this a "partial" balance assertion.
To assert the balance of more than one commodity in an account, you can To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance. write multiple postings, each asserting one commodity's balance.
You can make a stronger "total" balance assertion by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (== EXPECTEDBALANCE). This asserts that there are no other equals sign (== EXPECTEDBALANCE). This asserts that there are no other
unasserted commodities in the account (or, that their balance is 0). unasserted commodities in the account (or, that their balance is 0).
@ -562,7 +567,7 @@ FILE FORMAT
a 0 == $1 a 0 == $1
It's not yet possible to make a complete assertion about a balance that It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity has multiple commodities. One workaround is to isolate each commodity
into its own subaccount: into its own subaccount:
2013/1/1 2013/1/1
@ -576,21 +581,21 @@ FILE FORMAT
a:euro 0 == 1EUR a:euro 0 == 1EUR
Assertions and prices Assertions and prices
Balance assertions ignore transaction prices, and should normally be Balance assertions ignore transaction prices, and should normally be
written without one: written without one:
2019/1/1 2019/1/1
(a) $1 @ EUR1 = $1 (a) $1 @ EUR1 = $1
We do allow prices to be written there, however, and print shows them, We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails. even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign- generate balance assertions with prices), and because balance assign-
ments do use them (see below). ments do use them (see below).
Assertions and subaccounts Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg: assert the balance including subaccounts by writing =* or ==*, eg:
2019/1/1 2019/1/1
@ -604,16 +609,16 @@ FILE FORMAT
tual. They are not affected by the --real/-R flag or real: query. tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision Assertions and precision
Balance assertions compare the exactly calculated amounts, which are Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser- limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts. tions. Balance assertion failure messages show exact amounts.
Balance Assignments Balance Assignments
Ledger-style balance assignments are also supported. These are like Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when the assertion. This can be a convenience during data entry, eg when
setting opening balances: setting opening balances:
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
@ -631,14 +636,14 @@ FILE FORMAT
expenses:misc expenses:misc
The calculated amount depends on the account's balance in the commodity The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign- commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it. or do the calculations yourself, instead of just reading it.
Balance assignments and prices Balance assignments and prices
A transaction price in a balance assignment will cause the calculated A transaction price in a balance assignment will cause the calculated
amount to have that price attached: amount to have that price attached:
2019/1/1 2019/1/1
@ -649,85 +654,84 @@ FILE FORMAT
(a) $1 @ EUR2 = $1 @ EUR2 (a) $1 @ EUR2 = $1 @ EUR2
Directives Directives
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions). some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with here is a table summarising the directives and their effects, with
links to more detailed docs. links to more detailed docs.
direc- end di- subdi- purpose can affect (as of direc- end di- subdi- purpose can affect (as of
tive rective rec- 2018/06) tive rective rec- 2018/06)
tives tives
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
account any document account names, de- all entries in all account any document account names, de- all entries in all
text clare account types & dis- files, before or text clare account types & dis- files, before or
play order after play order after
alias end rewrite account names following in- alias end rewrite account names following in-
aliases line/included en- aliases line/included en-
tries until end of tries until end of
current file or end current file or end
directive directive
apply end apply prepend a common parent to following in- apply end apply prepend a common parent to following in-
account account account names line/included en- account account account names line/included en-
tries until end of tries until end of
current file or end current file or end
directive directive
comment end com- ignore part of journal following in- comment end com- ignore part of journal following in-
ment line/included en- ment line/included en-
tries until end of tries until end of
current file or end current file or end
directive directive
commod- format declare a commodity and its number notation: commod- format declare a commodity and its number notation:
ity number notation & display following entries ity number notation & display following entries
style in that commodity style in that commodity
in all files; dis- in all files; dis-
play style: amounts play style: amounts
of that commodity of that commodity
in reports in reports
D declare a commodity to be default commodity: D declare a commodity to be default commodity:
used for commodityless following commod- used for commodityless following commod-
amounts, and its number no- ityless entries un- amounts, and its number no- ityless entries un-
tation & display style til end of current tation & display style til end of current
file; number nota- file; number nota-
tion: following en- tion: following en-
tries in that com- tries in that com-
modity until end of modity until end of
current file; dis- current file; dis-
play style: amounts play style: amounts
of that commodity of that commodity
in reports in reports
include include entries/directives what the included include include entries/directives what the included
from another file directives affect from another file directives affect
P declare a market price for a amounts of that P declare a market price for a amounts of that
commodity commodity in re- commodity commodity in re-
ports, when -V is ports, when -V is
used used
Y declare a year for yearless following in- Y declare a year for yearless following in-
dates line/included en- dates line/included en-
tries until end of tries until end of
current file current file
= declare an auto posting all entries in par- = declare an auto posting all entries in par-
rule, adding postings to ent/current/child rule, adding postings to ent/current/child
other transactions files (but not sib- other transactions files (but not sib-
ling files, see ling files, see
#1212) #1212)
And some definitions: And some definitions:
subdi- optional indented directive line immediately following a parent subdi- optional indented directive line immediately following a parent
rec- directive rec- directive
tive tive
number how to interpret numbers when parsing journal entries (the iden- number how to interpret numbers when parsing journal entries (the iden-
nota- tity of the decimal separator character). (Currently each com- nota- tity of the decimal separator character). (Currently each com-
tion modity can have its own notation, even in the same file.) tion modity can have its own notation, even in the same file.)
dis- how to display amounts of a commodity in reports (symbol side
dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places) play and spacing, digit groups, decimal separator, decimal places)
style style
direc- which entries and (when there are multiple files) which files direc- which entries and (when there are multiple files) which files
tive are affected by a directive tive are affected by a directive
scope scope
@ -736,41 +740,41 @@ FILE FORMAT
ports). Some directives have multiple effects. ports). Some directives have multiple effects.
Directives and multiple files Directives and multiple files
If you use multiple -f/--file options, or the include directive, If you use multiple -f/--file options, or the include directive,
hledger will process multiple input files. But note that directives hledger will process multiple input files. But note that directives
which affect input (see above) typically last only until the end of the which affect input (see above) typically last only until the end of the
file in which they occur. file in which they occur.
This may seem inconvenient, but it's intentional; it makes reports sta- This may seem inconvenient, but it's intentional; it makes reports sta-
ble and deterministic, independent of the order of input. Otherwise ble and deterministic, independent of the order of input. Otherwise
you could see different numbers if you happened to write -f options in you could see different numbers if you happened to write -f options in
a different order, or if you moved includes around while cleaning up a different order, or if you moved includes around while cleaning up
your files. your files.
It can be surprising though; for example, it means that alias direc- It can be surprising though; for example, it means that alias direc-
tives do not affect parent or sibling files (see below). tives do not affect parent or sibling files (see below).
Comment blocks Comment blocks
A line containing just comment starts a commented region of the file, A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file) and a line containing just end comment (or the end of the current file)
ends it. See also comments. ends it. See also comments.
Including other files Including other files
You can pull in the content of additional files by writing an include You can pull in the content of additional files by writing an include
directive, like this: directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g. file. The include file path may contain common glob patterns (e.g.
*). *).
The include directive can only be used in journal files. It can in- The include directive can only be used in journal files. It can in-
clude journal, timeclock or timedot files, but not CSV files. clude journal, timeclock or timedot files, but not CSV files.
Default year Default year
You can set a default year to be used for subsequent dates which don't You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -792,19 +796,19 @@ FILE FORMAT
Declaring commodities Declaring commodities
The commodity directive has several functions: The commodity directive has several functions:
1. It declares commodities which may be used in the journal. This is 1. It declares commodities which may be used in the journal. This is
currently not enforced, but can serve as documentation. currently not enforced, but can serve as documentation.
2. It declares what decimal mark character (period or comma) to expect 2. It declares what decimal mark character (period or comma) to expect
when parsing input - useful to disambiguate international number when parsing input - useful to disambiguate international number
formats in your data. (Without this, hledger will parse both 1,000 formats in your data. (Without this, hledger will parse both 1,000
and 1.000 as 1). and 1.000 as 1).
3. It declares the amount display style to use in output - decimal and 3. It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc. digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di- You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them rectives, sooner or later, so it's a good idea to just always use them
to declare your commodities. to declare your commodities.
A commodity directive is just the word commodity followed by an amount. A commodity directive is just the word commodity followed by an amount.
@ -817,8 +821,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. (In this case or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places.): places.):
; commodity SYMBOL ; commodity SYMBOL
@ -831,9 +835,12 @@ FILE FORMAT
format INR 1,00,00,000.00 format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi- The quantity of the amount does not matter; only the format is signifi-
cant. The number must include a decimal mark: either a period or a cant. The number must include a decimal mark: either a period or a
comma, followed by 0 or more decimal digits. comma, followed by 0 or more decimal digits.
Note hledger normally uses banker's rounding, so 0.5 displayed with
zero decimal digits is "0". (More at Amount display style.)
Default commodity Default commodity
The D directive sets a default commodity, to be used for amounts with- The D directive sets a default commodity, to be used for amounts with-
out a commodity symbol (ie, plain numbers). This commodity will be ap- out a commodity symbol (ie, plain numbers). This commodity will be ap-

7
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -351,13 +351,14 @@ Budget performance in 2017/11/01-2017/12/31:
----------------------++---------------------------------------------------- ----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0] || 0 [ 0] 0 [ 0]
Note this is different from a normal balance report in several ways: This is different from a normal balance report in several ways:
- Only accounts with budget goals during the report period are shown, - Only accounts with budget goals during the report period are shown,
by default. by default.
- In each column, in square brackets after the actual amount, budgeted - In each column, in square brackets after the actual amount, budget
amounts are shown, along with the percentage of budget used. goal amounts are shown, and the actual/goal percentage. (Note:
budget goals should be in the same commodity as the actual amount.)
- All parent accounts are always shown, even in flat mode. Eg assets, - All parent accounts are always shown, even in flat mode. Eg assets,
assets:bank, and expenses above. assets:bank, and expenses above.

8
hledger/hledger.1
View File

@ -2838,13 +2838,15 @@ Budget performance in 2017/11/01-2017/12/31:
\f[R] \f[R]
.fi .fi
.PP .PP
Note this is different from a normal balance report in several ways: This is different from a normal balance report in several ways:
.IP \[bu] 2 .IP \[bu] 2
Only accounts with budget goals during the report period are shown, by Only accounts with budget goals during the report period are shown, by
default. default.
.IP \[bu] 2 .IP \[bu] 2
In each column, in square brackets after the actual amount, budgeted In each column, in square brackets after the actual amount, budget goal
amounts are shown, along with the percentage of budget used. amounts are shown, and the actual/goal percentage.
(Note: budget goals should be in the same commodity as the actual
amount.)
.IP \[bu] 2 .IP \[bu] 2
All parent accounts are always shown, even in flat mode. All parent accounts are always shown, even in flat mode.
Eg assets, assets:bank, and expenses above. Eg assets, assets:bank, and expenses above.

174
hledger/hledger.info
View File

@ -2319,14 +2319,14 @@ Budget performance in 2017/11/01-2017/12/31:
----------------------++---------------------------------------------------- ----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0] || 0 [ 0] 0 [ 0]
Note this is different from a normal balance report in several ways: This is different from a normal balance report in several ways:
* Only accounts with budget goals during the report period are shown, * Only accounts with budget goals during the report period are shown,
by default. by default.
* In each column, in square brackets after the actual amount, * In each column, in square brackets after the actual amount, budget
budgeted amounts are shown, along with the percentage of budget goal amounts are shown, and the actual/goal percentage. (Note:
used. budget goals should be in the same commodity as the actual amount.)
* All parent accounts are always shown, even in flat mode. Eg * All parent accounts are always shown, even in flat mode. Eg
assets, assets:bank, and expenses above. assets, assets:bank, and expenses above.
@ -3832,89 +3832,89 @@ Node: Multicolumn balance report73444
Ref: #multicolumn-balance-report73624 Ref: #multicolumn-balance-report73624
Node: Budget report78886 Node: Budget report78886
Ref: #budget-report79029 Ref: #budget-report79029
Node: Nested budgets84231 Node: Nested budgets84295
Ref: #nested-budgets84343 Ref: #nested-budgets84407
Ref: #output-format-187824 Ref: #output-format-187888
Node: balancesheet88021 Node: balancesheet88085
Ref: #balancesheet88157 Ref: #balancesheet88221
Node: balancesheetequity89623 Node: balancesheetequity89687
Ref: #balancesheetequity89772 Ref: #balancesheetequity89836
Node: cashflow90495 Node: cashflow90559
Ref: #cashflow90623 Ref: #cashflow90687
Node: check-dates91802 Node: check-dates91866
Ref: #check-dates91929 Ref: #check-dates91993
Node: check-dupes92208 Node: check-dupes92272
Ref: #check-dupes92332 Ref: #check-dupes92396
Node: close92625 Node: close92689
Ref: #close92739 Ref: #close92803
Node: close usage94261 Node: close usage94325
Ref: #close-usage94354 Ref: #close-usage94418
Node: commodities97167 Node: commodities97231
Ref: #commodities97294 Ref: #commodities97358
Node: descriptions97376 Node: descriptions97440
Ref: #descriptions97504 Ref: #descriptions97568
Node: diff97685 Node: diff97749
Ref: #diff97791 Ref: #diff97855
Node: files98838 Node: files98902
Ref: #files98938 Ref: #files99002
Node: help99085 Node: help99149
Ref: #help99185 Ref: #help99249
Node: import100266 Node: import100330
Ref: #import100380 Ref: #import100444
Node: Importing balance assignments101273 Node: Importing balance assignments101337
Ref: #importing-balance-assignments101421 Ref: #importing-balance-assignments101485
Node: incomestatement102070 Node: incomestatement102134
Ref: #incomestatement102203 Ref: #incomestatement102267
Node: notes103690 Node: notes103754
Ref: #notes103803 Ref: #notes103867
Node: payees103929 Node: payees103993
Ref: #payees104035 Ref: #payees104099
Node: prices104193 Node: prices104257
Ref: #prices104299 Ref: #prices104363
Node: print104640 Node: print104704
Ref: #print104750 Ref: #print104814
Node: print-unique109536 Node: print-unique109600
Ref: #print-unique109662 Ref: #print-unique109726
Node: register109947 Node: register110011
Ref: #register110074 Ref: #register110138
Node: Custom register output114246 Node: Custom register output114310
Ref: #custom-register-output114375 Ref: #custom-register-output114439
Node: register-match115712 Node: register-match115776
Ref: #register-match115846 Ref: #register-match115910
Node: rewrite116197 Node: rewrite116261
Ref: #rewrite116312 Ref: #rewrite116376
Node: Re-write rules in a file118167 Node: Re-write rules in a file118231
Ref: #re-write-rules-in-a-file118301 Ref: #re-write-rules-in-a-file118365
Node: Diff output format119511 Node: Diff output format119575
Ref: #diff-output-format119680 Ref: #diff-output-format119744
Node: rewrite vs print --auto120772 Node: rewrite vs print --auto120836
Ref: #rewrite-vs.-print---auto120951 Ref: #rewrite-vs.-print---auto121015
Node: roi121507 Node: roi121571
Ref: #roi121605 Ref: #roi121669
Node: stats122617 Node: stats122681
Ref: #stats122716 Ref: #stats122780
Node: tags123504 Node: tags123568
Ref: #tags123602 Ref: #tags123666
Node: test123896 Node: test123960
Ref: #test124004 Ref: #test124068
Node: Add-on Commands124751 Node: Add-on Commands124815
Ref: #add-on-commands124868 Ref: #add-on-commands124932
Node: ui126211 Node: ui126275
Ref: #ui126299 Ref: #ui126363
Node: web126353 Node: web126417
Ref: #web126456 Ref: #web126520
Node: iadd126572 Node: iadd126636
Ref: #iadd126683 Ref: #iadd126747
Node: interest126765 Node: interest126829
Ref: #interest126872 Ref: #interest126936
Node: ENVIRONMENT127112 Node: ENVIRONMENT127176
Ref: #environment127224 Ref: #environment127288
Node: FILES128053 Node: FILES128117
Ref: #files-1128156 Ref: #files-1128220
Node: LIMITATIONS128369 Node: LIMITATIONS128433
Ref: #limitations128488 Ref: #limitations128552
Node: TROUBLESHOOTING129230 Node: TROUBLESHOOTING129294
Ref: #troubleshooting129343 Ref: #troubleshooting129407
 
End Tag Table End Tag Table

461
hledger/hledger.txt
View File

@ -1995,27 +1995,28 @@ COMMANDS
----------------------++---------------------------------------------------- ----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0] || 0 [ 0] 0 [ 0]
Note this is different from a normal balance report in several ways: This is different from a normal balance report in several ways:
o Only accounts with budget goals during the report period are shown, o Only accounts with budget goals during the report period are shown,
by default. by default.
o In each column, in square brackets after the actual amount, budgeted o In each column, in square brackets after the actual amount, budget
amounts are shown, along with the percentage of budget used. goal amounts are shown, and the actual/goal percentage. (Note: bud-
get goals should be in the same commodity as the actual amount.)
o All parent accounts are always shown, even in flat mode. Eg assets, o All parent accounts are always shown, even in flat mode. Eg assets,
assets:bank, and expenses above. assets:bank, and expenses above.
o Amounts always include all subaccounts, budgeted or unbudgeted, even o Amounts always include all subaccounts, budgeted or unbudgeted, even
in flat mode. in flat mode.
This means that the numbers displayed will not always add up! Eg above, This means that the numbers displayed will not always add up! Eg above,
the expenses actual amount includes the gifts and supplies transac- the expenses actual amount includes the gifts and supplies transac-
tions, but the expenses:gifts and expenses:supplies accounts are not tions, but the expenses:gifts and expenses:supplies accounts are not
shown, as they have no budget amounts declared. shown, as they have no budget amounts declared.
This can be confusing. When you need to make things clearer, use the This can be confusing. When you need to make things clearer, use the
-E/--empty flag, which will reveal all accounts including unbudgeted -E/--empty flag, which will reveal all accounts including unbudgeted
ones, giving the full picture. Eg: ones, giving the full picture. Eg:
$ hledger balance -M --budget --empty $ hledger balance -M --budget --empty
@ -2057,12 +2058,12 @@ COMMANDS
For more examples, see Budgeting and Forecasting. For more examples, see Budgeting and Forecasting.
Nested budgets Nested budgets
You can add budgets to any account in your account hierarchy. If you You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud- have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their get(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave. parent, much like account balances behave.
In the most simple case this means that once you add a budget to any In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well. account, all its parents would have budget as well.
To illustrate this, consider the following budget: To illustrate this, consider the following budget:
@ -2072,13 +2073,13 @@ COMMANDS
expenses:personal:electronics $100.00 expenses:personal:electronics $100.00
liabilities liabilities
With this, monthly budget for electronics is defined to be $100 and With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicitly budget for personal expenses is an additional $1000, which implicitly
means that budget for both expenses:personal and expenses is $1100. means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both to- Transactions in expenses:personal:electronics will be counted both to-
wards its $100 budget and $1100 of expenses:personal , and transactions wards its $100 budget and $1100 of expenses:personal , and transactions
in any other subaccount of expenses:personal would be counted towards in any other subaccount of expenses:personal would be counted towards
only towards the budget of expenses:personal. only towards the budget of expenses:personal.
For example, let's consider these transactions: For example, let's consider these transactions:
@ -2104,9 +2105,9 @@ COMMANDS
expenses:personal $30.00 expenses:personal $30.00
liabilities liabilities
As you can see, we have transactions in expenses:personal:electron- As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac- these accounts are without explicitly defined budget, these transac-
tions would be counted towards budgets of expenses:personal:electronics tions would be counted towards budgets of expenses:personal:electronics
and expenses:personal accordingly: and expenses:personal accordingly:
@ -2122,7 +2123,7 @@ COMMANDS
-------------------------------++------------------------------- -------------------------------++-------------------------------
|| 0 [ 0] || 0 [ 0]
And with --empty, we can get a better picture of budget allocation and And with --empty, we can get a better picture of budget allocation and
consumption: consumption:
$ hledger balance --budget -M --empty $ hledger balance --budget -M --empty
@ -2141,17 +2142,17 @@ COMMANDS
Output format Output format
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, (multicolumn non-bud- tions The output formats supported are txt, csv, (multicolumn non-bud-
get reports only) html, and (experimental) json. get reports only) html, and (experimental) json.
balancesheet balancesheet
balancesheet, bs balancesheet, bs
This command displays a simple balance sheet, showing historical ending This command displays a simple balance sheet, showing historical ending
balances of asset and liability accounts (ignoring any report begin balances of asset and liability accounts (ignoring any report begin
date). It assumes that these accounts are under a top-level asset or date). It assumes that these accounts are under a top-level asset or
liability account (case insensitive, plural forms also allowed). liability account (case insensitive, plural forms also allowed).
Note this report shows all account balances with normal positive sign Note this report shows all account balances with normal positive sign
(like conventional financial statements, unlike balance/print/register) (like conventional financial statements, unlike balance/print/register)
(experimental). (experimental).
@ -2177,21 +2178,21 @@ COMMANDS
0 0
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. As with multicolumn balance reports, you can alter the report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal- report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates (and a balance sheet; note this means it ignores report begin dates (and
-T/--row-total, since summing end balances generally does not make -T/--row-total, since summing end balances generally does not make
sense). Instead of absolute values percentages can be displayed with sense). Instead of absolute values percentages can be displayed with
-%. -%.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, html, and (experimen- tions The output formats supported are txt, csv, html, and (experimen-
tal) json. tal) json.
balancesheetequity balancesheetequity
balancesheetequity, bse balancesheetequity, bse
Just like balancesheet, but also reports Equity (which it assumes is Just like balancesheet, but also reports Equity (which it assumes is
under a top-level equity account). under a top-level equity account).
Example: Example:
@ -2221,15 +2222,15 @@ COMMANDS
0 0
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, html, and (experimen- tions The output formats supported are txt, csv, html, and (experimen-
tal) json. tal) json.
cashflow cashflow
cashflow, cf cashflow, cf
This command displays a simple cashflow statement, showing changes in This command displays a simple cashflow statement, showing changes in
"cash" accounts. It assumes that these accounts are under a top-level "cash" accounts. It assumes that these accounts are under a top-level
asset account (case insensitive, plural forms also allowed) and do not asset account (case insensitive, plural forms also allowed) and do not
contain receivable or A/R in their name. Note this report shows all contain receivable or A/R in their name. Note this report shows all
account balances with normal positive sign (like conventional financial account balances with normal positive sign (like conventional financial
statements, unlike balance/print/register) (experimental). statements, unlike balance/print/register) (experimental).
@ -2250,90 +2251,90 @@ COMMANDS
$-1 $-1
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. Normally cashflow shows changes in assets per period, report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical. Instead of absolute val- mode with --change/--cumulative/--historical. Instead of absolute val-
ues percentages can be displayed with -%. ues percentages can be displayed with -%.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, html, and (experimen- tions The output formats supported are txt, csv, html, and (experimen-
tal) json. tal) json.
check-dates check-dates
check-dates check-dates
Check that transactions are sorted by increasing date. With --date2, Check that transactions are sorted by increasing date. With --date2,
checks secondary dates instead. With --strict, dates must also be checks secondary dates instead. With --strict, dates must also be
unique. With a query, only matched transactions' dates are checked. unique. With a query, only matched transactions' dates are checked.
Reads the default journal file, or another specified with -f. Reads the default journal file, or another specified with -f.
check-dupes check-dupes
check-dupes check-dupes
Reports account names having the same leaf but different prefixes. In Reports account names having the same leaf but different prefixes. In
other words, two or more leaves that are categorized differently. other words, two or more leaves that are categorized differently.
Reads the default journal file, or another specified as an argument. Reads the default journal file, or another specified as an argument.
An example: http://stefanorodighiero.net/software/hledger-dupes.html An example: http://stefanorodighiero.net/software/hledger-dupes.html
close close
close, equity close, equity
Prints a "closing balances" transaction and an "opening balances" Prints a "closing balances" transaction and an "opening balances"
transaction that bring account balances to and from zero, respectively. transaction that bring account balances to and from zero, respectively.
These can be added to your journal file(s), eg to bring asset/liability These can be added to your journal file(s), eg to bring asset/liability
balances forward into a new journal file, or to close out revenues/ex- balances forward into a new journal file, or to close out revenues/ex-
penses to retained earnings at the end of a period. penses to retained earnings at the end of a period.
You can print just one of these transactions by using the --close or You can print just one of these transactions by using the --close or
--open flag. You can customise their descriptions with the --close- --open flag. You can customise their descriptions with the --close-
desc and --open-desc options. desc and --open-desc options.
One amountless posting to "equity:opening/closing balances" is added to One amountless posting to "equity:opening/closing balances" is added to
balance the transactions, by default. You can customise this account balance the transactions, by default. You can customise this account
name with --close-acct and --open-acct; if you specify only one of name with --close-acct and --open-acct; if you specify only one of
these, it will be used for both. these, it will be used for both.
With --x/--explicit, the equity posting's amount will be shown. And if With --x/--explicit, the equity posting's amount will be shown. And if
it involves multiple commodities, a posting for each commodity will be it involves multiple commodities, a posting for each commodity will be
shown, as with the print command. shown, as with the print command.
With --interleaved, the equity postings are shown next to the postings With --interleaved, the equity postings are shown next to the postings
they balance, which makes troubleshooting easier. they balance, which makes troubleshooting easier.
By default, transaction prices in the journal are ignored when generat- By default, transaction prices in the journal are ignored when generat-
ing the closing/opening transactions. With --show-costs, this cost in- ing the closing/opening transactions. With --show-costs, this cost in-
formation is preserved (balance -B reports will be unchanged after the formation is preserved (balance -B reports will be unchanged after the
transition). Separate postings are generated for each cost in each transition). Separate postings are generated for each cost in each
commodity. Note this can generate very large journal entries, if you commodity. Note this can generate very large journal entries, if you
have many foreign currency or investment transactions. have many foreign currency or investment transactions.
close usage close usage
If you split your journal files by time (eg yearly), you will typically If you split your journal files by time (eg yearly), you will typically
run this command at the end of the year, and save the closing transac- run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded. that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly; Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac- or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open- reports; you can exclude them with a query like not:desc:'(open-
ing|closing) balances'.) ing|closing) balances'.)
If you're running a business, you might also use this command to "close If you're running a business, you might also use this command to "close
the books" at the end of an accounting period, transferring income the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to statement account balances to retained earnings. (You may want to
change the equity account name to something like "equity:retained earn- change the equity account name to something like "equity:retained earn-
ings".) ings".)
By default, the closing transaction is dated yesterday, the balances By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN- dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
You can also use -p or date:PERIOD (any starting date is ignored). You can also use -p or date:PERIOD (any starting date is ignored).
Both transactions will include balance assertions for the closed/re- Both transactions will include balance assertions for the closed/re-
opened accounts. You probably shouldn't use status or realness filters opened accounts. You probably shouldn't use status or realness filters
(like -C or -R or status:) with this command, or the generated balance (like -C or -R or status:) with this command, or the generated balance
assertions will depend on these flags. Likewise, if you run this com- assertions will depend on these flags. Likewise, if you run this com-
mand with --auto, the balance assertions will probably always require mand with --auto, the balance assertions will probably always require
--auto. --auto.
Examples: Examples:
@ -2388,18 +2389,18 @@ COMMANDS
diff diff
diff diff
Compares a particular account's transactions in two input files. It Compares a particular account's transactions in two input files. It
shows any transactions to this account which are in one file but not in shows any transactions to this account which are in one file but not in
the other. the other.
More precisely, for each posting affecting this account in either file, More precisely, for each posting affecting this account in either file,
it looks for a corresponding posting in the other file which posts the it looks for a corresponding posting in the other file which posts the
same amount to the same account (ignoring date, description, etc.) same amount to the same account (ignoring date, description, etc.)
Since postings not transactions are compared, this also works when mul- Since postings not transactions are compared, this also works when mul-
tiple bank transactions have been combined into a single journal entry. tiple bank transactions have been combined into a single journal entry.
This is useful eg if you have downloaded an account's transactions from This is useful eg if you have downloaded an account's transactions from
your bank (eg as CSV data). When hledger and your bank disagree about your bank (eg as CSV data). When hledger and your bank disagree about
the account balance, you can compare the bank data with your journal to the account balance, you can compare the bank data with your journal to
find out the cause. find out the cause.
@ -2417,20 +2418,20 @@ COMMANDS
files files
files files
List all files included in the journal. With a REGEX argument, only List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown. file names matching the regular expression (case sensitive) are shown.
help help
help help
Show any of the hledger manuals. Show any of the hledger manuals.
The help command displays any of the main hledger manuals, in one of The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one. a full or partial manual name to select one.
hledger manuals are available in several formats. hledger help will hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man, use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can $PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags. force a particular viewer with the --info, --man, --pager, --cat flags.
Examples: Examples:
@ -2457,9 +2458,9 @@ COMMANDS
import import
import import
Read new transactions added to each FILE since last run, and add them Read new transactions added to each FILE since last run, and add them
to the main journal file. Or with --dry-run, just print the transac- to the main journal file. Or with --dry-run, just print the transac-
tions that would be added. Or with --catchup, just mark all of the tions that would be added. Or with --catchup, just mark all of the
FILEs' transactions as imported, without actually importing any. FILEs' transactions as imported, without actually importing any.
The input files are specified as arguments - no need to write -f before The input files are specified as arguments - no need to write -f before
@ -2470,36 +2471,36 @@ COMMANDS
ing transactions are always added to the input files in increasing date ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files. order, and by saving .latest.FILE state files.
The --dry-run output is in journal format, so you can filter it, eg to The --dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions: see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
Importing balance assignments Importing balance assignments
Entries added by import will have their posting amounts made explicit Entries added by import will have their posting amounts made explicit
(like hledger print -x). This means that any balance assignments in (like hledger print -x). This means that any balance assignments in
imported files must be evaluated; but, imported files don't get to see imported files must be evaluated; but, imported files don't get to see
the main file's account balances. As a result, importing entries with the main file's account balances. As a result, importing entries with
balance assignments (eg from an institution that provides only balances balance assignments (eg from an institution that provides only balances
and not posting amounts) will probably generate incorrect posting and not posting amounts) will probably generate incorrect posting
amounts. To avoid this problem, use print instead of import: amounts. To avoid this problem, use print instead of import:
$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
(If you think import should leave amounts implicit like print does, (If you think import should leave amounts implicit like print does,
please test it and send a pull request.) please test it and send a pull request.)
incomestatement incomestatement
incomestatement, is incomestatement, is
This command displays a simple income statement, showing revenues and This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu- top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements, un- with normal positive sign (like conventional financial statements, un-
like balance/print/register) (experimental). like balance/print/register) (experimental).
This command displays a simple income statement. It currently assumes This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.) (plural forms also allowed.)
$ hledger incomestatement $ hledger incomestatement
@ -2524,13 +2525,13 @@ COMMANDS
0 0
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical. Instead of abso- report mode with --change/--cumulative/--historical. Instead of abso-
lute values percentages can be displayed with -%. lute values percentages can be displayed with -%.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, html, and (experimen- tions The output formats supported are txt, csv, html, and (experimen-
tal) json. tal) json.
notes notes
@ -2558,10 +2559,10 @@ COMMANDS
prices prices
prices prices
Print market price directives from the journal. With --costs, also Print market price directives from the journal. With --costs, also
print synthetic market prices based on transaction prices. With --in- print synthetic market prices based on transaction prices. With --in-
verted-costs, also print inverse prices based on transaction prices. verted-costs, also print inverse prices based on transaction prices.
Prices (and postings providing prices) can be filtered by a query. Prices (and postings providing prices) can be filtered by a query.
Price amounts are always displayed with their full precision. Price amounts are always displayed with their full precision.
print print
@ -2569,11 +2570,11 @@ COMMANDS
Show transaction journal entries, sorted by date. Show transaction journal entries, sorted by date.
The print command displays full journal entries (transactions) from the The print command displays full journal entries (transactions) from the
journal file in date order, tidily formatted. With --date2, transac- journal file in date order, tidily formatted. With --date2, transac-
tions are sorted by secondary date instead. tions are sorted by secondary date instead.
print's output is always a valid hledger journal. print's output is always a valid hledger journal.
It preserves all transaction information, but it does not preserve di- It preserves all transaction information, but it does not preserve di-
rectives or inter-transaction comments rectives or inter-transaction comments
$ hledger print $ hledger print
@ -2600,43 +2601,43 @@ COMMANDS
Normally, the journal entry's explicit or implicit amount style is pre- Normally, the journal entry's explicit or implicit amount style is pre-
served. For example, when an amount is omitted in the journal, it will served. For example, when an amount is omitted in the journal, it will
not appear in the output. Similarly, when a transaction price is im- not appear in the output. Similarly, when a transaction price is im-
plied but not written, it will not appear in the output. You can use plied but not written, it will not appear in the output. You can use
the -x/--explicit flag to make all amounts and transaction prices ex- the -x/--explicit flag to make all amounts and transaction prices ex-
plicit, which can be useful for troubleshooting or for making your plicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors. -x is also journal more readable and robust against data entry errors. -x is also
implied by using any of -B,-V,-X,--value. implied by using any of -B,-V,-X,--value.
Note, -x/--explicit will cause postings with a multi-commodity amount Note, -x/--explicit will cause postings with a multi-commodity amount
(these can arise when a multi-commodity transaction has an implicit (these can arise when a multi-commodity transaction has an implicit
amount) to be split into multiple single-commodity postings, keeping amount) to be split into multiple single-commodity postings, keeping
the output parseable. the output parseable.
With -B/--cost, amounts with transaction prices are converted to cost With -B/--cost, amounts with transaction prices are converted to cost
using that price. This can be used for troubleshooting. using that price. This can be used for troubleshooting.
With -m/--match and a STR argument, print will show at most one trans- With -m/--match and a STR argument, print will show at most one trans-
action: the one one whose description is most similar to STR, and is action: the one one whose description is most similar to STR, and is
most recent. STR should contain at least two characters. If there is most recent. STR should contain at least two characters. If there is
no similar-enough match, no transaction will be shown. no similar-enough match, no transaction will be shown.
With --new, for each FILE being read, hledger reads (and writes) a spe- With --new, for each FILE being read, hledger reads (and writes) a spe-
cial state file (.latest.FILE in the same directory), containing the cial state file (.latest.FILE in the same directory), containing the
latest transaction date(s) that were seen last time FILE was read. latest transaction date(s) that were seen last time FILE was read.
When this file is found, only transactions with newer dates (and new When this file is found, only transactions with newer dates (and new
transactions on the latest date) are printed. This is useful for ig- transactions on the latest date) are printed. This is useful for ig-
noring already-seen entries in import data, such as downloaded CSV noring already-seen entries in import data, such as downloaded CSV
files. Eg: files. Eg:
$ hledger -f bank1.csv print --new $ hledger -f bank1.csv print --new
(shows transactions added since last print --new on this file) (shows transactions added since last print --new on this file)
This assumes that transactions added to FILE always have same or in- This assumes that transactions added to FILE always have same or in-
creasing dates, and that transactions on the same day do not get re- creasing dates, and that transactions on the same day do not get re-
ordered. See also the import command. ordered. See also the import command.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, and (experimental) tions The output formats supported are txt, csv, and (experimental)
json. json.
Here's an example of print's CSV output: Here's an example of print's CSV output:
@ -2655,20 +2656,20 @@ COMMANDS
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
o There is one CSV record per posting, with the parent transaction's o There is one CSV record per posting, with the parent transaction's
fields repeated. fields repeated.
o The "txnidx" (transaction index) field shows which postings belong to o The "txnidx" (transaction index) field shows which postings belong to
the same transaction. (This number might change if transactions are the same transaction. (This number might change if transactions are
reordered within the file, files are parsed/included in a different reordered within the file, files are parsed/included in a different
order, etc.) order, etc.)
o The amount is separated into "commodity" (the symbol) and "amount" o The amount is separated into "commodity" (the symbol) and "amount"
(numeric quantity) fields. (numeric quantity) fields.
o The numeric amount is repeated in either the "credit" or "debit" col- o The numeric amount is repeated in either the "credit" or "debit" col-
umn, for convenience. (Those names are not accurate in the account- umn, for convenience. (Those names are not accurate in the account-
ing sense; it just puts negative amounts under credit and zero or ing sense; it just puts negative amounts under credit and zero or
greater amounts under debit.) greater amounts under debit.)
print-unique print-unique
@ -2692,7 +2693,7 @@ COMMANDS
Show postings and their running total. Show postings and their running total.
The register command displays postings in date order, one per line, and The register command displays postings in date order, one per line, and
their running total. This is typically used with a query selecting a their running total. This is typically used with a query selecting a
particular account, to see that account's activity: particular account, to see that account's activity:
$ hledger register checking $ hledger register checking
@ -2703,8 +2704,8 @@ COMMANDS
With --date2, it shows and sorts by secondary date instead. With --date2, it shows and sorts by secondary date instead.
The --historical/-H flag adds the balance from any undisplayed prior The --historical/-H flag adds the balance from any undisplayed prior
postings to the running total. This is useful when you want to see postings to the running total. This is useful when you want to see
only recent activity, with a historically accurate running balance: only recent activity, with a historically accurate running balance:
$ hledger register checking -b 2008/6 --historical $ hledger register checking -b 2008/6 --historical
@ -2714,18 +2715,18 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed. The --depth option limits the amount of sub-account detail displayed.
The --average/-A flag shows the running average posting amount instead The --average/-A flag shows the running average posting amount instead
of the running total (so, the final number displayed is the average for of the running total (so, the final number displayed is the average for
the whole report period). This flag implies --empty (see below). It the whole report period). This flag implies --empty (see below). It
is affected by --historical. It works best when showing just one ac- is affected by --historical. It works best when showing just one ac-
count and one commodity. count and one commodity.
The --related/-r flag shows the other postings in the transactions of The --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown. the postings which would normally be shown.
The --invert flag negates all amounts. For example, it can be used on The --invert flag negates all amounts. For example, it can be used on
an income account where amounts are normally displayed as negative num- an income account where amounts are normally displayed as negative num-
bers. It's also useful to show postings on the checking account to- bers. It's also useful to show postings on the checking account to-
gether with the related account: gether with the related account:
$ hledger register --related --invert assets:checking $ hledger register --related --invert assets:checking
@ -2737,7 +2738,7 @@ COMMANDS
2008/01 income:salary $-1 $-1 2008/01 income:salary $-1 $-1
2008/06 income:gifts $-1 $-2 2008/06 income:gifts $-1 $-2
Periods with no activity, and summary postings with a zero amount, are Periods with no activity, and summary postings with a zero amount, are
not shown by default; use the --empty/-E flag to see them: not shown by default; use the --empty/-E flag to see them:
$ hledger register --monthly income -E $ hledger register --monthly income -E
@ -2754,7 +2755,7 @@ COMMANDS
2008/11 0 $-2 2008/11 0 $-2
2008/12 0 $-2 2008/12 0 $-2
Often, you'll want to see just one line per interval. The --depth op- Often, you'll want to see just one line per interval. The --depth op-
tion helps with this, causing subaccounts to be aggregated: tion helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h $ hledger register --monthly assets --depth 1h
@ -2762,17 +2763,17 @@ COMMANDS
2008/06 assets $-1 0 2008/06 assets $-1 0
2008/12 assets $-1 $-1 2008/12 assets $-1 $-1
Note when using report intervals, if you specify start/end dates these Note when using report intervals, if you specify start/end dates these
will be adjusted outward if necessary to contain a whole number of in- will be adjusted outward if necessary to contain a whole number of in-
tervals. This ensures that the first and last intervals are full tervals. This ensures that the first and last intervals are full
length and comparable to the others in the report. length and comparable to the others in the report.
Custom register output Custom register output
register uses the full terminal width by default, except on windows. register uses the full terminal width by default, except on windows.
You can override this by setting the COLUMNS environment variable (not You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option. a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a de- (about half of (width - 40) each). You can adjust this by adding a de-
scription width as part of --width's argument, comma-separated: --width scription width as part of --width's argument, comma-separated: --width
W,D . Here's a diagram (won't display correctly in --help): W,D . Here's a diagram (won't display correctly in --help):
@ -2791,27 +2792,27 @@ COMMANDS
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, and (experimental) tions The output formats supported are txt, csv, and (experimental)
json. json.
register-match register-match
register-match register-match
Print the one posting whose transaction description is closest to DESC, Print the one posting whose transaction description is closest to DESC,
in the style of the register command. If there are multiple equally in the style of the register command. If there are multiple equally
good matches, it shows the most recent. Query options (options, not good matches, it shows the most recent. Query options (options, not
arguments) can be used to restrict the search space. Helps ledger-au- arguments) can be used to restrict the search space. Helps ledger-au-
tosync detect already-seen transactions when importing. tosync detect already-seen transactions when importing.
rewrite rewrite
rewrite rewrite
Print all transactions, rewriting the postings of matched transactions. Print all transactions, rewriting the postings of matched transactions.
For now the only rewrite available is adding new postings, like print For now the only rewrite available is adding new postings, like print
--auto. --auto.
This is a start at a generic rewriter of transaction entries. It reads This is a start at a generic rewriter of transaction entries. It reads
the default journal and prints the transactions, like print, but adds the default journal and prints the transactions, like print, but adds
one or more specified postings to any transactions matching QUERY. The one or more specified postings to any transactions matching QUERY. The
posting amounts can be fixed, or a multiplier of the existing transac- posting amounts can be fixed, or a multiplier of the existing transac-
tion's first posting amount. tion's first posting amount.
Examples: Examples:
@ -2827,7 +2828,7 @@ COMMANDS
(reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:grocery) *0.25 ; reserve 25% for grocery
(reserve:) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery
Note the single quotes to protect the dollar sign from bash, and the Note the single quotes to protect the dollar sign from bash, and the
two spaces between account and amount. two spaces between account and amount.
More: More:
@ -2837,16 +2838,16 @@ COMMANDS
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
Argument for --add-posting option is a usual posting of transaction Argument for --add-posting option is a usual posting of transaction
with an exception for amount specification. More precisely, you can with an exception for amount specification. More precisely, you can
use '*' (star symbol) before the amount to indicate that that this is a use '*' (star symbol) before the amount to indicate that that this is a
factor for an amount of original matched posting. If the amount in- factor for an amount of original matched posting. If the amount in-
cludes a commodity name, the new posting amount will be in the new com- cludes a commodity name, the new posting amount will be in the new com-
modity; otherwise, it will be in the matched posting amount's commod- modity; otherwise, it will be in the matched posting amount's commod-
ity. ity.
Re-write rules in a file Re-write rules in a file
During the run this tool will execute so called "Automated Transac- During the run this tool will execute so called "Automated Transac-
tions" found in any journal it process. I.e instead of specifying this tions" found in any journal it process. I.e instead of specifying this
operations in command line you can put them in a journal file. operations in command line you can put them in a journal file.
@ -2861,7 +2862,7 @@ COMMANDS
budget:gifts *-1 budget:gifts *-1
assets:budget *1 assets:budget *1
Note that '=' (equality symbol) that is used instead of date in trans- Note that '=' (equality symbol) that is used instead of date in trans-
actions you usually write. It indicates the query by which you want to actions you usually write. It indicates the query by which you want to
match the posting to add new ones. match the posting to add new ones.
@ -2874,12 +2875,12 @@ COMMANDS
--add-posting 'assets:budget *1' \ --add-posting 'assets:budget *1' \
> rewritten-tidy-output.journal > rewritten-tidy-output.journal
It is important to understand that relative order of such entries in It is important to understand that relative order of such entries in
journal is important. You can re-use result of previously added post- journal is important. You can re-use result of previously added post-
ings. ings.
Diff output format Diff output format
To use this tool for batch modification of your journal files you may To use this tool for batch modification of your journal files you may
find useful output in form of unified diff. find useful output in form of unified diff.
$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
@ -2903,10 +2904,10 @@ COMMANDS
If you'll pass this through patch tool you'll get transactions contain- If you'll pass this through patch tool you'll get transactions contain-
ing the posting that matches your query be updated. Note that multiple ing the posting that matches your query be updated. Note that multiple
files might be update according to list of input files specified via files might be update according to list of input files specified via
--file options and include directives inside of these files. --file options and include directives inside of these files.
Be careful. Whole transaction being re-formatted in a style of output Be careful. Whole transaction being re-formatted in a style of output
from hledger print. from hledger print.
See also: See also:
@ -2914,48 +2915,48 @@ COMMANDS
https://github.com/simonmichael/hledger/issues/99 https://github.com/simonmichael/hledger/issues/99
rewrite vs. print --auto rewrite vs. print --auto
This command predates print --auto, and currently does much the same This command predates print --auto, and currently does much the same
thing, but with these differences: thing, but with these differences:
o with multiple files, rewrite lets rules in any file affect all other o with multiple files, rewrite lets rules in any file affect all other
files. print --auto uses standard directive scoping; rules affect files. print --auto uses standard directive scoping; rules affect
only child files. only child files.
o rewrite's query limits which transactions can be rewritten; all are o rewrite's query limits which transactions can be rewritten; all are
printed. print --auto's query limits which transactions are printed. printed. print --auto's query limits which transactions are printed.
o rewrite applies rules specified on command line or in the journal. o rewrite applies rules specified on command line or in the journal.
print --auto applies rules specified in the journal. print --auto applies rules specified in the journal.
roi roi
roi roi
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
on your investments. on your investments.
This command assumes that you have account(s) that hold nothing but This command assumes that you have account(s) that hold nothing but
your investments and whenever you record current appraisal/valuation of your investments and whenever you record current appraisal/valuation of
these investments you offset unrealized profit and loss into account(s) these investments you offset unrealized profit and loss into account(s)
that, again, hold nothing but unrealized profit and loss. that, again, hold nothing but unrealized profit and loss.
Any transactions affecting balance of investment account(s) and not Any transactions affecting balance of investment account(s) and not
originating from unrealized profit and loss account(s) are assumed to originating from unrealized profit and loss account(s) are assumed to
be your investments or withdrawals. be your investments or withdrawals.
At a minimum, you need to supply a query (which could be just an ac- At a minimum, you need to supply a query (which could be just an ac-
count name) to select your investments with --inv, and another query to count name) to select your investments with --inv, and another query to
identify your profit and loss transactions with --pnl. identify your profit and loss transactions with --pnl.
It will compute and display the internalized rate of return (IRR) and It will compute and display the internalized rate of return (IRR) and
time-weighted rate of return (TWR) for your investments for the time time-weighted rate of return (TWR) for your investments for the time
period requested. Both rates of return are annualized before display, period requested. Both rates of return are annualized before display,
regardless of the length of reporting interval. regardless of the length of reporting interval.
stats stats
stats stats
Show some journal statistics. Show some journal statistics.
The stats command displays summary information for the whole journal, The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report or a matched part of it. With a reporting interval, it shows a report
for each report period. for each report period.
Example: Example:
@ -2973,14 +2974,14 @@ COMMANDS
Commodities : 1 ($) Commodities : 1 ($)
Market prices : 12 ($) Market prices : 12 ($)
This command also supports output destination and output format selec- This command also supports output destination and output format selec-
tion. tion.
tags tags
tags tags
List all the tag names used in the journal. With a TAGREGEX argument, List all the tag names used in the journal. With a TAGREGEX argument,
only tag names matching the regular expression (case insensitive) are only tag names matching the regular expression (case insensitive) are
shown. With QUERY arguments, only transactions matching the query are shown. With QUERY arguments, only transactions matching the query are
considered. With --values flag, the tags' unique values are listed in- considered. With --values flag, the tags' unique values are listed in-
stead. stead.
@ -2988,13 +2989,13 @@ COMMANDS
test test
Run built-in unit tests. Run built-in unit tests.
This command runs the unit tests built in to hledger and hledger-lib, This command runs the unit tests built in to hledger and hledger-lib,
printing the results on stdout. If any test fails, the exit code will printing the results on stdout. If any test fails, the exit code will
be non-zero. be non-zero.
This is mainly used by hledger developers, but you can also use it to This is mainly used by hledger developers, but you can also use it to
sanity-check the installed hledger executable on your platform. All sanity-check the installed hledger executable on your platform. All
tests are expected to pass - if you ever see a failure, please report tests are expected to pass - if you ever see a failure, please report
as a bug! as a bug!
This command also accepts tasty test runner options, written after a -- This command also accepts tasty test runner options, written after a --
@ -3003,35 +3004,35 @@ COMMANDS
$ hledger test -- -pData.Amount --color=never $ hledger test -- -pData.Amount --color=never
For help on these, see https://github.com/feuerbach/tasty#options (-- For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them). --help currently doesn't show them).
Add-on Commands Add-on Commands
hledger also searches for external add-on commands, and will include hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten- whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
Add-ons can be invoked like any hledger command, but there are a few Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed, things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help. hledger-web's help.
o Flags specific to the add-on must have a preceding -- to hide them o Flags specific to the add-on must have a preceding -- to hide them
from hledger. So hledger web --serve --port 9000 will be rejected; from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000. you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred: hledger-web --serve o You can always run add-ons directly if preferred: hledger-web --serve
--port 9000. --port 9000.
Add-ons are a relatively easy way to add local features or experiment Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell with new ideas. They can be written in any language, but haskell
scripts have a big advantage: they can use the same hledger (and scripts have a big advantage: they can use the same hledger (and
haskell) library functions that built-in commands do, for command-line haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc. options, journal parsing, reporting, etc.
Two important add-ons are the hledger-ui and hledger-web user inter- Two important add-ons are the hledger-ui and hledger-web user inter-
faces. These are maintained and released along with hledger: faces. These are maintained and released along with hledger:
ui ui
@ -3050,23 +3051,23 @@ COMMANDS
hledger-interest generates interest transactions for an account accord- hledger-interest generates interest transactions for an account accord-
ing to various schemes. ing to various schemes.
A few more experimental or old add-ons can be found in hledger's bin/ A few more experimental or old add-ons can be found in hledger's bin/
directory. These are typically prototypes and not guaranteed to work. directory. These are typically prototypes and not guaranteed to work.
ENVIRONMENT ENVIRONMENT
COLUMNS The screen width used by the register command. Default: the COLUMNS The screen width used by the register command. Default: the
full terminal width. full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default: LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal). nal).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur- trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal. rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing vironment.plist file containing
@ -3077,13 +3078,13 @@ ENVIRONMENT
To see the effect you may need to killall Dock, or reboot. To see the effect you may need to killall Dock, or reboot.
FILES FILES
Reads data from one or more files in hledger journal, timeclock, time- Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). C:/Users/USER/.hledger.journal).
LIMITATIONS LIMITATIONS
The need to precede addon command options with -- when invoked from The need to precede addon command options with -- when invoked from
hledger is awkward. hledger is awkward.
When input data contains non-ascii characters, a suitable system locale When input data contains non-ascii characters, a suitable system locale
@ -3099,33 +3100,33 @@ LIMITATIONS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add. add.
Not all of Ledger's journal file syntax is supported. See file format Not all of Ledger's journal file syntax is supported. See file format
differences. differences.
On large data files, hledger is slower and uses more memory than On large data files, hledger is slower and uses more memory than
Ledger. Ledger.
TROUBLESHOOTING TROUBLESHOOTING
Here are some issues you might encounter when you run hledger (and re- Here are some issues you might encounter when you run hledger (and re-
member you can also seek help from the IRC channel, mail list or bug member you can also seek help from the IRC channel, mail list or bug
tracker): tracker):
Successfully installed, but "No command 'hledger' found" Successfully installed, but "No command 'hledger' found"
stack and cabal install binaries into a special directory, which should stack and cabal install binaries into a special directory, which should
be added to your PATH environment variable. Eg on unix-like systems, be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively. that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file I set a custom LEDGER_FILE, but hledger is still using the default file
LEDGER_FILE should be a real environment variable, not just a shell LEDGER_FILE should be a real environment variable, not just a shell
variable. The command env | grep LEDGER_FILE should show it. You may variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation. need to use export. Here's an explanation.
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup- also configure it temporarily. The locale may need to be one that sup-
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet). I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu Here's an example of setting the locale temporarily, on ubuntu
@ -3144,7 +3145,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login $ bash --login
If we preferred to use eg fr_FR.utf8, we might have to install that If we preferred to use eg fr_FR.utf8, we might have to install that
first: first:
$ apt-get install language-pack-fr $ apt-get install language-pack-fr
@ -3165,7 +3166,7 @@ TROUBLESHOOTING
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -3179,7 +3180,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)