From 1a606870caf98214e3f5e1cb9c3e00ed4ebc8278 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 19 Mar 2020 16:05:52 -0700 Subject: [PATCH] ;regen docs --- hledger-lib/hledger_journal.5 | 10 + hledger-lib/hledger_journal.info | 176 ++++----- hledger-lib/hledger_journal.txt | 197 +++++----- hledger/Hledger/Cli/Commands/Balance.txt | 7 +- hledger/hledger.1 | 8 +- hledger/hledger.info | 174 ++++----- hledger/hledger.txt | 461 ++++++++++++----------- 7 files changed, 531 insertions(+), 502 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index b43502d59..51588d2a3 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -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. If you want to see fewer decimal places in reports, use a commodity 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 .PP 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. The number must include a decimal mark: either a period or a comma, 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 .PP The \f[C]D\f[R] directive sets a default commodity, to be used for diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index d59553d65..90eccfd6d 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -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 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 @@ -1070,6 +1075,9 @@ commodity INR significant. The number must include a decimal mark: either a period or 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 @@ -1821,90 +1829,90 @@ Node: Digit group marks16739 Ref: #digit-group-marks16887 Node: Amount display style17825 Ref: #amount-display-style17979 -Node: Transaction prices19140 -Ref: #transaction-prices19306 -Node: Balance Assertions21572 -Ref: #balance-assertions21752 -Node: Assertions and ordering22785 -Ref: #assertions-and-ordering22973 -Node: Assertions and included files23673 -Ref: #assertions-and-included-files23916 -Node: Assertions and multiple -f options24249 -Ref: #assertions-and-multiple--f-options24505 -Node: Assertions and commodities24637 -Ref: #assertions-and-commodities24869 -Node: Assertions and prices26026 -Ref: #assertions-and-prices26240 -Node: Assertions and subaccounts26680 -Ref: #assertions-and-subaccounts26909 -Node: Assertions and virtual postings27233 -Ref: #assertions-and-virtual-postings27475 -Node: Assertions and precision27617 -Ref: #assertions-and-precision27810 -Node: Balance Assignments28077 -Ref: #balance-assignments28251 -Node: Balance assignments and prices29415 -Ref: #balance-assignments-and-prices29587 -Node: Directives29811 -Ref: #directives29970 -Node: Directives and multiple files35651 -Ref: #directives-and-multiple-files35834 -Node: Comment blocks36498 -Ref: #comment-blocks36681 -Node: Including other files36857 -Ref: #including-other-files37037 -Node: Default year37445 -Ref: #default-year37614 -Node: Declaring commodities38021 -Ref: #declaring-commodities38204 -Node: Default commodity39877 -Ref: #default-commodity40053 -Node: Market prices40942 -Ref: #market-prices41107 -Node: Declaring accounts41948 -Ref: #declaring-accounts42124 -Node: Account comments43049 -Ref: #account-comments43212 -Node: Account subdirectives43636 -Ref: #account-subdirectives43831 -Node: Account types44144 -Ref: #account-types44328 -Node: Account display order45967 -Ref: #account-display-order46137 -Node: Rewriting accounts47288 -Ref: #rewriting-accounts47473 -Node: Basic aliases48230 -Ref: #basic-aliases48376 -Node: Regex aliases49080 -Ref: #regex-aliases49252 -Node: Combining aliases49970 -Ref: #combining-aliases50163 -Node: Aliases and multiple files51439 -Ref: #aliases-and-multiple-files51648 -Node: end aliases52227 -Ref: #end-aliases52384 -Node: Default parent account52485 -Ref: #default-parent-account52653 -Node: Periodic transactions53537 -Ref: #periodic-transactions53712 -Node: Periodic rule syntax55584 -Ref: #periodic-rule-syntax55790 -Node: Two spaces between period expression and description!56494 -Ref: #two-spaces-between-period-expression-and-description56813 -Node: Forecasting with periodic transactions57497 -Ref: #forecasting-with-periodic-transactions57802 -Node: Budgeting with periodic transactions59828 -Ref: #budgeting-with-periodic-transactions60067 -Node: Auto postings60516 -Ref: #auto-postings60656 -Node: Auto postings and multiple files62835 -Ref: #auto-postings-and-multiple-files63039 -Node: Auto postings and dates63248 -Ref: #auto-postings-and-dates63522 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions63697 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64048 -Node: Auto posting tags64390 -Ref: #auto-posting-tags64605 +Node: Transaction prices19417 +Ref: #transaction-prices19583 +Node: Balance Assertions21849 +Ref: #balance-assertions22029 +Node: Assertions and ordering23062 +Ref: #assertions-and-ordering23250 +Node: Assertions and included files23950 +Ref: #assertions-and-included-files24193 +Node: Assertions and multiple -f options24526 +Ref: #assertions-and-multiple--f-options24782 +Node: Assertions and commodities24914 +Ref: #assertions-and-commodities25146 +Node: Assertions and prices26303 +Ref: #assertions-and-prices26517 +Node: Assertions and subaccounts26957 +Ref: #assertions-and-subaccounts27186 +Node: Assertions and virtual postings27510 +Ref: #assertions-and-virtual-postings27752 +Node: Assertions and precision27894 +Ref: #assertions-and-precision28087 +Node: Balance Assignments28354 +Ref: #balance-assignments28528 +Node: Balance assignments and prices29692 +Ref: #balance-assignments-and-prices29864 +Node: Directives30088 +Ref: #directives30247 +Node: Directives and multiple files35928 +Ref: #directives-and-multiple-files36111 +Node: Comment blocks36775 +Ref: #comment-blocks36958 +Node: Including other files37134 +Ref: #including-other-files37314 +Node: Default year37722 +Ref: #default-year37891 +Node: Declaring commodities38298 +Ref: #declaring-commodities38481 +Node: Default commodity40287 +Ref: #default-commodity40463 +Node: Market prices41352 +Ref: #market-prices41517 +Node: Declaring accounts42358 +Ref: #declaring-accounts42534 +Node: Account comments43459 +Ref: #account-comments43622 +Node: Account subdirectives44046 +Ref: #account-subdirectives44241 +Node: Account types44554 +Ref: #account-types44738 +Node: Account display order46377 +Ref: #account-display-order46547 +Node: Rewriting accounts47698 +Ref: #rewriting-accounts47883 +Node: Basic aliases48640 +Ref: #basic-aliases48786 +Node: Regex aliases49490 +Ref: #regex-aliases49662 +Node: Combining aliases50380 +Ref: #combining-aliases50573 +Node: Aliases and multiple files51849 +Ref: #aliases-and-multiple-files52058 +Node: end aliases52637 +Ref: #end-aliases52794 +Node: Default parent account52895 +Ref: #default-parent-account53063 +Node: Periodic transactions53947 +Ref: #periodic-transactions54122 +Node: Periodic rule syntax55994 +Ref: #periodic-rule-syntax56200 +Node: Two spaces between period expression and description!56904 +Ref: #two-spaces-between-period-expression-and-description57223 +Node: Forecasting with periodic transactions57907 +Ref: #forecasting-with-periodic-transactions58212 +Node: Budgeting with periodic transactions60238 +Ref: #budgeting-with-periodic-transactions60477 +Node: Auto postings60926 +Ref: #auto-postings61066 +Node: Auto postings and multiple files63245 +Ref: #auto-postings-and-multiple-files63449 +Node: Auto postings and dates63658 +Ref: #auto-postings-and-dates63932 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions64107 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64458 +Node: Auto posting tags64800 +Ref: #auto-posting-tags65015  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 9d44d26b0..4abc4b318 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -429,11 +429,16 @@ FILE FORMAT see fewer decimal places in reports, use a commodity directive to over- 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 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 - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are + 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 + record purchases of a foreign currency. Note transaction prices are 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- tain date. @@ -462,7 +467,7 @@ FILE FORMAT (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- 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). Eg here is how -B affects the balance report for the example above: @@ -473,8 +478,8 @@ FILE FORMAT $-135 assets:dollars $135 assets:euros # <- the euros' cost - 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 + 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 amount. So if example 3's postings are reversed, while the transaction is equivalent, -B shows something different: @@ -487,9 +492,9 @@ FILE FORMAT EUR100 assets:euros Balance Assertions - hledger supports Ledger-style balance assertions in journal files. - These look like, for example, = EXPECTEDBALANCE following a posting's - amount. Eg here we assert the expected dollar balance in accounts a + hledger supports Ledger-style balance assertions in journal files. + These look like, for example, = EXPECTEDBALANCE following a posting's + amount. Eg here we assert the expected dollar balance in accounts a and b after each posting: 2013/1/1 @@ -501,32 +506,32 @@ FILE FORMAT b $-1 =$-2 After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the -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). Assertions and ordering - 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- + 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- 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.) So, hledger balance assertions keep working if you reorder differently- - dated transactions within the journal. But if you reorder same-dated - transactions or postings, assertions might break and require updating. + dated transactions within the journal. But if you reorder same-dated + transactions or postings, assertions might break and require updating. This order dependence does bring an advantage: precise control over the order of postings and assertions within a day, so you can assert intra- day balances. Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - 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 + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + 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 day, you'll have to put the assertion in the right file. Assertions and multiple -f options @@ -534,15 +539,15 @@ FILE FORMAT -f options. Use include or concatenate the files instead. Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the - (possibly multi-commodity) account balance. This is how assertions + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the + (possibly multi-commodity) account balance. This is how assertions 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 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 unasserted commodities in the account (or, that their balance is 0). @@ -562,7 +567,7 @@ FILE FORMAT a 0 == $1 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: 2013/1/1 @@ -576,21 +581,21 @@ FILE FORMAT a:euro 0 == 1EUR Assertions and prices - Balance assertions ignore transaction prices, and should normally be + Balance assertions ignore transaction prices, and should normally be written without one: 2019/1/1 (a) $1 @ EUR1 = $1 - 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. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- + 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. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- ments do use them (see below). Assertions and subaccounts - The balance assertions above (= and ==) do not count the balance from - subaccounts; they check the account's exclusive balance only. You can + The balance assertions above (= and ==) do not count the balance from + subaccounts; they check the account's exclusive balance only. You can assert the balance including subaccounts by writing =* or ==*, eg: 2019/1/1 @@ -604,16 +609,16 @@ FILE FORMAT tual. They are not affected by the --real/-R flag or real: query. Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. Balance Assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when setting opening balances: ; starting a new journal, set asset account balances @@ -631,14 +636,14 @@ FILE FORMAT expenses:misc The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- ment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. 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: 2019/1/1 @@ -649,85 +654,84 @@ FILE FORMAT (a) $1 @ EUR2 = $1 @ EUR2 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 based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). 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. - direc- end di- subdi- purpose can affect (as of + direc- end di- subdi- purpose can affect (as of tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------ - account any document account names, de- all entries in all - text clare account types & dis- files, before or + account any document account names, de- all entries in all + text clare account types & dis- files, before or play order after alias end rewrite account names following in- aliases line/included en- - tries until end of + tries until end of current file or end 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- - tries until end of + tries until end of current file or end directive comment end com- ignore part of journal following in- ment line/included en- - tries until end of + tries until end of current file or end 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 style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - D declare a commodity to be default commodity: + D declare a commodity to be default commodity: used for commodityless following commod- - amounts, and its number no- ityless entries un- - tation & display style til end of current - file; number nota- + amounts, and its number no- ityless entries un- + tation & display style til end of current + file; number nota- tion: following en- - tries in that com- + tries in that com- modity until end of - current file; dis- + current file; dis- play style: amounts of that commodity in reports include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that - commodity commodity in re- - ports, when -V is + commodity commodity in re- + ports, when -V is used - Y declare a year for yearless following in- + Y declare a year for yearless following in- dates line/included en- - tries until end of + tries until end of current file - = declare an auto posting all entries in par- - rule, adding postings to ent/current/child + = declare an auto posting all entries in par- + rule, adding postings to ent/current/child other transactions files (but not sib- ling files, see #1212) And some definitions: - subdi- optional indented directive line immediately following a parent + subdi- optional indented directive line immediately following a parent rec- directive tive 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.) - - 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) 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 scope @@ -736,41 +740,41 @@ FILE FORMAT ports). Some directives have multiple effects. Directives and multiple files - If you use multiple -f/--file options, or the include directive, - hledger will process multiple input files. But note that directives + If you use multiple -f/--file options, or the include directive, + hledger will process multiple input files. But note that directives which affect input (see above) typically last only until the end of the file in which they occur. This may seem inconvenient, but it's intentional; it makes reports sta- - ble and deterministic, independent of the order of input. Otherwise - 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 + ble and deterministic, independent of the order of input. Otherwise + 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 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). 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) ends it. See also comments. 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: include path/to/file.journal - 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. + 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. *). - 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. Default year - 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. + 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. Eg: Y2009 ; set default year to 2009 @@ -792,19 +796,19 @@ FILE FORMAT Declaring commodities 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. - 2. It declares what decimal mark character (period or comma) to expect - when parsing input - useful to disambiguate international number - formats in your data. (Without this, hledger will parse both 1,000 + 2. It declares what decimal mark character (period or comma) to expect + when parsing input - useful to disambiguate international number + formats in your data. (Without this, hledger will parse both 1,000 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. - 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 + 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 to declare your commodities. A commodity directive is just the word commodity followed by an amount. @@ -817,8 +821,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. (In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. (In this case + the commodity symbol appears twice and should be the same in both places.): ; commodity SYMBOL @@ -831,9 +835,12 @@ FILE FORMAT format INR 1,00,00,000.00 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. + Note hledger normally uses banker's rounding, so 0.5 displayed with + zero decimal digits is "0". (More at Amount display style.) + Default commodity 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- diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 34afb7d82..186018e37 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -351,13 +351,14 @@ Budget performance in 2017/11/01-2017/12/31: ----------------------++---------------------------------------------------- || 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, by default. -- In each column, in square brackets after the actual amount, budgeted - amounts are shown, along with the percentage of budget used. +- In each column, in square brackets after the actual amount, budget + 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, assets:bank, and expenses above. diff --git a/hledger/hledger.1 b/hledger/hledger.1 index d0b98d193..93bddce7c 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -2838,13 +2838,15 @@ Budget performance in 2017/11/01-2017/12/31: \f[R] .fi .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 Only accounts with budget goals during the report period are shown, by default. .IP \[bu] 2 -In each column, in square brackets after the actual amount, budgeted -amounts are shown, along with the percentage of budget used. +In each column, in square brackets after the actual amount, budget goal +amounts are shown, and the actual/goal percentage. +(Note: budget goals should be in the same commodity as the actual +amount.) .IP \[bu] 2 All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. diff --git a/hledger/hledger.info b/hledger/hledger.info index f26616b77..383bed802 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -2319,14 +2319,14 @@ Budget performance in 2017/11/01-2017/12/31: ----------------------++---------------------------------------------------- || 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, by default. - * In each column, in square brackets after the actual amount, - budgeted amounts are shown, along with the percentage of budget - used. + * In each column, in square brackets after the actual amount, budget + 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, assets:bank, and expenses above. @@ -3832,89 +3832,89 @@ Node: Multicolumn balance report73444 Ref: #multicolumn-balance-report73624 Node: Budget report78886 Ref: #budget-report79029 -Node: Nested budgets84231 -Ref: #nested-budgets84343 -Ref: #output-format-187824 -Node: balancesheet88021 -Ref: #balancesheet88157 -Node: balancesheetequity89623 -Ref: #balancesheetequity89772 -Node: cashflow90495 -Ref: #cashflow90623 -Node: check-dates91802 -Ref: #check-dates91929 -Node: check-dupes92208 -Ref: #check-dupes92332 -Node: close92625 -Ref: #close92739 -Node: close usage94261 -Ref: #close-usage94354 -Node: commodities97167 -Ref: #commodities97294 -Node: descriptions97376 -Ref: #descriptions97504 -Node: diff97685 -Ref: #diff97791 -Node: files98838 -Ref: #files98938 -Node: help99085 -Ref: #help99185 -Node: import100266 -Ref: #import100380 -Node: Importing balance assignments101273 -Ref: #importing-balance-assignments101421 -Node: incomestatement102070 -Ref: #incomestatement102203 -Node: notes103690 -Ref: #notes103803 -Node: payees103929 -Ref: #payees104035 -Node: prices104193 -Ref: #prices104299 -Node: print104640 -Ref: #print104750 -Node: print-unique109536 -Ref: #print-unique109662 -Node: register109947 -Ref: #register110074 -Node: Custom register output114246 -Ref: #custom-register-output114375 -Node: register-match115712 -Ref: #register-match115846 -Node: rewrite116197 -Ref: #rewrite116312 -Node: Re-write rules in a file118167 -Ref: #re-write-rules-in-a-file118301 -Node: Diff output format119511 -Ref: #diff-output-format119680 -Node: rewrite vs print --auto120772 -Ref: #rewrite-vs.-print---auto120951 -Node: roi121507 -Ref: #roi121605 -Node: stats122617 -Ref: #stats122716 -Node: tags123504 -Ref: #tags123602 -Node: test123896 -Ref: #test124004 -Node: Add-on Commands124751 -Ref: #add-on-commands124868 -Node: ui126211 -Ref: #ui126299 -Node: web126353 -Ref: #web126456 -Node: iadd126572 -Ref: #iadd126683 -Node: interest126765 -Ref: #interest126872 -Node: ENVIRONMENT127112 -Ref: #environment127224 -Node: FILES128053 -Ref: #files-1128156 -Node: LIMITATIONS128369 -Ref: #limitations128488 -Node: TROUBLESHOOTING129230 -Ref: #troubleshooting129343 +Node: Nested budgets84295 +Ref: #nested-budgets84407 +Ref: #output-format-187888 +Node: balancesheet88085 +Ref: #balancesheet88221 +Node: balancesheetequity89687 +Ref: #balancesheetequity89836 +Node: cashflow90559 +Ref: #cashflow90687 +Node: check-dates91866 +Ref: #check-dates91993 +Node: check-dupes92272 +Ref: #check-dupes92396 +Node: close92689 +Ref: #close92803 +Node: close usage94325 +Ref: #close-usage94418 +Node: commodities97231 +Ref: #commodities97358 +Node: descriptions97440 +Ref: #descriptions97568 +Node: diff97749 +Ref: #diff97855 +Node: files98902 +Ref: #files99002 +Node: help99149 +Ref: #help99249 +Node: import100330 +Ref: #import100444 +Node: Importing balance assignments101337 +Ref: #importing-balance-assignments101485 +Node: incomestatement102134 +Ref: #incomestatement102267 +Node: notes103754 +Ref: #notes103867 +Node: payees103993 +Ref: #payees104099 +Node: prices104257 +Ref: #prices104363 +Node: print104704 +Ref: #print104814 +Node: print-unique109600 +Ref: #print-unique109726 +Node: register110011 +Ref: #register110138 +Node: Custom register output114310 +Ref: #custom-register-output114439 +Node: register-match115776 +Ref: #register-match115910 +Node: rewrite116261 +Ref: #rewrite116376 +Node: Re-write rules in a file118231 +Ref: #re-write-rules-in-a-file118365 +Node: Diff output format119575 +Ref: #diff-output-format119744 +Node: rewrite vs print --auto120836 +Ref: #rewrite-vs.-print---auto121015 +Node: roi121571 +Ref: #roi121669 +Node: stats122681 +Ref: #stats122780 +Node: tags123568 +Ref: #tags123666 +Node: test123960 +Ref: #test124068 +Node: Add-on Commands124815 +Ref: #add-on-commands124932 +Node: ui126275 +Ref: #ui126363 +Node: web126417 +Ref: #web126520 +Node: iadd126636 +Ref: #iadd126747 +Node: interest126829 +Ref: #interest126936 +Node: ENVIRONMENT127176 +Ref: #environment127288 +Node: FILES128117 +Ref: #files-1128220 +Node: LIMITATIONS128433 +Ref: #limitations128552 +Node: TROUBLESHOOTING129294 +Ref: #troubleshooting129407  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 0df0b572f..94686df2d 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1995,27 +1995,28 @@ COMMANDS ----------------------++---------------------------------------------------- || 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, by default. - o In each column, in square brackets after the actual amount, budgeted - amounts are shown, along with the percentage of budget used. + o In each column, in square brackets after the actual amount, budget + 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. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -2057,12 +2058,12 @@ COMMANDS For more examples, see Budgeting and Forecasting. 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- - 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. - 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. To illustrate this, consider the following budget: @@ -2072,13 +2073,13 @@ COMMANDS expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicitly + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicitly 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 - 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. For example, let's consider these transactions: @@ -2104,9 +2105,9 @@ COMMANDS expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -2122,7 +2123,7 @@ COMMANDS -------------------------------++------------------------------- || 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: $ hledger balance --budget -M --empty @@ -2141,17 +2142,17 @@ COMMANDS Output format 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. balancesheet balancesheet, bs This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or 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) (experimental). @@ -2177,21 +2178,21 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for - a balance sheet; note this means it ignores report begin dates (and - -T/--row-total, since summing end balances generally does not make - sense). Instead of absolute values percentages can be displayed with + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates (and + -T/--row-total, since summing end balances generally does not make + sense). Instead of absolute values percentages can be displayed with -%. 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. balancesheetequity 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). Example: @@ -2221,15 +2222,15 @@ COMMANDS 0 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. cashflow cashflow, cf - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -2250,90 +2251,90 @@ COMMANDS $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. Instead of absolute val- ues percentages can be displayed with -%. 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. check-dates check-dates - Check that transactions are sorted by increasing date. With --date2, - checks secondary dates instead. With --strict, dates must also be - unique. With a query, only matched transactions' dates are checked. + Check that transactions are sorted by increasing date. With --date2, + checks secondary dates instead. With --strict, dates must also be + unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. check-dupes check-dupes - Reports account names having the same leaf but different prefixes. In - other words, two or more leaves that are categorized differently. + Reports account names having the same leaf but different prefixes. In + other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. An example: http://stefanorodighiero.net/software/hledger-dupes.html close 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. 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. - You can print just one of these transactions by using the --close or - --open flag. You can customise their descriptions with the --close- + You can print just one of these transactions by using the --close or + --open flag. You can customise their descriptions with the --close- desc and --open-desc options. One amountless posting to "equity:opening/closing balances" is added to - balance the transactions, by default. You can customise this account - name with --close-acct and --open-acct; if you specify only one of + balance the transactions, by default. You can customise this account + name with --close-acct and --open-acct; if you specify only one of these, it will be used for both. 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. - 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. By default, transaction prices in the journal are ignored when generat- ing the closing/opening transactions. With --show-costs, this cost in- - formation is preserved (balance -B reports will be unchanged after the - transition). Separate postings are generated for each cost in each - commodity. Note this can generate very large journal entries, if you + formation is preserved (balance -B reports will be unchanged after the + transition). Separate postings are generated for each cost in each + commodity. Note this can generate very large journal entries, if you have many foreign currency or investment transactions. close usage 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- - 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 - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - 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- + 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 + 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. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + 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- ing|closing) balances'.) 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 - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - 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- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + 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- + 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). - 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 - (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- - mand with --auto, the balance assertions will probably always require + (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- + mand with --auto, the balance assertions will probably always require --auto. Examples: @@ -2388,18 +2389,18 @@ COMMANDS 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 the other. More precisely, for each posting affecting this account in either file, - it looks for a corresponding posting in the other file which posts the - same amount to the same account (ignoring date, description, etc.) + it looks for a corresponding posting in the other file which posts the + same amount to the same account (ignoring date, description, etc.) Since postings not transactions are compared, this also works when mul- tiple bank transactions have been combined into a single journal entry. 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 find out the cause. @@ -2417,20 +2418,20 @@ COMMANDS 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. help help Show any of the hledger manuals. - 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 + 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 a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: @@ -2457,9 +2458,9 @@ COMMANDS import import - 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- - tions that would be added. Or with --catchup, just mark all of the + 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- + tions that would be added. Or with --catchup, just mark all of the FILEs' transactions as imported, without actually importing any. 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 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: $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions Importing balance assignments - Entries added by import will have their posting amounts made explicit - (like hledger print -x). This means that any balance assignments in - 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 + Entries added by import will have their posting amounts made explicit + (like hledger print -x). This means that any balance assignments in + 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 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: $ 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.) incomestatement incomestatement, is - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, un- + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, un- like balance/print/register) (experimental). - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -2524,13 +2525,13 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the - report mode with --change/--cumulative/--historical. Instead of abso- + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. Instead of abso- lute values percentages can be displayed with -%. 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. notes @@ -2558,10 +2559,10 @@ COMMANDS prices prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With --in- - verted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. print @@ -2569,11 +2570,11 @@ COMMANDS Show transaction journal entries, sorted by date. 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. 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 $ hledger print @@ -2600,43 +2601,43 @@ COMMANDS 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 - 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 - the -x/--explicit flag to make all amounts and transaction prices ex- - plicit, which can be useful for troubleshooting or for making your + 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 + the -x/--explicit flag to make all amounts and transaction prices ex- + plicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - Note, -x/--explicit will cause postings with a multi-commodity amount - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping 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. - 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 - most recent. STR should contain at least two characters. If there is + 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 + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for ig- - noring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new (shows transactions added since last print --new on this file) - 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- + 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- ordered. See also the import command. 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. 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","","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. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different 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. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2692,7 +2693,7 @@ COMMANDS Show postings and their running total. 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: $ hledger register checking @@ -2703,8 +2704,8 @@ COMMANDS With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -2714,18 +2715,18 @@ COMMANDS 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 - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- 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 --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- - 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: $ hledger register --related --invert assets:checking @@ -2737,7 +2738,7 @@ COMMANDS 2008/01 income:salary $-1 $-1 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: $ hledger register --monthly income -E @@ -2754,7 +2755,7 @@ COMMANDS 2008/11 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: $ hledger register --monthly assets --depth 1h @@ -2762,17 +2763,17 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - 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- - tervals. This ensures that the first and last intervals are full + 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- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not 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- scription width as part of --width's argument, comma-separated: --width 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 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. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger-au- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. rewrite rewrite 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. 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 - 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. Examples: @@ -2827,7 +2828,7 @@ COMMANDS (reserve:grocery) *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. More: @@ -2837,16 +2838,16 @@ COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can 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- - 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. 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 operations in command line you can put them in a journal file. @@ -2861,7 +2862,7 @@ COMMANDS budget:gifts *-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 match the posting to add new ones. @@ -2874,12 +2875,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. 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. $ 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- 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. - 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. See also: @@ -2914,48 +2915,48 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 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: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect 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. - 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. 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. - 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 these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to 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 identify your profit and loss transactions with --pnl. - It will compute and display the internalized rate of return (IRR) and - time-weighted rate of return (TWR) for your investments for the time - period requested. Both rates of return are annualized before display, + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. stats stats Show some journal statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. Example: @@ -2973,14 +2974,14 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With QUERY arguments, only transactions matching the query are + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are + shown. With QUERY arguments, only transactions matching the query are considered. With --values flag, the tags' unique values are listed in- stead. @@ -2988,13 +2989,13 @@ COMMANDS test Run built-in unit tests. - 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 + 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 be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -3003,35 +3004,35 @@ COMMANDS $ 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). 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 - 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). - 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, - 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. - 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; + 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; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - 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 - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + 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 + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line 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: ui @@ -3050,23 +3051,23 @@ COMMANDS hledger-interest generates interest transactions for an account accord- 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. 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. 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). - 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- + 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- 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 - 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- vironment.plist file containing @@ -3077,13 +3078,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). 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. 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 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. - 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. TROUBLESHOOTING - 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 + 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 tracker): Successfully installed, but "No command 'hledger' found" 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. 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 - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may 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 In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can 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). 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 $ 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: $ apt-get install language-pack-fr @@ -3165,7 +3166,7 @@ TROUBLESHOOTING 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) @@ -3179,7 +3180,7 @@ COPYRIGHT 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- dot(5), ledger(1)