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

;update manuals

Browse Source
This commit is contained in:
Simon Michael 2020-11-09 17:13:57 -08:00
parent 94b01dd19d
commit 86fac4236d
6 changed files with 336 additions and 316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
hledger-lib/hledger_journal.5
View File

@ -584,7 +584,8 @@ commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
\f[R] \f[R]
.fi .fi
.SS Amount display style .PP
.SS Commodity display style
.PP .PP
For each commodity, hledger chooses a consistent format to use when For each commodity, hledger chooses a consistent format to use when
displaying amounts. displaying amounts.
@ -613,11 +614,10 @@ 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 .PP
hledger uses banker\[aq]s rounding: it rounds to the nearest even Note, 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]). 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 (Guaranteed since hledger 1.17.1; in older versions this could vary if
built with an old version of Decimal (<0.5.1); since 1.17.1 it\[aq]s hledger was built with Decimal < 0.5.1.)
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
@ -1198,7 +1198,7 @@ your data.
(Without this, hledger will parse both \f[C]1,000\f[R] and (Without this, hledger will parse both \f[C]1,000\f[R] and
\f[C]1.000\f[R] as 1). \f[C]1.000\f[R] as 1).
.IP "3." 3 .IP "3." 3
It declares the amount display style to use in output - decimal and It declares a commodity\[aq]s display style in output - decimal and
digit group marks, number of decimal places, symbol placement etc. digit group marks, number of decimal places, symbol placement etc.
.PP .PP
You are likely to run into one of the problems solved by commodity You are likely to run into one of the problems solved by commodity
@ -1244,7 +1244,7 @@ followed by 0 or more decimal digits.
.PP .PP
Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with
zero decimal digits is \[dq]0\[dq]. zero decimal digits is \[dq]0\[dq].
(More at Amount display style.) (More at Commodity 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

202
hledger-lib/hledger_journal.info
View File

@ -487,10 +487,10 @@ EUR 1E3
* Menu: * Menu:
* Digit group marks:: * Digit group marks::
* Amount display style:: * Commodity display style::
 
File: hledger_journal.info, Node: Digit group marks, Next: Amount display style, Up: Amounts File: hledger_journal.info, Node: Digit group marks, Next: Commodity display style, Up: Amounts
1.8.1 Digit group marks 1.8.1 Digit group marks
----------------------- -----------------------
@ -523,10 +523,10 @@ commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
 
File: hledger_journal.info, Node: Amount display style, Prev: Digit group marks, Up: Amounts File: hledger_journal.info, Node: Commodity display style, Prev: Digit group marks, Up: Amounts
1.8.2 Amount display style 1.8.2 Commodity display style
-------------------------- -----------------------------
For each commodity, hledger chooses a consistent format to use when For each commodity, hledger chooses a consistent format to use when
displaying amounts. (Except price amounts, which are always displayed displaying amounts. (Except price amounts, which are always displayed
@ -553,10 +553,10 @@ 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, Note, hledger uses banker's rounding: it rounds to the nearest even
eg 0.5 displayed with zero decimal places is "0"). (Note, prior to number, eg 0.5 displayed with zero decimal places is "0"). (Guaranteed
hledger 1.17.1 this could vary if hledger happened to be built with an since hledger 1.17.1; in older versions this could vary if hledger was
old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.) built with Decimal < 0.5.1.)
 
File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Transactions File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Transactions
@ -1079,7 +1079,7 @@ The 'commodity' directive has several functions:
formats in your data. (Without this, hledger will parse both formats in your data. (Without this, hledger will parse both
'1,000' and '1.000' as 1). '1,000' and '1.000' as 1).
3. It declares the amount display style to use in output - decimal and 3. It declares a commodity's display style 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 You are likely to run into one of the problems solved by commodity
@ -1114,7 +1114,7 @@ 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 Note hledger normally uses banker's rounding, so 0.5 displayed with
zero decimal digits is "0". (More at Amount display style.) zero decimal digits is "0". (More at Commodity display style.)
 
File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: Directives File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: Directives
@ -1889,96 +1889,96 @@ Node: Account names15177
Ref: #account-names15318 Ref: #account-names15318
Node: Amounts15805 Node: Amounts15805
Ref: #amounts15944 Ref: #amounts15944
Node: Digit group marks17052 Node: Digit group marks17055
Ref: #digit-group-marks17200 Ref: #digit-group-marks17206
Node: Amount display style18138 Node: Commodity display style18144
Ref: #amount-display-style18292 Ref: #commodity-display-style18307
Node: Transaction prices19729 Node: Transaction prices19711
Ref: #transaction-prices19901 Ref: #transaction-prices19883
Node: Lot prices and lot dates22332 Node: Lot prices and lot dates22314
Ref: #lot-prices-and-lot-dates22529 Ref: #lot-prices-and-lot-dates22511
Node: Balance assertions23017 Node: Balance assertions22999
Ref: #balance-assertions23203 Ref: #balance-assertions23185
Node: Assertions and ordering24236 Node: Assertions and ordering24218
Ref: #assertions-and-ordering24424 Ref: #assertions-and-ordering24406
Node: Assertions and included files25124 Node: Assertions and included files25106
Ref: #assertions-and-included-files25367 Ref: #assertions-and-included-files25349
Node: Assertions and multiple -f options25700 Node: Assertions and multiple -f options25682
Ref: #assertions-and-multiple--f-options25956 Ref: #assertions-and-multiple--f-options25938
Node: Assertions and commodities26088 Node: Assertions and commodities26070
Ref: #assertions-and-commodities26320 Ref: #assertions-and-commodities26302
Node: Assertions and prices27477 Node: Assertions and prices27459
Ref: #assertions-and-prices27691 Ref: #assertions-and-prices27673
Node: Assertions and subaccounts28131 Node: Assertions and subaccounts28113
Ref: #assertions-and-subaccounts28360 Ref: #assertions-and-subaccounts28342
Node: Assertions and virtual postings28684 Node: Assertions and virtual postings28666
Ref: #assertions-and-virtual-postings28926 Ref: #assertions-and-virtual-postings28908
Node: Assertions and precision29068 Node: Assertions and precision29050
Ref: #assertions-and-precision29261 Ref: #assertions-and-precision29243
Node: Balance assignments29528 Node: Balance assignments29510
Ref: #balance-assignments29702 Ref: #balance-assignments29684
Node: Balance assignments and prices30866 Node: Balance assignments and prices30848
Ref: #balance-assignments-and-prices31038 Ref: #balance-assignments-and-prices31020
Node: Directives31262 Node: Directives31244
Ref: #directives31421 Ref: #directives31403
Node: Directives and multiple files36919 Node: Directives and multiple files36901
Ref: #directives-and-multiple-files37102 Ref: #directives-and-multiple-files37084
Node: Comment blocks37766 Node: Comment blocks37748
Ref: #comment-blocks37949 Ref: #comment-blocks37931
Node: Including other files38125 Node: Including other files38107
Ref: #including-other-files38305 Ref: #including-other-files38287
Node: Default year39229 Node: Default year39211
Ref: #default-year39398 Ref: #default-year39380
Node: Declaring commodities39805 Node: Declaring commodities39787
Ref: #declaring-commodities39988 Ref: #declaring-commodities39970
Node: Default commodity41794 Node: Default commodity41775
Ref: #default-commodity41980 Ref: #default-commodity41961
Node: Declaring market prices42869 Node: Declaring market prices42850
Ref: #declaring-market-prices43064 Ref: #declaring-market-prices43045
Node: Declaring accounts43921 Node: Declaring accounts43902
Ref: #declaring-accounts44107 Ref: #declaring-accounts44088
Node: Account comments45032 Node: Account comments45013
Ref: #account-comments45195 Ref: #account-comments45176
Node: Account subdirectives45619 Node: Account subdirectives45600
Ref: #account-subdirectives45814 Ref: #account-subdirectives45795
Node: Account types46127 Node: Account types46108
Ref: #account-types46311 Ref: #account-types46292
Node: Account display order49357 Node: Account display order49338
Ref: #account-display-order49527 Ref: #account-display-order49508
Node: Rewriting accounts50678 Node: Rewriting accounts50659
Ref: #rewriting-accounts50863 Ref: #rewriting-accounts50844
Node: Basic aliases51620 Node: Basic aliases51601
Ref: #basic-aliases51766 Ref: #basic-aliases51747
Node: Regex aliases52470 Node: Regex aliases52451
Ref: #regex-aliases52642 Ref: #regex-aliases52623
Node: Combining aliases53361 Node: Combining aliases53342
Ref: #combining-aliases53554 Ref: #combining-aliases53535
Node: Aliases and multiple files54830 Node: Aliases and multiple files54811
Ref: #aliases-and-multiple-files55039 Ref: #aliases-and-multiple-files55020
Node: end aliases55618 Node: end aliases55599
Ref: #end-aliases55775 Ref: #end-aliases55756
Node: Default parent account55876 Node: Default parent account55857
Ref: #default-parent-account56044 Ref: #default-parent-account56025
Node: Periodic transactions56928 Node: Periodic transactions56909
Ref: #periodic-transactions57103 Ref: #periodic-transactions57084
Node: Periodic rule syntax58975 Node: Periodic rule syntax58956
Ref: #periodic-rule-syntax59181 Ref: #periodic-rule-syntax59162
Node: Two spaces between period expression and description!59885 Node: Two spaces between period expression and description!59866
Ref: #two-spaces-between-period-expression-and-description60204 Ref: #two-spaces-between-period-expression-and-description60185
Node: Forecasting with periodic transactions60888 Node: Forecasting with periodic transactions60869
Ref: #forecasting-with-periodic-transactions61193 Ref: #forecasting-with-periodic-transactions61174
Node: Budgeting with periodic transactions63248 Node: Budgeting with periodic transactions63229
Ref: #budgeting-with-periodic-transactions63487 Ref: #budgeting-with-periodic-transactions63468
Node: Auto postings63896 Node: Auto postings63877
Ref: #auto-postings64036 Ref: #auto-postings64017
Node: Auto postings and multiple files66215 Node: Auto postings and multiple files66196
Ref: #auto-postings-and-multiple-files66419 Ref: #auto-postings-and-multiple-files66400
Node: Auto postings and dates66628 Node: Auto postings and dates66609
Ref: #auto-postings-and-dates66902 Ref: #auto-postings-and-dates66883
Node: Auto postings and transaction balancing / inferred amounts / balance assertions67077 Node: Auto postings and transaction balancing / inferred amounts / balance assertions67058
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67428 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67409
Node: Auto posting tags67770 Node: Auto posting tags67751
Ref: #auto-posting-tags67985 Ref: #auto-posting-tags67966
 
End Tag Table End Tag Table

14
hledger-lib/hledger_journal.txt
View File

@ -411,7 +411,7 @@ FILE FORMAT
commodity INR 9,99,99,999.00 commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
Amount display style Commodity display style
For each commodity, hledger chooses a consistent format to use when For each commodity, hledger chooses a consistent format to use when
displaying amounts. (Except price amounts, which are always displayed displaying amounts. (Except price amounts, which are always displayed
as written). The display style is chosen as follows: as written). The display style is chosen as follows:
@ -437,10 +437,10 @@ 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, Note, hledger uses banker's rounding: it rounds to the nearest even
eg 0.5 displayed with zero decimal places is "0"). (Note, prior to number, eg 0.5 displayed with zero decimal places is "0"). (Guaranteed
hledger 1.17.1 this could vary if hledger happened to be built with an since hledger 1.17.1; in older versions this could vary if hledger was
old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.) built with Decimal < 0.5.1.)
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-
@ -838,7 +838,7 @@ FILE FORMAT
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 a commodity's display style 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-
@ -873,7 +873,7 @@ FILE FORMAT
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 Note hledger normally uses banker's rounding, so 0.5 displayed with
zero decimal digits is "0". (More at Amount display style.) zero decimal digits is "0". (More at Commodity 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-

4
hledger/hledger.1
View File

@ -3805,6 +3805,10 @@ $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
.PP .PP
(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.)
.SS Commodity display styles
.PP
Imported amounts will be formatted according to the canonical commodity
styles (declared or inferred) in the main journal file.
.SS incomestatement .SS incomestatement
.PP .PP
incomestatement, is incomestatement, is

122
hledger/hledger.info
View File

@ -3218,9 +3218,10 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
* Menu: * Menu:
* Importing balance assignments:: * Importing balance assignments::
* Commodity display styles::
 
File: hledger.info, Node: Importing balance assignments, Up: import File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Up: import
3.18.1 Importing balance assignments 3.18.1 Importing balance assignments
------------------------------------ ------------------------------------
@ -3238,6 +3239,15 @@ $ 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.)

File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import
3.18.2 Commodity display styles
-------------------------------
Imported amounts will be formatted according to the canonical commodity
styles (declared or inferred) in the main journal file.
 
File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS
@ -4252,60 +4262,62 @@ Node: help111433
Ref: #help111533 Ref: #help111533
Node: import112614 Node: import112614
Ref: #import112728 Ref: #import112728
Node: Importing balance assignments113621 Node: Importing balance assignments113650
Ref: #importing-balance-assignments113769 Ref: #importing-balance-assignments113831
Node: incomestatement114418 Node: Commodity display styles114480
Ref: #incomestatement114551 Ref: #commodity-display-styles114651
Node: notes115896 Node: incomestatement114780
Ref: #notes116009 Ref: #incomestatement114913
Node: payees116377 Node: notes116258
Ref: #payees116483 Ref: #notes116371
Node: prices116903 Node: payees116739
Ref: #prices117009 Ref: #payees116845
Node: print117350 Node: prices117265
Ref: #print117460 Ref: #prices117371
Node: print-unique122256 Node: print117712
Ref: #print-unique122382 Ref: #print117822
Node: register122667 Node: print-unique122618
Ref: #register122794 Ref: #print-unique122744
Node: Custom register output127243 Node: register123029
Ref: #custom-register-output127372 Ref: #register123156
Node: register-match128709 Node: Custom register output127605
Ref: #register-match128843 Ref: #custom-register-output127734
Node: rewrite129194 Node: register-match129071
Ref: #rewrite129309 Ref: #register-match129205
Node: Re-write rules in a file131164 Node: rewrite129556
Ref: #re-write-rules-in-a-file131298 Ref: #rewrite129671
Node: Diff output format132508 Node: Re-write rules in a file131526
Ref: #diff-output-format132677 Ref: #re-write-rules-in-a-file131660
Node: rewrite vs print --auto133769 Node: Diff output format132870
Ref: #rewrite-vs.-print---auto133948 Ref: #diff-output-format133039
Node: roi134504 Node: rewrite vs print --auto134131
Ref: #roi134602 Ref: #rewrite-vs.-print---auto134310
Node: stats135614 Node: roi134866
Ref: #stats135713 Ref: #roi134964
Node: tags136501 Node: stats135976
Ref: #tags136599 Ref: #stats136075
Node: test137118 Node: tags136863
Ref: #test137226 Ref: #tags136961
Node: Add-on commands137973 Node: test137480
Ref: #add-on-commands138090 Ref: #test137588
Node: ui139433 Node: Add-on commands138335
Ref: #ui139521 Ref: #add-on-commands138452
Node: web139575 Node: ui139795
Ref: #web139678 Ref: #ui139883
Node: iadd139794 Node: web139937
Ref: #iadd139905 Ref: #web140040
Node: interest139987 Node: iadd140156
Ref: #interest140094 Ref: #iadd140267
Node: ENVIRONMENT140334 Node: interest140349
Ref: #environment140446 Ref: #interest140456
Node: FILES141431 Node: ENVIRONMENT140696
Ref: #files-1141534 Ref: #environment140808
Node: LIMITATIONS141747 Node: FILES141793
Ref: #limitations141866 Ref: #files-1141896
Node: TROUBLESHOOTING142608 Node: LIMITATIONS142109
Ref: #troubleshooting142721 Ref: #limitations142228
Node: TROUBLESHOOTING142970
Ref: #troubleshooting143083
 
End Tag Table End Tag Table

296
hledger/hledger.txt
View File

@ -2777,15 +2777,19 @@ COMMANDS
(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.)
Commodity display styles
Imported amounts will be formatted according to the canonical commodity
styles (declared or inferred) in the main journal file.
incomestatement incomestatement
incomestatement, is incomestatement, is
This command displays an income statement, showing revenues and ex- This command displays an income statement, showing revenues and ex-
penses during one or more periods. Amounts are shown with normal posi- penses during one or more periods. Amounts are shown with normal posi-
tive sign, as in conventional financial statements. tive sign, as in conventional financial statements.
The revenue and expense accounts shown are those accounts declared with The revenue and expense accounts shown are those accounts declared with
the Revenue or Expense type, or otherwise all accounts under a top- the Revenue or Expense type, or otherwise all accounts under a top-
level revenue or income or expense account (case insensitive, plurals level revenue or income or expense account (case insensitive, plurals
allowed). allowed).
Example: Example:
@ -2812,13 +2816,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
@ -2826,8 +2830,8 @@ COMMANDS
List the unique notes that appear in transactions. List the unique notes that appear in transactions.
This command lists the unique notes that appear in transactions, in al- This command lists the unique notes that appear in transactions, in al-
phabetic order. You can add a query to select a subset of transac- phabetic order. You can add a query to select a subset of transac-
tions. The note is the part of the transaction description after a | tions. The note is the part of the transaction description after a |
character (or if there is no |, the whole description). character (or if there is no |, the whole description).
Example: Example:
@ -2841,8 +2845,8 @@ COMMANDS
List the unique payee/payer names that appear in transactions. List the unique payee/payer names that appear in transactions.
This command lists the unique payee/payer names that appear in transac- This command lists the unique payee/payer names that appear in transac-
tions, in alphabetic order. You can add a query to select a subset of tions, in alphabetic order. You can add a query to select a subset of
transactions. The payee/payer is the part of the transaction descrip- transactions. The payee/payer is the part of the transaction descrip-
tion before a | character (or if there is no |, the whole description). tion before a | character (or if there is no |, the whole description).
Example: Example:
@ -2854,10 +2858,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
@ -2865,11 +2869,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
@ -2896,43 +2900,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 and sql. json and sql.
Here's an example of print's CSV output: Here's an example of print's CSV output:
@ -2951,20 +2955,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
@ -2988,14 +2992,14 @@ COMMANDS
Show postings and their running total. Show postings and their running total.
The register command displays matched postings, across all accounts, in The register command displays matched postings, across all accounts, in
date order, with their running total or running historical balance. date order, with their running total or running historical balance.
(See also the aregister command, which shows matched transactions in a (See also the aregister command, which shows matched transactions in a
specific account.) specific account.)
register normally shows line per posting, but note that multi-commodity register normally shows line per posting, but note that multi-commodity
amounts will occupy multiple lines (one line per commodity). amounts will occupy multiple lines (one line per commodity).
It is typically used with a query selecting a particular account, to It is typically used with a query selecting a particular account, to
see that account's activity: see that account's activity:
$ hledger register checking $ hledger register checking
@ -3006,8 +3010,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
@ -3017,18 +3021,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
@ -3040,7 +3044,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
@ -3057,7 +3061,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
@ -3065,17 +3069,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):
@ -3094,27 +3098,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:
@ -3130,7 +3134,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:
@ -3140,16 +3144,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.
@ -3164,7 +3168,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.
@ -3177,12 +3181,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'
@ -3206,10 +3210,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:
@ -3217,48 +3221,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:
@ -3276,35 +3280,35 @@ 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 the unique tag names used in the journal. With a TAGREGEX argu- List the unique tag names used in the journal. With a TAGREGEX argu-
ment, only tag names matching the regular expression (case insensitive) ment, 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. are considered.
With the --values flag, the tags' unique values are listed instead. With the --values flag, the tags' unique values are listed instead.
With --parsed flag, all tags or values are shown in the order they are With --parsed flag, all tags or values are shown in the order they are
parsed from the input data, including duplicates. parsed from the input data, including duplicates.
With -E/--empty, any blank/empty values will also be shown, otherwise With -E/--empty, any blank/empty values will also be shown, otherwise
they are omitted. they are omitted.
test test
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 --
@ -3313,35 +3317,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
@ -3360,20 +3364,20 @@ 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
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
@ -3383,21 +3387,21 @@ 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.
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.
NO_COLOR If this variable exists with any value, hledger will not use NO_COLOR If this variable exists with any value, hledger will not use
ANSI color codes in terminal output. This overrides the ANSI color codes in terminal output. This overrides the
--color/--colour option. --color/--colour option.
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
@ -3413,36 +3417,36 @@ 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.
Getting errors like "Illegal byte sequence" or "Invalid or incomplete Getting errors like "Illegal byte sequence" or "Invalid or incomplete
multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- multibyte or wide character" or "commitAndReleaseBuffer: invalid argu-
ment (invalid character)" ment (invalid character)"
Programs compiled with GHC (hledger, haskell build tools, etc.) need to Programs compiled with GHC (hledger, haskell build tools, etc.) need to
have a UTF-8-aware locale configured in the environment, otherwise they have a UTF-8-aware locale configured in the environment, otherwise they
will fail with these kinds of errors when they encounter non-ascii will fail with these kinds of errors when they encounter non-ascii
characters. characters.
To fix it, set the LANG environment variable to some locale which sup- To fix it, set the LANG environment variable to some locale which sup-
ports UTF-8. The locale you choose must be installed on your system. ports UTF-8. The locale you choose must be installed on your system.
Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux: Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
@ -3457,8 +3461,8 @@ TROUBLESHOOTING
POSIX POSIX
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
If available, C.UTF-8 will also work. If your preferred locale isn't If available, C.UTF-8 will also work. If your preferred locale isn't
listed by locale -a, you might need to install it. Eg on Ubuntu/De- listed by locale -a, you might need to install it. Eg on Ubuntu/De-
bian: bian:
$ apt-get install language-pack-fr $ apt-get install language-pack-fr
@ -3478,8 +3482,8 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.utf8" >>~/.bash_profile $ echo "export LANG=en_US.utf8" >>~/.bash_profile
$ bash --login $ bash --login
Exact spelling and capitalisation may be important. Note the differ- Exact spelling and capitalisation may be important. Note the differ-
ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
variant spellings, but others (eg macos) require it to be exact: variant spellings, but others (eg macos) require it to be exact:
$ locale -a | grep -iE en_us.*utf $ locale -a | grep -iE en_us.*utf
@ -3489,7 +3493,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)
@ -3503,7 +3507,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)