hledger 1.20.2 → 1.20.3

raw patch · 24 files changed

+2280/−2202 lines, 24 filesdep ~hledger-libPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: hledger-lib

API changes (from Hackage documentation)

Files

• CHANGES.md +34/−0
• Hledger/Cli/Commands/Balance.hs +2/−9
• Hledger/Cli/Commands/Balance.txt +196/−188
• Hledger/Cli/Commands/Roi.hs +3/−3
• Hledger/Cli/CompoundBalanceCommand.hs +0/−7
• embeddedfiles/hledger-ui.1 +1/−1
• embeddedfiles/hledger-ui.txt +1/−1
• embeddedfiles/hledger-web.1 +1/−1
• embeddedfiles/hledger-web.txt +1/−1
• embeddedfiles/hledger.1 +226/−213
• embeddedfiles/hledger.info +322/−317
• embeddedfiles/hledger.txt +464/−457
• embeddedfiles/hledger_csv.5 +1/−1
• embeddedfiles/hledger_csv.txt +1/−1
• embeddedfiles/hledger_journal.5 +1/−1
• embeddedfiles/hledger_journal.txt +1/−1
• embeddedfiles/hledger_timeclock.5 +1/−1
• embeddedfiles/hledger_timeclock.txt +1/−1
• embeddedfiles/hledger_timedot.5 +1/−1
• embeddedfiles/hledger_timedot.txt +1/−1
• hledger.1 +226/−213
• hledger.cabal +9/−9
• hledger.info +322/−317
• hledger.txt +464/−457

@@ -1,6 +1,40 @@ User-visible changes in the hledger command line tool and library.  +# 1.20.3 2021-01-14++- When searching for price chains during valuation/currency conversion:++  - It no longer hangs when there are price loops. (And in case of+    future bugs, it will give up rather than search forever.) (#1439)+  - It now really finds the shortest path. (#1443)+  - Useful progress info is displayed with `--debug=1` or `--debug=2`.++- balance, incomestatement: End-valued multi-period balance change+  reports (eg: `bal -MV`) have been reverted to show value-of-change,+  as in previous hledger versions, rather than change-of-value, for+  now. (#1353, #1428) (Stephen Morgan)++- balance: End-valued balance change reports now choose the same final+  valuation date and show consistent results whether single-period or+  multi-period. (#1424) (Stephen Morgan)++- balance: the `--drop` option now works with `csv` and `html` output.+  (#1456) (Ilya Konovalov)++- check: the `commodities` check, and `-s`/`--strict` mode, now ignore+  the "AUTO" internal pseudo-commodity. (#1419) (Ilya Konovalov)++- register: Then-valued multi-period register reports+  (eg: `register -M --value=then`) now calculate the correct values.+  (#1449) (Stephen Morgan)++- roi: now shows a better error message when required prices are+  missing. (#1446) (Dmitry Astapov)++- The no-symbol commodity's input number format can now be set by a+  `commodity` directive, like other commodities. (#1461)+ # 1.20.2 2020-12-28  - help: Fix loss of capitalisation in part of the hledger-ui manual. 

@@ -356,7 +356,7 @@ balanceReportAsCsv :: ReportOpts -> BalanceReport -> CSV balanceReportAsCsv opts (items, total) =   ["account","balance"] :-  [[T.unpack a, showMixedAmountOneLineWithoutPrice False b] | (a, _, _, b) <- items]+  [[T.unpack $ accountNameDrop (drop_ opts) a, showMixedAmountOneLineWithoutPrice False b] | (a, _, _, b) <- items]   ++   if no_total_ opts   then []@@ -450,7 +450,7 @@    ++ ["Total"   | row_total_]    ++ ["Average" | average_]   ) :-  [T.unpack (displayFull a) :+  [T.unpack (displayName a) :    map (showMixedAmountOneLineWithoutPrice False)    (amts     ++ [rowtot | row_total_]@@ -566,28 +566,21 @@     title = mtitle <> " in " <> showDateSpan (periodicReportSpan r) <> valuationdesc <> ":"      mtitle = case balancetype_ of-        PeriodChange     | changingValuation -> "Period-end value changes"         PeriodChange                         -> "Balance changes"         CumulativeChange                     -> "Ending balances (cumulative)"         HistoricalBalance                    -> "Ending balances (historical)"     valuationdesc = case value_ of         Just (AtCost _mc)    -> ", valued at cost"         Just (AtThen _mc)    -> error' unsupportedValueThenError  -- TODO -- ", valued at period ends"  -- handled like AtEnd for now  -- PARTIAL:-        Just (AtEnd _mc) | changingValuation -> ""         Just (AtEnd _mc)     -> ", valued at period ends"         Just (AtNow _mc)     -> ", current value"         -- XXX duplicates the above-        Just (AtDefault _mc) | changingValuation -> ""         Just (AtDefault _mc) | multiperiod       -> ", valued at period ends"         Just (AtDefault _mc) -> ", current value"         Just (AtDate d _mc)  -> ", valued at "++showDate d         Nothing              -> ""      multiperiod = interval_ /= NoInterval-    changingValuation-      | PeriodChange <- balancetype_, Just (AtEnd _mc)     <- value_ = multiperiod-      | PeriodChange <- balancetype_, Just (AtDefault _mc) <- value_ = multiperiod-      | otherwise                                                    = False  -- | Build a 'Table' from a multi-column balance report. balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount

@@ -29,11 +29,32 @@  The balance command can produce several styles of report: -Classic balance report+Single-period flat balance report -This is the original balance report, as found in Ledger. It usually-looks like this:+This is the default for hledger's balance command: a flat list of all+(or with a query, matched) accounts, showing full account names.+Accounts are sorted by declaration order if any, and then by account+name. Accounts which have zero balance are not shown unless -E/--empty+is used. The reported balances' total is shown as the last line, unless+disabled by -N/--no-total. +$ hledger bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  ++Single-period tree-mode balance report++With the -t/--tree flag, accounts are displayed hierarchically, showing+subaccounts as short names indented below their parent. (This is the+default style in Ledger and in older hledger versions.)+ $ hledger balance                  $-1  assets                   $1    bank:saving@@ -48,188 +69,53 @@ --------------------                    0 -By default, accounts are displayed hierarchically, with subaccounts-indented below their parent, with accounts at each level of the tree-sorted by declaration order if declared, then by account name.--"Boring" accounts, which contain a single interesting subaccount and no-balance of their own, are elided into the following line for more-compact output. (Eg above, the "liabilities" account.) Use --no-elide to-prevent this.--Account balances are "inclusive" - they include the balances of any-subaccounts.--Accounts which have zero balance (and no non-zero subaccounts) are-omitted. Use -E/--empty to show them.--A final total is displayed by default; use -N/--no-total to suppress it,-eg:--$ hledger balance -p 2008/6 expenses --no-total-                  $2  expenses-                  $1    food-                  $1    supplies--Customising the classic balance report--You can customise the layout of classic balance reports with---format FMT:--$ hledger balance --format "%20(account) %12(total)"-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1-----------------------------------                                0--The FMT format string (plus a newline) specifies the formatting applied-to each account/balance pair. It may contain any suitable text, with-data fields interpolated like so:--%[MIN][.MAX](FIELDNAME)---   MIN pads with spaces to at least this width (optional)---   MAX truncates at this width (optional)---   FIELDNAME must be enclosed in parentheses, and can be one of:--    -   depth_spacer - a number of spaces equal to the account's depth,-        or if MIN is specified, MIN * depth spaces.-    -   account - the account's name-    -   total - the account's balance/posted total, right justified--Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:---   %_ - render on multiple lines, bottom-aligned (the default)--   %^ - render on multiple lines, top-aligned--   %, - render on one line, comma-separated--There are some quirks. Eg in one-line mode, %(depth_spacer) has no-effect, instead %(account) has indentation built in. Experimentation may-be needed to get pleasing results.--Some example formats:---   %(total) - the account's total--   %-20.20(account) - the account's name, left justified, padded to 20-    characters and clipped at 20 characters--   %,%-50(account)  %25(total) - account name padded to 50 characters,-    total padded to 20 characters, with multiple commodities rendered on-    one line--   %20(total)  %2(depth_spacer)%-(account) - the default format for the-    single-column balance report--Colour support--In terminal output, when colour is enabled, the balance command shows-negative amounts in red.--Flat mode--To see a flat list instead of the default hierarchical display, use---flat. In this mode, accounts (unless depth-clipped) show their full-names and "exclusive" balance, excluding any subaccount balances. In-this mode, you can also use --drop N to omit the first few account name-components.--$ hledger balance -p 2008/6 expenses -N --flat --drop 1-                  $1  food-                  $1  supplies--Depth limited balance reports--With --depth N or depth:N or just -N, balance reports show accounts only-to the specified numeric depth. This is very useful to summarise a-complex set of accounts and get an overview.--$ hledger balance -N -1-                 $-1  assets-                  $2  expenses-                 $-2  income-                  $1  liabilities--Flat-mode balance reports, which normally show exclusive balances, show-inclusive balances at the depth limit.--Percentages--With -% or --percent, balance reports show each account's value-expressed as a percentage of the column's total. This is useful to get-an overview of the relative sizes of account balances. For example to-obtain an overview of expenses:--$ hledger balance expenses -%-             100.0 %  expenses-              50.0 %    food-              50.0 %    supplies----------------------             100.0 %--Note that --tree does not have an effect on -%. The percentages are-always relative to the total sum of each column, they are never relative-to the parent account.--Since the percentages are relative to the columns sum, it is usually not-useful to calculate percentages if the signs of the amounts are mixed.-Although the results are technically correct, they are most likely-useless. Especially in a balance report that sums up to zero (eg-hledger balance -B) all percentage values will be zero.--This flag does not work if the report contains any mixed commodity-accounts. If there are mixed commodity accounts in the report be sure to-use -V or -B to coerce the report into using a single commodity.--Sorting by amount+For more compact output, "boring" accounts containing a single+interesting subaccount and no balance of their own (assets:bank and+liabilities here) are elided into the following line, unless --no-elide+is used. And accounts which have zero balance and no non-zero+subaccounts are omitted, unless -E/--empty is used. -With -S/--sort-amount, accounts with the largest (most positive)-balances are shown first. For example, hledger bal expenses -MAS shows-your biggest averaged monthly expenses first.+Account balances in tree mode are "inclusive" - they include the+balances of any subaccounts. Eg, the assets $-1 balance here includes+the $1 from assets:bank:saving and the $-2 from assets:cash. (And it+would include balance posted to the assets account itself, if there was+any). Note this causes some repetition, and the final total (0) is the+sum of the top-level balances, not of all the balances shown. -Revenues and liability balances are typically negative, however, so -S-shows these in reverse order. To work around this, you can add --invert-to flip the signs. Or, use one of the sign-flipping reports like-balancesheet or incomestatement, which also support -S. Eg:-hledger is -MAS.+Each group of sibling accounts is sorted separately, by declaration+order and then by account name. -Multicolumn balance report+Multi-period balance report -Multicolumn or tabular balance reports are a very useful hledger-feature, and usually the preferred style. They share many of the above-features, but they show the report as a table, with columns representing-time periods. This mode is activated by providing a reporting interval.+Multi-period balance reports are a very useful hledger feature,+activated if you provide one of the reporting interval flags, such as+-M/--monthly. They are similar to single-period balance reports, but+they show the report as a table, with columns representing one or more+successive time periods. This is the usually the preferred style of+balance report in hledger (even for a single period). -There are three types of multicolumn balance report, showing different+Multi-period balance reports come in several types, showing different information: -1.  By default: each column shows the sum of postings in that period, ie-    the account's change of balance in that period. This is useful eg-    for a monthly income statement:+1.  A balance change report: by default, each column shows the sum of+    postings in that period, ie the account's change of balance in that+    period. This is useful eg for a monthly income statement: -    $ hledger balance --quarterly income expenses -E-    Balance changes in 2008:+$ hledger balance --quarterly income expenses -E+Balance changes in 2008: -                       ||  2008q1  2008q2  2008q3  2008q4 -    ===================++=================================-     expenses:food     ||       0      $1       0       0 -     expenses:supplies ||       0      $1       0       0 -     income:gifts      ||       0     $-1       0       0 -     income:salary     ||     $-1       0       0       0 -    -------------------++----------------------------------                       ||     $-1      $1       0       0 +                   ||  2008q1  2008q2  2008q3  2008q4 +===================++=================================+ expenses:food     ||       0      $1       0       0 + expenses:supplies ||       0      $1       0       0 + income:gifts      ||       0     $-1       0       0 + income:salary     ||     $-1       0       0       0 +-------------------++---------------------------------+                   ||     $-1      $1       0       0  -2.  With --cumulative: each column shows the ending balance for that-    period, accumulating the changes across periods, starting from 0 at-    the report start date:+2.  A cumulative end balance report: with --cumulative, each column+    shows the end balance for that period, accumulating the changes+    across periods, starting from 0 at the report start date:      $ hledger balance --quarterly income expenses -E --cumulative     Ending balances (cumulative) in 2008:@@ -243,11 +129,12 @@     -------------------++-------------------------------------------------                        ||         $-1           0           0           0  -3.  With --historical/-H: each column shows the actual historical ending-    balance for that period, accumulating the changes across periods,-    starting from the actual balance at the report start date. This is-    useful eg for a multi-period balance sheet, and when you are showing-    only the data after a certain start date:+3.  A historical end balance report: with --historical/-H, each column+    shows the actual historical end balance for that period,+    accumulating the changes across periods, and including the balance+    from any postings before the report start date. This is useful eg+    for a multi-period balance sheet, and when you want to see balances+    only after a certain date:      $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1     Ending balances (historical) in 2008/04/01-2008/12/31:@@ -264,9 +151,6 @@ Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. -Multicolumn balance reports display accounts in flat mode by default; to-see the hierarchy, use --tree.- With a reporting interval (like --quarterly above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last periods will be@@ -317,13 +201,137 @@ less -RS (-R for colour, -S to chop long lines). Eg: hledger bal -D --color=yes | less -RS. +Depth limiting++With a depth:N query, or --depth N option, or just -N, balance reports+will show accounts only to the specified depth. This is very useful to+hide low-level accounts and get an overview. Eg, limiting to depth 1+shows the top-level accounts:++$ hledger balance -N -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities++Accounts at the depth limit will include the balances of any hidden+subaccounts (even in flat mode, which normally shows exclusive+balances).++You can also drop account name components from the start of account+names, using --drop N. This can be useful to hide unwanted top-level+detail.++Colour support++In terminal output, when colour is enabled, the balance command shows+negative amounts in red.++Sorting by amount++With -S/--sort-amount, accounts with the largest (most positive)+balances are shown first. For example, hledger bal expenses -MAS shows+your biggest averaged monthly expenses first.++Revenues and liability balances are typically negative, however, so -S+shows these in reverse order. To work around this, you can add --invert+to flip the signs. Or, use one of the sign-flipping reports like+balancesheet or incomestatement, which also support -S. Eg:+hledger is -MAS.++Percentages++With -% or --percent, balance reports show each account's value+expressed as a percentage of the column's total. This is useful to get+an overview of the relative sizes of account balances. For example to+obtain an overview of expenses:++$ hledger balance expenses -%+             100.0 %  expenses+              50.0 %    food+              50.0 %    supplies+--------------------+             100.0 %++Note that --tree does not have an effect on -%. The percentages are+always relative to the total sum of each column, they are never relative+to the parent account.++Since the percentages are relative to the columns sum, it is usually not+useful to calculate percentages if the signs of the amounts are mixed.+Although the results are technically correct, they are most likely+useless. Especially in a balance report that sums up to zero (eg+hledger balance -B) all percentage values will be zero.++This flag does not work if the report contains any mixed commodity+accounts. If there are mixed commodity accounts in the report be sure to+use -V or -B to coerce the report into using a single commodity.++Customising single-period balance reports++You can customise the layout of single-period balance reports with+--format FMT, which sets the format of each line. Eg:++$ hledger balance --format "%20(account) %12(total)"+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0++The FMT format string (plus a newline) specifies the formatting applied+to each account/balance pair. It may contain any suitable text, with+data fields interpolated like so:++%[MIN][.MAX](FIELDNAME)++-   MIN pads with spaces to at least this width (optional)++-   MAX truncates at this width (optional)++-   FIELDNAME must be enclosed in parentheses, and can be one of:++    -   depth_spacer - a number of spaces equal to the account's depth,+        or if MIN is specified, MIN * depth spaces.+    -   account - the account's name+    -   total - the account's balance/posted total, right justified++Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++-   %_ - render on multiple lines, bottom-aligned (the default)+-   %^ - render on multiple lines, top-aligned+-   %, - render on one line, comma-separated++There are some quirks. Eg in one-line mode, %(depth_spacer) has no+effect, instead %(account) has indentation built in. Experimentation may+be needed to get pleasing results.++Some example formats:++-   %(total) - the account's total+-   %-20.20(account) - the account's name, left justified, padded to 20+    characters and clipped at 20 characters+-   %,%-50(account)  %25(total) - account name padded to 50 characters,+    total padded to 20 characters, with multiple commodities rendered on+    one line+-   %20(total)  %2(depth_spacer)%-(account) - the default format for the+    single-column balance report+ Budget report -With --budget, extra columns are displayed showing budget goals for each-account and period, if any. Budget goals are defined by periodic-transactions. This is very useful for comparing planned and actual-income, expenses, time usage, etc. --budget is most often combined with-a report interval.+There is also a special balance report mode for showing budget+performance. The --budget flag activates extra columns showing the+budget goals for each account and period, if any. For this report,+budget goals are defined by periodic transactions. This is very useful+for comparing planned and actual income, expenses, time usage, etc.  For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:

@@ -261,6 +261,6 @@  unMix :: MixedAmount -> Quantity unMix a =-  case (normaliseMixedAmount $ mixedAmountCost a) of-    (Mixed [a]) -> aquantity a-    _ -> error' "MixedAmount failed to normalize"  -- PARTIAL:+  case (unifyMixedAmount $ mixedAmountCost a) of+    Just a -> aquantity a+    Nothing -> error' $ "Amounts could not be converted to a single cost basis: " ++ show (map showAmount $ amounts a)

@@ -126,7 +126,6 @@            -- when user overrides, add an indication to the report title           mtitleclarification = flip fmap mBalanceTypeOverride $ \case-              PeriodChange | changingValuation -> "(Period-End Value Changes)"               PeriodChange                     -> "(Balance Changes)"               CumulativeChange                 -> "(Cumulative Ending Balances)"               HistoricalBalance                -> "(Historical Ending Balances)"@@ -134,20 +133,14 @@           valuationdesc = case value_ of             Just (AtCost _mc)       -> ", valued at cost"             Just (AtThen _mc)       -> error' unsupportedValueThenError  -- TODO-            Just (AtEnd _mc) | changingValuation -> ""             Just (AtEnd _mc)        -> ", valued at period ends"             Just (AtNow _mc)        -> ", current value"-            Just (AtDefault _mc) | changingValuation -> ""             Just (AtDefault _mc) | multiperiod       -> ", valued at period ends"             Just (AtDefault _mc)    -> ", current value"             Just (AtDate today _mc) -> ", valued at "++showDate today             Nothing                 -> ""            multiperiod = interval_ /= NoInterval-          changingValuation-            | PeriodChange <- balancetype_, Just (AtEnd _mc)     <- value_ = multiperiod-            | PeriodChange <- balancetype_, Just (AtDefault _mc) <- value_ = multiperiod-            | otherwise                                                    = False        -- make a CompoundBalanceReport.       cbr' = compoundBalanceReport rspec{rsOpts=ropts'} j cbcqueries

@@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "December 2020" "hledger-ui-1.20.1 " "hledger User Manuals"+.TH "HLEDGER-UI" "1" "December 2020" "hledger-ui-1.20.3 " "hledger User Manuals"   

@@ -459,4 +459,4 @@   -hledger-ui-1.20.1                December 2020                   HLEDGER-UI(1)+hledger-ui-1.20.3                December 2020                   HLEDGER-UI(1)

@@ -1,5 +1,5 @@ -.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.1 " "hledger User Manuals"+.TH "HLEDGER-WEB" "1" "December 2020" "hledger-web-1.20.3 " "hledger User Manuals"   

@@ -552,4 +552,4 @@   -hledger-web-1.20.1               December 2020                  HLEDGER-WEB(1)+hledger-web-1.20.3               December 2020                  HLEDGER-WEB(1)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2020" "hledger-1.20.1 " "hledger User Manuals"+.TH "HLEDGER" "1" "December 2020" "hledger-1.20.3 " "hledger User Manuals"   @@ -2798,231 +2798,95 @@ \f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R]. .PP The balance command can produce several styles of report:-.SS Classic balance report .PP-This is the original balance report, as found in Ledger.-It usually looks like this:+.SS Single-period flat balance report+.PP+This is the default for hledger\[aq]s balance command: a flat list of+all (or with a query, matched) accounts, showing full account names.+Accounts are sorted by declaration order if any, and then by account+name.+Accounts which have zero balance are not shown unless+\f[C]-E/--empty\f[R] is used.+The reported balances\[aq] total is shown as the last line, unless+disabled by \f[C]-N\f[R]/\f[C]--no-total\f[R]. .IP .nf \f[C]-$ hledger balance-                 $-1  assets-                  $1    bank:saving-                 $-2    cash-                  $2  expenses-                  $1    food-                  $1    supplies-                 $-2  income-                 $-1    gifts-                 $-1    salary+$ hledger bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary                   $1  liabilities:debts ---------------------                   0+                   0   \f[R] .fi .PP-By default, accounts are displayed hierarchically, with subaccounts-indented below their parent, with accounts at each level of the tree-sorted by declaration order if declared, then by account name.-.PP-\[dq]Boring\[dq] accounts, which contain a single interesting subaccount-and no balance of their own, are elided into the following line for more-compact output.-(Eg above, the \[dq]liabilities\[dq] account.) Use \f[C]--no-elide\f[R]-to prevent this.-.PP-Account balances are \[dq]inclusive\[dq] - they include the balances of-any subaccounts.-.PP-Accounts which have zero balance (and no non-zero subaccounts) are-omitted.-Use \f[C]-E/--empty\f[R] to show them.+.SS Single-period tree-mode balance report .PP-A final total is displayed by default; use \f[C]-N/--no-total\f[R] to-suppress it, eg:+With the \f[C]-t/--tree\f[R] flag, accounts are displayed+hierarchically, showing subaccounts as short names indented below their+parent.+(This is the default style in Ledger and in older hledger versions.) .IP .nf \f[C]-$ hledger balance -p 2008/6 expenses --no-total+$ hledger balance+                 $-1  assets+                  $1    bank:saving+                 $-2    cash                   $2  expenses                   $1    food                   $1    supplies-\f[R]-.fi-.SS Customising the classic balance report-.PP-You can customise the layout of classic balance reports with-\f[C]--format FMT\f[R]:-.IP-.nf-\f[C]-$ hledger balance --format \[dq]%20(account) %12(total)\[dq]-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1-----------------------------------                                0-\f[R]-.fi-.PP-The FMT format string (plus a newline) specifies the formatting applied-to each account/balance pair.-It may contain any suitable text, with data fields interpolated like so:-.PP-\f[C]%[MIN][.MAX](FIELDNAME)\f[R]-.IP \[bu] 2-MIN pads with spaces to at least this width (optional)-.IP \[bu] 2-MAX truncates at this width (optional)-.IP \[bu] 2-FIELDNAME must be enclosed in parentheses, and can be one of:-.RS 2-.IP \[bu] 2-\f[C]depth_spacer\f[R] - a number of spaces equal to the account\[aq]s-depth, or if MIN is specified, MIN * depth spaces.-.IP \[bu] 2-\f[C]account\f[R] - the account\[aq]s name-.IP \[bu] 2-\f[C]total\f[R] - the account\[aq]s balance/posted total, right-justified-.RE-.PP-Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:-.IP \[bu] 2-\f[C]%_\f[R] - render on multiple lines, bottom-aligned (the default)-.IP \[bu] 2-\f[C]%\[ha]\f[R] - render on multiple lines, top-aligned-.IP \[bu] 2-\f[C]%,\f[R] - render on one line, comma-separated-.PP-There are some quirks.-Eg in one-line mode, \f[C]%(depth_spacer)\f[R] has no effect, instead-\f[C]%(account)\f[R] has indentation built in.-Experimentation may be needed to get pleasing results.-.PP-Some example formats:-.IP \[bu] 2-\f[C]%(total)\f[R] - the account\[aq]s total-.IP \[bu] 2-\f[C]%-20.20(account)\f[R] - the account\[aq]s name, left justified,-padded to 20 characters and clipped at 20 characters-.IP \[bu] 2-\f[C]%,%-50(account)  %25(total)\f[R] - account name padded to 50-characters, total padded to 20 characters, with multiple commodities-rendered on one line-.IP \[bu] 2-\f[C]%20(total)  %2(depth_spacer)%-(account)\f[R] - the default format-for the single-column balance report-.SS Colour support-.PP-In terminal output, when colour is enabled, the balance command shows-negative amounts in red.-.SS Flat mode-.PP-To see a flat list instead of the default hierarchical display, use-\f[C]--flat\f[R].-In this mode, accounts (unless depth-clipped) show their full names and-\[dq]exclusive\[dq] balance, excluding any subaccount balances.-In this mode, you can also use \f[C]--drop N\f[R] to omit the first few-account name components.-.IP-.nf-\f[C]-$ hledger balance -p 2008/6 expenses -N --flat --drop 1-                  $1  food-                  $1  supplies-\f[R]-.fi-.SS Depth limited balance reports-.PP-With \f[C]--depth N\f[R] or \f[C]depth:N\f[R] or just \f[C]-N\f[R],-balance reports show accounts only to the specified numeric depth.-This is very useful to summarise a complex set of accounts and get an-overview.-.IP-.nf-\f[C]-$ hledger balance -N -1-                 $-1  assets-                  $2  expenses                  $-2  income-                  $1  liabilities-\f[R]-.fi-.PP-Flat-mode balance reports, which normally show exclusive balances, show-inclusive balances at the depth limit.-.SS Percentages-.PP-With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each-account\[aq]s value expressed as a percentage of the column\[aq]s total.-This is useful to get an overview of the relative sizes of account-balances.-For example to obtain an overview of expenses:-.IP-.nf-\f[C]-$ hledger balance expenses -%-             100.0 %  expenses-              50.0 %    food-              50.0 %    supplies+                 $-1    gifts+                 $-1    salary+                  $1  liabilities:debts ---------------------             100.0 %+                   0 \f[R] .fi .PP-Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].-The percentages are always relative to the total sum of each column,-they are never relative to the parent account.-.PP-Since the percentages are relative to the columns sum, it is usually not-useful to calculate percentages if the signs of the amounts are mixed.-Although the results are technically correct, they are most likely-useless.-Especially in a balance report that sums up to zero (eg-\f[C]hledger balance -B\f[R]) all percentage values will be zero.-.PP-This flag does not work if the report contains any mixed commodity-accounts.-If there are mixed commodity accounts in the report be sure to use-\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single-commodity.-.SS Sorting by amount+For more compact output, \[dq]boring\[dq] accounts containing a single+interesting subaccount and no balance of their own+(\f[C]assets:bank\f[R] and \f[C]liabilities\f[R] here) are elided into+the following line, unless \f[C]--no-elide\f[R] is used.+And accounts which have zero balance and no non-zero subaccounts are+omitted, unless \f[C]-E/--empty\f[R] is used. .PP-With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest-(most positive) balances are shown first.-For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest-averaged monthly expenses first.+Account balances in tree mode are \[dq]inclusive\[dq] - they include the+balances of any subaccounts.+Eg, the \f[C]assets\f[R] \f[C]$-1\f[R] balance here includes the+\f[C]$1\f[R] from \f[C]assets:bank:saving\f[R] and the \f[C]$-2\f[R]+from \f[C]assets:cash\f[R].+(And it would include balance posted to the \f[C]assets\f[R] account+itself, if there was any).+Note this causes some repetition, and the final total (\f[C]0\f[R]) is+the sum of the top-level balances, not of all the balances shown. .PP-Revenues and liability balances are typically negative, however, so-\f[C]-S\f[R] shows these in reverse order.-To work around this, you can add \f[C]--invert\f[R] to flip the signs.-Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or-\f[C]incomestatement\f[R], which also support \f[C]-S\f[R].-Eg: \f[C]hledger is -MAS\f[R].-.SS Multicolumn balance report+Each group of sibling accounts is sorted separately, by declaration+order and then by account name.+.SS Multi-period balance report .PP-Multicolumn or tabular balance reports are a very useful hledger-feature, and usually the preferred style.-They share many of the above features, but they show the report as a-table, with columns representing time periods.-This mode is activated by providing a reporting interval.+Multi-period balance reports are a very useful hledger feature,+activated if you provide one of the reporting interval flags, such as+\f[C]-M\f[R]/\f[C]--monthly\f[R].+They are similar to single-period balance reports, but they show the+report as a table, with columns representing one or more successive time+periods.+This is the usually the preferred style of balance report in hledger+(even for a single period). .PP-There are three types of multicolumn balance report, showing different+Multi-period balance reports come in several types, showing different information: .IP "1." 3-By default: each column shows the sum of postings in that period, ie the-account\[aq]s change of balance in that period.+A balance change report: by default, each column shows the sum of+postings in that period, ie the account\[aq]s change of balance in that+period. This is useful eg for a monthly income statement:-.RS 4 .IP .nf \f[C]@@ -3039,11 +2903,10 @@                    ||     $-1      $1       0       0  \f[R] .fi-.RE .IP "2." 3-With \f[C]--cumulative\f[R]: each column shows the ending balance for-that period, accumulating the changes across periods, starting from 0 at-the report start date:+A cumulative end balance report: with \f[C]--cumulative\f[R], each+column shows the end balance for that period, accumulating the changes+across periods, starting from 0 at the report start date: .RS 4 .IP .nf@@ -3063,11 +2926,12 @@ .fi .RE .IP "3." 3-With \f[C]--historical/-H\f[R]: each column shows the actual historical-ending balance for that period, accumulating the changes across periods,-starting from the actual balance at the report start date.-This is useful eg for a multi-period balance sheet, and when you are-showing only the data after a certain start date:+A historical end balance report: with \f[C]--historical/-H\f[R], each+column shows the actual historical end balance for that period,+accumulating the changes across periods, and including the balance from+any postings before the report start date.+This is useful eg for a multi-period balance sheet, and when you want to+see balances only after a certain date: .RS 4 .IP .nf@@ -3091,9 +2955,6 @@ \f[C]--row-total/-T\f[R], since summing end balances generally does not make sense. .PP-Multicolumn balance reports display accounts in flat mode by default; to-see the hierarchy, use \f[C]--tree\f[R].-.PP With a reporting interval (like \f[C]--quarterly\f[R] above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods.@@ -3150,14 +3011,166 @@ When the report is still too wide, a good workaround is to pipe it into \f[C]less -RS\f[R] (-R for colour, -S to chop long lines). Eg: \f[C]hledger bal -D --color=yes | less -RS\f[R].+.SS Depth limiting+.PP+With a \f[C]depth:N\f[R] query, or \f[C]--depth N\f[R] option, or just+\f[C]-N\f[R], balance reports will show accounts only to the specified+depth.+This is very useful to hide low-level accounts and get an overview.+Eg, limiting to depth 1 shows the top-level accounts:+.IP+.nf+\f[C]+$ hledger balance -N -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities+\f[R]+.fi+.PP+Accounts at the depth limit will include the balances of any hidden+subaccounts (even in flat mode, which normally shows exclusive+balances).+.PP+You can also drop account name components from the start of account+names, using \f[C]--drop N\f[R].+This can be useful to hide unwanted top-level detail.+.SS Colour support+.PP+In terminal output, when colour is enabled, the balance command shows+negative amounts in red.+.SS Sorting by amount+.PP+With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest+(most positive) balances are shown first.+For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest+averaged monthly expenses first.+.PP+Revenues and liability balances are typically negative, however, so+\f[C]-S\f[R] shows these in reverse order.+To work around this, you can add \f[C]--invert\f[R] to flip the signs.+Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or+\f[C]incomestatement\f[R], which also support \f[C]-S\f[R].+Eg: \f[C]hledger is -MAS\f[R].+.SS Percentages+.PP+With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each+account\[aq]s value expressed as a percentage of the column\[aq]s total.+This is useful to get an overview of the relative sizes of account+balances.+For example to obtain an overview of expenses:+.IP+.nf+\f[C]+$ hledger balance expenses -%+             100.0 %  expenses+              50.0 %    food+              50.0 %    supplies+--------------------+             100.0 %+\f[R]+.fi+.PP+Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].+The percentages are always relative to the total sum of each column,+they are never relative to the parent account.+.PP+Since the percentages are relative to the columns sum, it is usually not+useful to calculate percentages if the signs of the amounts are mixed.+Although the results are technically correct, they are most likely+useless.+Especially in a balance report that sums up to zero (eg+\f[C]hledger balance -B\f[R]) all percentage values will be zero.+.PP+This flag does not work if the report contains any mixed commodity+accounts.+If there are mixed commodity accounts in the report be sure to use+\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single+commodity.+.PP+.SS Customising single-period balance reports+.PP+You can customise the layout of single-period balance reports with+\f[C]--format FMT\f[R], which sets the format of each line.+Eg:+.IP+.nf+\f[C]+$ hledger balance --format \[dq]%20(account) %12(total)\[dq]+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0+\f[R]+.fi+.PP+The FMT format string (plus a newline) specifies the formatting applied+to each account/balance pair.+It may contain any suitable text, with data fields interpolated like so:+.PP+\f[C]%[MIN][.MAX](FIELDNAME)\f[R]+.IP \[bu] 2+MIN pads with spaces to at least this width (optional)+.IP \[bu] 2+MAX truncates at this width (optional)+.IP \[bu] 2+FIELDNAME must be enclosed in parentheses, and can be one of:+.RS 2+.IP \[bu] 2+\f[C]depth_spacer\f[R] - a number of spaces equal to the account\[aq]s+depth, or if MIN is specified, MIN * depth spaces.+.IP \[bu] 2+\f[C]account\f[R] - the account\[aq]s name+.IP \[bu] 2+\f[C]total\f[R] - the account\[aq]s balance/posted total, right+justified+.RE+.PP+Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:+.IP \[bu] 2+\f[C]%_\f[R] - render on multiple lines, bottom-aligned (the default)+.IP \[bu] 2+\f[C]%\[ha]\f[R] - render on multiple lines, top-aligned+.IP \[bu] 2+\f[C]%,\f[R] - render on one line, comma-separated+.PP+There are some quirks.+Eg in one-line mode, \f[C]%(depth_spacer)\f[R] has no effect, instead+\f[C]%(account)\f[R] has indentation built in.+Experimentation may be needed to get pleasing results.+.PP+Some example formats:+.IP \[bu] 2+\f[C]%(total)\f[R] - the account\[aq]s total+.IP \[bu] 2+\f[C]%-20.20(account)\f[R] - the account\[aq]s name, left justified,+padded to 20 characters and clipped at 20 characters+.IP \[bu] 2+\f[C]%,%-50(account)  %25(total)\f[R] - account name padded to 50+characters, total padded to 20 characters, with multiple commodities+rendered on one line+.IP \[bu] 2+\f[C]%20(total)  %2(depth_spacer)%-(account)\f[R] - the default format+for the single-column balance report .SS Budget report .PP-With \f[C]--budget\f[R], extra columns are displayed showing budget+There is also a special balance report mode for showing budget+performance.+The \f[C]--budget\f[R] flag activates extra columns showing the budget goals for each account and period, if any.-Budget goals are defined by periodic transactions.+For this report, budget goals are defined by periodic transactions. This is very useful for comparing planned and actual income, expenses, time usage, etc.---budget is most often combined with a report interval. .PP For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:

@@ -2274,25 +2274,50 @@  * Menu: -* Classic balance report::-* Customising the classic balance report::+* Single-period flat balance report::+* Single-period tree-mode balance report::+* Multi-period balance report::+* Depth limiting:: * Colour support::-* Flat mode::-* Depth limited balance reports::-* Percentages:: * Sorting by amount::-* Multicolumn balance report::+* Percentages::+* Customising single-period balance reports:: * Budget report::  -File: hledger.info,  Node: Classic balance report,  Next: Customising the classic balance report,  Up: balance+File: hledger.info,  Node: Single-period flat balance report,  Next: Single-period tree-mode balance report,  Up: balance -3.5.1 Classic balance report-----------------------------+3.5.1 Single-period flat balance report+--------------------------------------- -This is the original balance report, as found in Ledger.  It usually-looks like this:+This is the default for hledger's balance command: a flat list of all+(or with a query, matched) accounts, showing full account names.+Accounts are sorted by declaration order if any, and then by account+name.  Accounts which have zero balance are not shown unless+'-E/--empty' is used.  The reported balances' total is shown as the last+line, unless disabled by '-N'/'--no-total'. +$ hledger bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  +++File: hledger.info,  Node: Single-period tree-mode balance report,  Next: Multi-period balance report,  Prev: Single-period flat balance report,  Up: balance++3.5.2 Single-period tree-mode balance report+--------------------------------------------++With the '-t/--tree' flag, accounts are displayed hierarchically,+showing subaccounts as short names indented below their parent.  (This+is the default style in Ledger and in older hledger versions.)+ $ hledger balance                  $-1  assets                   $1    bank:saving@@ -2307,216 +2332,58 @@ --------------------                    0 -   By default, accounts are displayed hierarchically, with subaccounts-indented below their parent, with accounts at each level of the tree-sorted by declaration order if declared, then by account name.--   "Boring" accounts, which contain a single interesting subaccount and-no balance of their own, are elided into the following line for more-compact output.  (Eg above, the "liabilities" account.)  Use-'--no-elide' to prevent this.--   Account balances are "inclusive" - they include the balances of any-subaccounts.--   Accounts which have zero balance (and no non-zero subaccounts) are-omitted.  Use '-E/--empty' to show them.+   For more compact output, "boring" accounts containing a single+interesting subaccount and no balance of their own ('assets:bank' and+'liabilities' here) are elided into the following line, unless+'--no-elide' is used.  And accounts which have zero balance and no+non-zero subaccounts are omitted, unless '-E/--empty' is used. -   A final total is displayed by default; use '-N/--no-total' to-suppress it, eg:+   Account balances in tree mode are "inclusive" - they include the+balances of any subaccounts.  Eg, the 'assets' '$-1' balance here+includes the '$1' from 'assets:bank:saving' and the '$-2' from+'assets:cash'.  (And it would include balance posted to the 'assets'+account itself, if there was any).  Note this causes some repetition,+and the final total ('0') is the sum of the top-level balances, not of+all the balances shown. -$ hledger balance -p 2008/6 expenses --no-total-                  $2  expenses-                  $1    food-                  $1    supplies+   Each group of sibling accounts is sorted separately, by declaration+order and then by account name.  -File: hledger.info,  Node: Customising the classic balance report,  Next: Colour support,  Prev: Classic balance report,  Up: balance--3.5.2 Customising the classic balance report-----------------------------------------------You can customise the layout of classic balance reports with '--format-FMT':+File: hledger.info,  Node: Multi-period balance report,  Next: ,  Prev: Single-period tree-mode balance report,  Up: balance -$ hledger balance --format "%20(account) %12(total)"-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1+3.5.3 Multi-period balance report ----------------------------------                                0 -   The FMT format string (plus a newline) specifies the formatting-applied to each account/balance pair.  It may contain any suitable text,-with data fields interpolated like so:--   '%[MIN][.MAX](FIELDNAME)'--   * MIN pads with spaces to at least this width (optional)--   * MAX truncates at this width (optional)--   * FIELDNAME must be enclosed in parentheses, and can be one of:--        * 'depth_spacer' - a number of spaces equal to the account's-          depth, or if MIN is specified, MIN * depth spaces.-        * 'account' - the account's name-        * 'total' - the account's balance/posted total, right justified--   Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:--   * '%_' - render on multiple lines, bottom-aligned (the default)-   * '%^' - render on multiple lines, top-aligned-   * '%,' - render on one line, comma-separated--   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no-effect, instead '%(account)' has indentation built in.  Experimentation-may be needed to get pleasing results.--   Some example formats:--   * '%(total)' - the account's total-   * '%-20.20(account)' - the account's name, left justified, padded to-     20 characters and clipped at 20 characters-   * '%,%-50(account) %25(total)' - account name padded to 50-     characters, total padded to 20 characters, with multiple-     commodities rendered on one line-   * '%20(total) %2(depth_spacer)%-(account)' - the default format for-     the single-column balance report---File: hledger.info,  Node: Colour support,  Next: Flat mode,  Prev: Customising the classic balance report,  Up: balance--3.5.3 Colour support-----------------------In terminal output, when colour is enabled, the balance command shows-negative amounts in red.---File: hledger.info,  Node: Flat mode,  Next: Depth limited balance reports,  Prev: Colour support,  Up: balance--3.5.4 Flat mode------------------To see a flat list instead of the default hierarchical display, use-'--flat'.  In this mode, accounts (unless depth-clipped) show their full-names and "exclusive" balance, excluding any subaccount balances.  In-this mode, you can also use '--drop N' to omit the first few account-name components.--$ hledger balance -p 2008/6 expenses -N --flat --drop 1-                  $1  food-                  $1  supplies---File: hledger.info,  Node: Depth limited balance reports,  Next: Percentages,  Prev: Flat mode,  Up: balance--3.5.5 Depth limited balance reports--------------------------------------With '--depth N' or 'depth:N' or just '-N', balance reports show-accounts only to the specified numeric depth.  This is very useful to-summarise a complex set of accounts and get an overview.--$ hledger balance -N -1-                 $-1  assets-                  $2  expenses-                 $-2  income-                  $1  liabilities--   Flat-mode balance reports, which normally show exclusive balances,-show inclusive balances at the depth limit.---File: hledger.info,  Node: Percentages,  Next: Sorting by amount,  Prev: Depth limited balance reports,  Up: balance--3.5.6 Percentages--------------------With '-%' or '--percent', balance reports show each account's value-expressed as a percentage of the column's total.  This is useful to get-an overview of the relative sizes of account balances.  For example to-obtain an overview of expenses:--$ hledger balance expenses -%-             100.0 %  expenses-              50.0 %    food-              50.0 %    supplies----------------------             100.0 %--   Note that '--tree' does not have an effect on '-%'.  The percentages-are always relative to the total sum of each column, they are never-relative to the parent account.--   Since the percentages are relative to the columns sum, it is usually-not useful to calculate percentages if the signs of the amounts are-mixed.  Although the results are technically correct, they are most-likely useless.  Especially in a balance report that sums up to zero (eg-'hledger balance -B') all percentage values will be zero.--   This flag does not work if the report contains any mixed commodity-accounts.  If there are mixed commodity accounts in the report be sure-to use '-V' or '-B' to coerce the report into using a single commodity.---File: hledger.info,  Node: Sorting by amount,  Next: Multicolumn balance report,  Prev: Percentages,  Up: balance--3.5.7 Sorting by amount--------------------------With '-S'/'--sort-amount', accounts with the largest (most positive)-balances are shown first.  For example, 'hledger bal expenses -MAS'-shows your biggest averaged monthly expenses first.--   Revenues and liability balances are typically negative, however, so-'-S' shows these in reverse order.  To work around this, you can add-'--invert' to flip the signs.  Or, use one of the sign-flipping reports-like 'balancesheet' or 'incomestatement', which also support '-S'.  Eg:-'hledger is -MAS'.---File: hledger.info,  Node: Multicolumn balance report,  Next: Budget report,  Prev: Sorting by amount,  Up: balance--3.5.8 Multicolumn balance report---------------------------------+Multi-period balance reports are a very useful hledger feature,+activated if you provide one of the reporting interval flags, such as+'-M'/'--monthly'.  They are similar to single-period balance reports,+but they show the report as a table, with columns representing one or+more successive time periods.  This is the usually the preferred style+of balance report in hledger (even for a single period). -Multicolumn or tabular balance reports are a very useful hledger-feature, and usually the preferred style.  They share many of the above-features, but they show the report as a table, with columns representing-time periods.  This mode is activated by providing a reporting interval.+   Multi-period balance reports come in several types, showing different+information: -   There are three types of multicolumn balance report, showing-different information:+  1. A balance change report: by default, each column shows the sum of+     postings in that period, ie the account's change of balance in that+     period.  This is useful eg for a monthly income statement: -  1. By default: each column shows the sum of postings in that period,-     ie the account's change of balance in that period.  This is useful-     eg for a monthly income statement:+$ hledger balance --quarterly income expenses -E+Balance changes in 2008: -     $ hledger balance --quarterly income expenses -E-     Balance changes in 2008:-     -                        ||  2008q1  2008q2  2008q3  2008q4 -     ===================++=================================-      expenses:food     ||       0      $1       0       0 -      expenses:supplies ||       0      $1       0       0 -      income:gifts      ||       0     $-1       0       0 -      income:salary     ||     $-1       0       0       0 -     -------------------++----------------------------------                        ||     $-1      $1       0       0 +                   ||  2008q1  2008q2  2008q3  2008q4 +===================++=================================+ expenses:food     ||       0      $1       0       0 + expenses:supplies ||       0      $1       0       0 + income:gifts      ||       0     $-1       0       0 + income:salary     ||     $-1       0       0       0 +-------------------++---------------------------------+                   ||     $-1      $1       0       0  -  2. With '--cumulative': each column shows the ending balance for that-     period, accumulating the changes across periods, starting from 0 at-     the report start date:+  2. A cumulative end balance report: with '--cumulative', each column+     shows the end balance for that period, accumulating the changes+     across periods, starting from 0 at the report start date:       $ hledger balance --quarterly income expenses -E --cumulative      Ending balances (cumulative) in 2008:@@ -2530,11 +2397,12 @@      -------------------++-------------------------------------------------                         ||         $-1           0           0           0  -  3. With '--historical/-H': each column shows the actual historical-     ending balance for that period, accumulating the changes across-     periods, starting from the actual balance at the report start date.-     This is useful eg for a multi-period balance sheet, and when you-     are showing only the data after a certain start date:+  3. A historical end balance report: with '--historical/-H', each+     column shows the actual historical end balance for that period,+     accumulating the changes across periods, and including the balance+     from any postings before the report start date.  This is useful eg+     for a multi-period balance sheet, and when you want to see balances+     only after a certain date:       $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1      Ending balances (historical) in 2008/04/01-2008/12/31:@@ -2552,9 +2420,6 @@ '--row-total/-T', since summing end balances generally does not make sense. -   Multicolumn balance reports display accounts in flat mode by default;-to see the hierarchy, use '--tree'.-    With a reporting interval (like '--quarterly' above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods.  This is so that the first and last periods@@ -2605,17 +2470,158 @@ into 'less -RS' (-R for colour, -S to chop long lines).  Eg: 'hledger bal -D --color=yes | less -RS'. +3.5.4 Depth limiting+--------------------++With a 'depth:N' query, or '--depth N' option, or just '-N', balance+reports will show accounts only to the specified depth.  This is very+useful to hide low-level accounts and get an overview.  Eg, limiting to+depth 1 shows the top-level accounts:++$ hledger balance -N -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities++   Accounts at the depth limit will include the balances of any hidden+subaccounts (even in flat mode, which normally shows exclusive+balances).++   You can also drop account name components from the start of account+names, using '--drop N'.  This can be useful to hide unwanted top-level+detail.+ -File: hledger.info,  Node: Budget report,  Prev: Multicolumn balance report,  Up: balance+File: hledger.info,  Node: Colour support,  Next: Sorting by amount,  Prev: ,  Up: balance +3.5.5 Colour support+--------------------++In terminal output, when colour is enabled, the balance command shows+negative amounts in red.+++File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Colour support,  Up: balance++3.5.6 Sorting by amount+-----------------------++With '-S'/'--sort-amount', accounts with the largest (most positive)+balances are shown first.  For example, 'hledger bal expenses -MAS'+shows your biggest averaged monthly expenses first.++   Revenues and liability balances are typically negative, however, so+'-S' shows these in reverse order.  To work around this, you can add+'--invert' to flip the signs.  Or, use one of the sign-flipping reports+like 'balancesheet' or 'incomestatement', which also support '-S'.  Eg:+'hledger is -MAS'.+++File: hledger.info,  Node: Percentages,  Next: Customising single-period balance reports,  Prev: Sorting by amount,  Up: balance++3.5.7 Percentages+-----------------++With '-%' or '--percent', balance reports show each account's value+expressed as a percentage of the column's total.  This is useful to get+an overview of the relative sizes of account balances.  For example to+obtain an overview of expenses:++$ hledger balance expenses -%+             100.0 %  expenses+              50.0 %    food+              50.0 %    supplies+--------------------+             100.0 %++   Note that '--tree' does not have an effect on '-%'.  The percentages+are always relative to the total sum of each column, they are never+relative to the parent account.++   Since the percentages are relative to the columns sum, it is usually+not useful to calculate percentages if the signs of the amounts are+mixed.  Although the results are technically correct, they are most+likely useless.  Especially in a balance report that sums up to zero (eg+'hledger balance -B') all percentage values will be zero.++   This flag does not work if the report contains any mixed commodity+accounts.  If there are mixed commodity accounts in the report be sure+to use '-V' or '-B' to coerce the report into using a single commodity.+++File: hledger.info,  Node: Customising single-period balance reports,  Next: Budget report,  Prev: Percentages,  Up: balance++3.5.8 Customising single-period balance reports+-----------------------------------------------++You can customise the layout of single-period balance reports with+'--format FMT', which sets the format of each line.  Eg:++$ hledger balance --format "%20(account) %12(total)"+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0++   The FMT format string (plus a newline) specifies the formatting+applied to each account/balance pair.  It may contain any suitable text,+with data fields interpolated like so:++   '%[MIN][.MAX](FIELDNAME)'++   * MIN pads with spaces to at least this width (optional)++   * MAX truncates at this width (optional)++   * FIELDNAME must be enclosed in parentheses, and can be one of:++        * 'depth_spacer' - a number of spaces equal to the account's+          depth, or if MIN is specified, MIN * depth spaces.+        * 'account' - the account's name+        * 'total' - the account's balance/posted total, right justified++   Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++   * '%_' - render on multiple lines, bottom-aligned (the default)+   * '%^' - render on multiple lines, top-aligned+   * '%,' - render on one line, comma-separated++   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no+effect, instead '%(account)' has indentation built in.  Experimentation+may be needed to get pleasing results.++   Some example formats:++   * '%(total)' - the account's total+   * '%-20.20(account)' - the account's name, left justified, padded to+     20 characters and clipped at 20 characters+   * '%,%-50(account) %25(total)' - account name padded to 50+     characters, total padded to 20 characters, with multiple+     commodities rendered on one line+   * '%20(total) %2(depth_spacer)%-(account)' - the default format for+     the single-column balance report+++File: hledger.info,  Node: Budget report,  Prev: Customising single-period balance reports,  Up: balance+ 3.5.9 Budget report ------------------- -With '--budget', extra columns are displayed showing budget goals for-each account and period, if any.  Budget goals are defined by periodic-transactions.  This is very useful for comparing planned and actual-income, expenses, time usage, etc.  -budget is most often combined with-a report interval.+There is also a special balance report mode for showing budget+performance.  The '--budget' flag activates extra columns showing the+budget goals for each account and period, if any.  For this report,+budget goals are defined by periodic transactions.  This is very useful+for comparing planned and actual income, expenses, time usage, etc.     For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:@@ -4297,99 +4303,98 @@ Ref: #aregister-and-custom-posting-dates76676 Node: balance77497 Ref: #balance77614-Node: Classic balance report79240-Ref: #classic-balance-report79413-Node: Customising the classic balance report80737-Ref: #customising-the-classic-balance-report80965-Node: Colour support83041-Ref: #colour-support83208-Node: Flat mode83304-Ref: #flat-mode83452-Node: Depth limited balance reports83865-Ref: #depth-limited-balance-reports84050-Node: Percentages84506-Ref: #percentages84663-Node: Sorting by amount85800-Ref: #sorting-by-amount85966-Node: Multicolumn balance report86460-Ref: #multicolumn-balance-report86646-Node: Budget report92243-Ref: #budget-report92377-Node: Budget report start date97666-Ref: #budget-report-start-date97831-Node: Nested budgets99163-Ref: #nested-budgets99308-Node: balancesheet102748-Ref: #balancesheet102884-Node: balancesheetequity104396-Ref: #balancesheetequity104545-Node: cashflow105621-Ref: #cashflow105743-Node: check106959-Ref: #check107062-Node: Basic checks107667-Ref: #basic-checks107783-Node: Strict checks108276-Ref: #strict-checks108415-Node: Other checks108658-Ref: #other-checks108796-Node: Add-on checks109094-Ref: #add-on-checks109212-Node: close109665-Ref: #close109767-Node: close usage111289-Ref: #close-usage111382-Node: codes114195-Ref: #codes114303-Node: commodities115015-Ref: #commodities115142-Node: descriptions115224-Ref: #descriptions115352-Node: diff115656-Ref: #diff115762-Node: files116809-Ref: #files116909-Node: help117056-Ref: #help117156-Node: import118237-Ref: #import118351-Node: Importing balance assignments119273-Ref: #importing-balance-assignments119454-Node: Commodity display styles120103-Ref: #commodity-display-styles120274-Node: incomestatement120403-Ref: #incomestatement120536-Node: notes121881-Ref: #notes121995-Node: rewrite122363-Ref: #rewrite122469-Node: Re-write rules in a file124375-Ref: #re-write-rules-in-a-file124536-Node: Diff output format125685-Ref: #diff-output-format125866-Node: rewrite vs print --auto126958-Ref: #rewrite-vs.-print---auto127116-Node: roi127672-Ref: #roi127770-Node: stats139980-Ref: #stats140079-Node: tags140867-Ref: #tags140965-Node: test141484-Ref: #test141592-Node: Add-on commands142339-Ref: #add-on-commands142485-Node: Add-on command flags143249-Ref: #add-on-command-flags143423-Node: Making add-on commands144003-Ref: #making-add-on-commands144157-Node: ENVIRONMENT144750-Ref: #environment144862-Node: FILES145847-Ref: #files-1145950-Node: LIMITATIONS146163-Ref: #limitations146282-Node: TROUBLESHOOTING147025-Ref: #troubleshooting147138+Node: Single-period flat balance report79269+Ref: #single-period-flat-balance-report79475+Node: Single-period tree-mode balance report80179+Ref: #single-period-tree-mode-balance-report80431+Node: Multi-period balance report81876+Ref: #multi-period-balance-report82073+Ref: #depth-limiting-187766+Node: Colour support88462+Ref: #colour-support88599+Node: Sorting by amount88695+Ref: #sorting-by-amount88849+Node: Percentages89343+Ref: #percentages89512+Node: Customising single-period balance reports90649+Ref: #customising-single-period-balance-reports90874+Node: Budget report92997+Ref: #budget-report93146+Node: Budget report start date98476+Ref: #budget-report-start-date98641+Node: Nested budgets99973+Ref: #nested-budgets100118+Node: balancesheet103558+Ref: #balancesheet103694+Node: balancesheetequity105206+Ref: #balancesheetequity105355+Node: cashflow106431+Ref: #cashflow106553+Node: check107769+Ref: #check107872+Node: Basic checks108477+Ref: #basic-checks108593+Node: Strict checks109086+Ref: #strict-checks109225+Node: Other checks109468+Ref: #other-checks109606+Node: Add-on checks109904+Ref: #add-on-checks110022+Node: close110475+Ref: #close110577+Node: close usage112099+Ref: #close-usage112192+Node: codes115005+Ref: #codes115113+Node: commodities115825+Ref: #commodities115952+Node: descriptions116034+Ref: #descriptions116162+Node: diff116466+Ref: #diff116572+Node: files117619+Ref: #files117719+Node: help117866+Ref: #help117966+Node: import119047+Ref: #import119161+Node: Importing balance assignments120083+Ref: #importing-balance-assignments120264+Node: Commodity display styles120913+Ref: #commodity-display-styles121084+Node: incomestatement121213+Ref: #incomestatement121346+Node: notes122691+Ref: #notes122805+Node: rewrite123173+Ref: #rewrite123279+Node: Re-write rules in a file125185+Ref: #re-write-rules-in-a-file125346+Node: Diff output format126495+Ref: #diff-output-format126676+Node: rewrite vs print --auto127768+Ref: #rewrite-vs.-print---auto127926+Node: roi128482+Ref: #roi128580+Node: stats140790+Ref: #stats140889+Node: tags141677+Ref: #tags141775+Node: test142294+Ref: #test142402+Node: Add-on commands143149+Ref: #add-on-commands143295+Node: Add-on command flags144059+Ref: #add-on-command-flags144233+Node: Making add-on commands144813+Ref: #making-add-on-commands144967+Node: ENVIRONMENT145560+Ref: #environment145672+Node: FILES146657+Ref: #files-1146760+Node: LIMITATIONS146973+Ref: #limitations147092+Node: TROUBLESHOOTING147835+Ref: #troubleshooting147948  End Tag Table

@@ -1969,10 +1969,30 @@         The balance command can produce several styles of report: -   Classic balance report-       This is the original balance report, as found in  Ledger.   It  usually-       looks like this:+   Single-period flat balance report+       This is the default for hledger's balance command: a flat list  of  all+       (or  with  a query, matched) accounts, showing full account names.  Ac-+       counts are sorted by declaration order if  any,  and  then  by  account+       name.  Accounts which have zero balance are not shown unless -E/--empty+       is used.  The reported balances' total is shown as the last  line,  un-+       less disabled by -N/--no-total. +              $ hledger bal+                                $1  assets:bank:saving+                               $-2  assets:cash+                                $1  expenses:food+                                $1  expenses:supplies+                               $-1  income:gifts+                               $-1  income:salary+                                $1  liabilities:debts+              --------------------+                                 0++   Single-period tree-mode balance report+       With the -t/--tree flag, accounts are displayed hierarchically, showing+       subaccounts as short names indented below their parent.  (This  is  the+       default style in Ledger and in older hledger versions.)+               $ hledger balance                                $-1  assets                                 $1    bank:saving@@ -1987,189 +2007,52 @@               --------------------                                  0 -       By default, accounts are displayed hierarchically, with subaccounts in--       dented below their parent, with accounts at  each  level  of  the  tree-       sorted by declaration order if declared, then by account name.--       "Boring" accounts, which contain a single interesting subaccount and no-       balance of their own, are elided into the following line for more  com--       pact  output.  (Eg above, the "liabilities" account.) Use --no-elide to-       prevent this.--       Account balances are "inclusive" - they include  the  balances  of  any-       subaccounts.--       Accounts  which  have  zero  balance  (and no non-zero subaccounts) are-       omitted.  Use -E/--empty to show them.--       A final total is displayed by default; use  -N/--no-total  to  suppress-       it, eg:--              $ hledger balance -p 2008/6 expenses --no-total-                                $2  expenses-                                $1    food-                                $1    supplies--   Customising the classic balance report-       You  can  customise the layout of classic balance reports with --format-       FMT:--              $ hledger balance --format "%20(account) %12(total)"-                            assets          $-1-                       bank:saving           $1-                              cash          $-2-                          expenses           $2-                              food           $1-                          supplies           $1-                            income          $-2-                             gifts          $-1-                            salary          $-1-                 liabilities:debts           $1-              ----------------------------------                                              0--       The FMT format string (plus a newline) specifies the formatting applied-       to  each  account/balance pair.  It may contain any suitable text, with-       data fields interpolated like so:--       %[MIN][.MAX](FIELDNAME)--       o MIN pads with spaces to at least this width (optional)--       o MAX truncates at this width (optional)--       o FIELDNAME must be enclosed in parentheses, and can be one of:--         o depth_spacer - a number of spaces equal to the account's depth,  or-           if MIN is specified, MIN * depth spaces.--         o account - the account's name--         o total - the account's balance/posted total, right justified--       Also,  FMT  can begin with an optional prefix to control how multi-com--       modity amounts are rendered:--       o %_ - render on multiple lines, bottom-aligned (the default)--       o %^ - render on multiple lines, top-aligned--       o %, - render on one line, comma-separated--       There are some quirks.  Eg in one-line mode, %(depth_spacer) has no ef--       fect, instead %(account) has indentation built in.  Experimentation may-       be needed to get pleasing results.--       Some example formats:--       o %(total) - the account's total--       o %-20.20(account) - the account's name, left justified, padded  to  20-         characters and clipped at 20 characters--       o %,%-50(account)   %25(total)  - account name padded to 50 characters,-         total padded to 20 characters, with multiple commodities rendered  on-         one line--       o %20(total)   %2(depth_spacer)%-(account) - the default format for the-         single-column balance report--   Colour support-       In terminal output, when colour is enabled, the balance  command  shows-       negative amounts in red.--   Flat mode-       To  see  a  flat  list instead of the default hierarchical display, use-       --flat.  In this mode, accounts (unless depth-clipped) show their  full-       names  and  "exclusive" balance, excluding any subaccount balances.  In-       this mode, you can also use --drop N to omit the first few account name-       components.--              $ hledger balance -p 2008/6 expenses -N --flat --drop 1-                                $1  food-                                $1  supplies--   Depth limited balance reports-       With  --depth  N  or  depth:N or just -N, balance reports show accounts-       only to the specified numeric depth.  This is very useful to  summarise-       a complex set of accounts and get an overview.--              $ hledger balance -N -1-                               $-1  assets-                                $2  expenses-                               $-2  income-                                $1  liabilities--       Flat-mode balance reports, which normally show exclusive balances, show-       inclusive balances at the depth limit.--   Percentages-       With -% or --percent, balance reports show  each  account's  value  ex--       pressed  as  a percentage of the column's total.  This is useful to get-       an overview of the relative sizes of account balances.  For example  to-       obtain an overview of expenses:--              $ hledger balance expenses -%-                           100.0 %  expenses-                            50.0 %    food-                            50.0 %    supplies-              ---------------------                           100.0 %--       Note  that  --tree  does not have an effect on -%.  The percentages are-       always relative to the total sum of each column, they are  never  rela--       tive to the parent account.--       Since  the  percentages  are relative to the columns sum, it is usually-       not useful to calculate percentages if the signs  of  the  amounts  are-       mixed.   Although  the  results  are technically correct, they are most-       likely useless.  Especially in a balance report that sums  up  to  zero-       (eg hledger balance -B) all percentage values will be zero.--       This  flag does not work if the report contains any mixed commodity ac--       counts.  If there are mixed commodity accounts in the report be sure to-       use -V or -B to coerce the report into using a single commodity.+       For  more  compact output, "boring" accounts containing a single inter-+       esting subaccount and no balance of their own (assets:bank and liabili-+       ties  here)  are  elided  into the following line, unless --no-elide is+       used.  And accounts which have zero balance and no non-zero subaccounts+       are omitted, unless -E/--empty is used. -   Sorting by amount-       With  -S/--sort-amount,  accounts with the largest (most positive) bal--       ances are shown first.  For example, hledger bal  expenses  -MAS  shows-       your biggest averaged monthly expenses first.+       Account  balances  in tree mode are "inclusive" - they include the bal-+       ances of any subaccounts.  Eg, the assets $-1 balance here includes the+       $1 from assets:bank:saving and the $-2 from assets:cash.  (And it would+       include balance posted to the assets account itself, if there was any).+       Note this causes some repetition, and the final total (0) is the sum of+       the top-level balances, not of all the balances shown. -       Revenues  and liability balances are typically negative, however, so -S-       shows these in reverse order.  To work around this, you can  add  --in--       vert  to flip the signs.  Or, use one of the sign-flipping reports like-       balancesheet or incomestatement, which also support -S.  Eg: hledger is-       -MAS.+       Each group of sibling accounts is sorted separately, by declaration or-+       der and then by account name. -   Multicolumn balance report-       Multicolumn  or  tabular balance reports are a very useful hledger fea--       ture, and usually the preferred style.  They share many  of  the  above-       features,  but they show the report as a table, with columns represent--       ing time periods.  This mode is activated by providing a reporting  in--       terval.+   Multi-period balance report+       Multi-period  balance  reports are a very useful hledger feature, acti-+       vated if you provide one of  the  reporting  interval  flags,  such  as+       -M/--monthly.   They  are similar to single-period balance reports, but+       they show the report as a table, with columns representing one or  more+       successive  time  periods.   This is the usually the preferred style of+       balance report in hledger (even for a single period). -       There  are three types of multicolumn balance report, showing different+       Multi-period balance reports come in several types,  showing  different        information: -       1. By default: each column shows the sum of postings in that period, ie-          the  account's  change of balance in that period.  This is useful eg-          for a monthly income statement:+       1. A  balance  change  report: by default, each column shows the sum of+          postings in that period, ie the account's change of balance in  that+          period.  This is useful eg for a monthly income statement: -                  $ hledger balance --quarterly income expenses -E-                  Balance changes in 2008:+          $ hledger balance --quarterly income expenses -E+          Balance changes in 2008: -                                     ||  2008q1  2008q2  2008q3  2008q4-                  ===================++=================================-                   expenses:food     ||       0      $1       0       0-                   expenses:supplies ||       0      $1       0       0-                   income:gifts      ||       0     $-1       0       0-                   income:salary     ||     $-1       0       0       0-                  -------------------++----------------------------------                                     ||     $-1      $1       0       0+                             ||  2008q1  2008q2  2008q3  2008q4+          ===================++=================================+           expenses:food     ||       0      $1       0       0+           expenses:supplies ||       0      $1       0       0+           income:gifts      ||       0     $-1       0       0+           income:salary     ||     $-1       0       0       0+          -------------------++---------------------------------+                             ||     $-1      $1       0       0 -       2. With --cumulative: each column shows the ending balance for that pe--          riod,  accumulating  the  changes across periods, starting from 0 at-          the report start date:+       2. A  cumulative  end  balance  report:  with --cumulative, each column+          shows the end balance for  that  period,  accumulating  the  changes+          across periods, starting from 0 at the report start date:                    $ hledger balance --quarterly income expenses -E --cumulative                   Ending balances (cumulative) in 2008:@@ -2183,11 +2066,12 @@                   -------------------++-------------------------------------------------                                      ||         $-1           0           0           0 -       3. With --historical/-H: each column shows the actual historical ending-          balance  for  that  period, accumulating the changes across periods,-          starting from the actual balance at the report start date.  This  is-          useful eg for a multi-period balance sheet, and when you are showing-          only the data after a certain start date:+       3. A  historical  end balance report: with --historical/-H, each column+          shows the actual historical end balance for that period,  accumulat-+          ing  the  changes across periods, and including the balance from any+          postings before the report start date.  This  is  useful  eg  for  a+          multi-period  balance  sheet, and when you want to see balances only+          after a certain date:                    $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1                   Ending balances (historical) in 2008/04/01-2008/12/31:@@ -2204,26 +2088,23 @@        Note that --cumulative or --historical/-H disable --row-total/-T, since        summing end balances generally does not make sense. -       Multicolumn  balance  reports display accounts in flat mode by default;-       to see the hierarchy, use --tree.--       With  a  reporting  interval  (like  --quarterly  above),  the   report-       start/end  dates  will  be adjusted if necessary so that they encompass+       With   a  reporting  interval  (like  --quarterly  above),  the  report+       start/end dates will be adjusted if necessary so  that  they  encompass        the displayed report periods.  This is so that the first and last peri-        ods will be "full" and comparable to the others. -       The  -E/--empty  flag  does  two things in multicolumn balance reports:+       The -E/--empty flag does two things  in  multicolumn  balance  reports:        first, the report will show all columns within the specified report pe--       riod  (without -E, leading and trailing columns with all zeroes are not-       shown).  Second, all accounts which existed at the  report  start  date-       will  be  considered, not just the ones with activity during the report-       period (use -E to include low-activity accounts which  would  otherwise+       riod (without -E, leading and trailing columns with all zeroes are  not+       shown).   Second,  all  accounts which existed at the report start date+       will be considered, not just the ones with activity during  the  report+       period  (use  -E to include low-activity accounts which would otherwise        would be omitted).         The -T/--row-total flag adds an additional column showing the total for        each row. -       The -A/--average flag adds a column showing the average value  in  each+       The  -A/--average  flag adds a column showing the average value in each        row.         Here's an example of all three:@@ -2244,27 +2125,153 @@                (Average is rounded to the dollar here since all journal amounts are) -       The  --transpose flag can be used to exchange the rows and columns of a+       The --transpose flag can be used to exchange the rows and columns of  a        multicolumn report. -       When showing multicommodity amounts, multicolumn balance  reports  will+       When  showing  multicommodity amounts, multicolumn balance reports will        elide any amounts which have more than two commodities, since otherwise-       columns could get very wide.  The --no-elide flag disables this.   Hid--       ing  totals  with the -N/--no-total flag can also help reduce the width+       columns  could get very wide.  The --no-elide flag disables this.  Hid-+       ing totals with the -N/--no-total flag can also help reduce  the  width        of multicommodity reports.         When the report is still too wide, a good workaround is to pipe it into-       less  -RS  (-R  for colour, -S to chop long lines).  Eg: hledger bal -D+       less -RS (-R for colour, -S to chop long lines).  Eg:  hledger  bal  -D        --color=yes | less -RS. +   Depth limiting+       With  a depth:N query, or --depth N option, or just -N, balance reports+       will show accounts only to the specified depth.  This is very useful to+       hide  low-level  accounts and get an overview.  Eg, limiting to depth 1+       shows the top-level accounts:++              $ hledger balance -N -1+                               $-1  assets+                                $2  expenses+                               $-2  income+                                $1  liabilities++       Accounts at the depth limit will include the  balances  of  any  hidden+       subaccounts  (even  in  flat  mode, which normally shows exclusive bal-+       ances).++       You can also drop account name components from  the  start  of  account+       names,  using  --drop N.  This can be useful to hide unwanted top-level+       detail.++   Colour support+       In terminal output, when colour is enabled, the balance  command  shows+       negative amounts in red.++   Sorting by amount+       With  -S/--sort-amount,  accounts with the largest (most positive) bal-+       ances are shown first.  For example, hledger bal  expenses  -MAS  shows+       your biggest averaged monthly expenses first.++       Revenues  and liability balances are typically negative, however, so -S+       shows these in reverse order.  To work around this, you can  add  --in-+       vert  to flip the signs.  Or, use one of the sign-flipping reports like+       balancesheet or incomestatement, which also support -S.  Eg: hledger is+       -MAS.++   Percentages+       With  -%  or  --percent,  balance reports show each account's value ex-+       pressed as a percentage of the column's total.  This is useful  to  get+       an  overview of the relative sizes of account balances.  For example to+       obtain an overview of expenses:++              $ hledger balance expenses -%+                           100.0 %  expenses+                            50.0 %    food+                            50.0 %    supplies+              --------------------+                           100.0 %++       Note that --tree does not have an effect on -%.   The  percentages  are+       always  relative  to the total sum of each column, they are never rela-+       tive to the parent account.++       Since the percentages are relative to the columns sum,  it  is  usually+       not  useful  to  calculate  percentages if the signs of the amounts are+       mixed.  Although the results are technically  correct,  they  are  most+       likely  useless.   Especially  in a balance report that sums up to zero+       (eg hledger balance -B) all percentage values will be zero.++       This flag does not work if the report contains any mixed commodity  ac-+       counts.  If there are mixed commodity accounts in the report be sure to+       use -V or -B to coerce the report into using a single commodity.++   Customising single-period balance reports+       You can customise the layout  of  single-period  balance  reports  with+       --format FMT, which sets the format of each line.  Eg:++              $ hledger balance --format "%20(account) %12(total)"+                            assets          $-1+                       bank:saving           $1+                              cash          $-2+                          expenses           $2+                              food           $1+                          supplies           $1+                            income          $-2+                             gifts          $-1+                            salary          $-1+                 liabilities:debts           $1+              ---------------------------------+                                              0++       The FMT format string (plus a newline) specifies the formatting applied+       to each account/balance pair.  It may contain any suitable  text,  with+       data fields interpolated like so:++       %[MIN][.MAX](FIELDNAME)++       o MIN pads with spaces to at least this width (optional)++       o MAX truncates at this width (optional)++       o FIELDNAME must be enclosed in parentheses, and can be one of:++         o depth_spacer  - a number of spaces equal to the account's depth, or+           if MIN is specified, MIN * depth spaces.++         o account - the account's name++         o total - the account's balance/posted total, right justified++       Also, FMT can begin with an optional prefix to control  how  multi-com-+       modity amounts are rendered:++       o %_ - render on multiple lines, bottom-aligned (the default)++       o %^ - render on multiple lines, top-aligned++       o %, - render on one line, comma-separated++       There are some quirks.  Eg in one-line mode, %(depth_spacer) has no ef-+       fect, instead %(account) has indentation built in.  Experimentation may+       be needed to get pleasing results.++       Some example formats:++       o %(total) - the account's total++       o %-20.20(account)  -  the account's name, left justified, padded to 20+         characters and clipped at 20 characters++       o %,%-50(account)  %25(total) - account name padded to  50  characters,+         total  padded to 20 characters, with multiple commodities rendered on+         one line++       o %20(total)  %2(depth_spacer)%-(account) - the default format for  the+         single-column balance report+    Budget report-       With --budget, extra columns are displayed  showing  budget  goals  for-       each  account and period, if any.  Budget goals are defined by periodic-       transactions.  This is very useful for comparing planned and actual in--       come,  expenses, time usage, etc.  --budget is most often combined with-       a report interval.+       There  is also a special balance report mode for showing budget perfor-+       mance.  The --budget flag activates extra columns  showing  the  budget+       goals  for  each  account  and period, if any.  For this report, budget+       goals are defined by periodic transactions.  This is  very  useful  for+       comparing planned and actual income, expenses, time usage, etc. -       For example, you can take average monthly expenses in  the  common  ex-+       For  example,  you  can take average monthly expenses in the common ex-        pense categories to construct a minimal monthly budget:                ;; Budget@@ -2311,26 +2318,26 @@         This is different from a normal balance report in several ways: -       o Only  accounts  with budget goals during the report period are shown,+       o Only accounts with budget goals during the report period  are  shown,          by default. -       o In each column, in square brackets after the  actual  amount,  budget-         goal  amounts are shown, and the actual/goal percentage.  (Note: bud-+       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@@ -2372,12 +2379,12 @@        For more examples and notes, see Budgeting.     Budget report start date-       This  might  be  a bug, but for now: when making budget reports, it's a+       This might be a bug, but for now: when making budget  reports,  it's  a        good idea to explicitly set the report's start date to the first day of-       a  reporting  period,  because a periodic rule like ~ monthly generates-       its transactions on the 1st of each month, and if your journal  has  no-       regular  transactions  on  the 1st, the default report start date could-       exclude that budget goal, which can be a little  surprising.   Eg  here+       a reporting period, because a periodic rule like  ~  monthly  generates+       its  transactions  on the 1st of each month, and if your journal has no+       regular transactions on the 1st, the default report  start  date  could+       exclude  that  budget  goal, which can be a little surprising.  Eg here        the default report period is just the day of 2020-01-15:                ~ monthly in 2020@@ -2396,9 +2403,9 @@               --------------++------------                             ||       $400 -       To  avoid  this,  specify  the  budget report's period, or at least the-       start date, with -b/-e/-p/date:, to ensure it includes the budget  goal-       transactions  (periodic  transactions)  that  you  want.  Eg, adding -b+       To avoid this, specify the budget report's  period,  or  at  least  the+       start  date, with -b/-e/-p/date:, to ensure it includes the budget goal+       transactions (periodic transactions) that  you  want.   Eg,  adding  -b        2020/1/1 to the above:                $ hledger bal expenses --budget -b 2020/1/1@@ -2411,12 +2418,12 @@                              ||     $400 [80% of $500]     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:@@ -2426,13 +2433,13 @@                   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:@@ -2458,9 +2465,9 @@                   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: @@ -2476,7 +2483,7 @@               -------------------------------++-------------------------------                                              ||        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@@ -2495,14 +2502,14 @@     balancesheet        balancesheet, bs-       This command displays a balance sheet, showing historical  ending  bal-+       This  command  displays a balance sheet, showing historical ending bal-        ances of asset and liability accounts.  (To see equity as well, use the-       balancesheetequity command.) Amounts are  shown  with  normal  positive+       balancesheetequity  command.)  Amounts  are  shown with normal positive        sign, as in conventional financial statements.         The asset and liability accounts shown are those accounts declared with-       the Asset or Cash or Liability type, or otherwise all accounts under  a-       top-level  asset  or  liability  account (case insensitive, plurals al-+       the  Asset or Cash or Liability type, or otherwise all accounts under a+       top-level asset or liability account  (case  insensitive,  plurals  al-        lowed).         Example:@@ -2527,25 +2534,25 @@                                  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-       This  command  displays a balance sheet, showing historical ending bal--       ances of asset, liability and equity accounts.  Amounts are shown  with+       This command displays a balance sheet, showing historical  ending  bal-+       ances  of asset, liability and equity accounts.  Amounts are shown with        normal positive sign, as in conventional financial statements. -       The  asset,  liability and equity accounts shown are those accounts de-+       The asset, liability and equity accounts shown are those  accounts  de-        clared with the Asset, Cash, Liability or Equity type, or otherwise all        accounts under a top-level asset, liability or equity account (case in-        sensitive, plurals allowed).@@ -2577,18 +2584,18 @@                                  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 cashflow statement,  showing  the  inflows  and-       outflows  affecting "cash" (ie, liquid) assets.  Amounts are shown with+       This  command  displays  a  cashflow statement, showing the inflows and+       outflows affecting "cash" (ie, liquid) assets.  Amounts are shown  with        normal positive sign, as in conventional financial statements. -       The "cash" accounts shown are those accounts  declared  with  the  Cash-       type,  or  otherwise all accounts under a top-level asset account (case-       insensitive, plural allowed) which do not have fixed,  investment,  re-+       The  "cash"  accounts  shown  are those accounts declared with the Cash+       type, or otherwise all accounts under a top-level asset  account  (case+       insensitive,  plural  allowed) which do not have fixed, investment, re-        ceivable or A/R in their name.         Example:@@ -2608,22 +2615,22 @@                                $-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        check        Check for various kinds of errors in your data.  experimental -       hledger  provides  a  number  of  built-in error checks to help prevent-       problems in your data.  Some of these are run  automatically;  or,  you-       can  use this check command to run them on demand, with no output and a+       hledger provides a number of built-in  error  checks  to  help  prevent+       problems  in  your  data.  Some of these are run automatically; or, you+       can use this check command to run them on demand, with no output and  a        zero exit code if all is well.  Some examples:                hledger check      # basic checks@@ -2637,15 +2644,15 @@         o parseable - data files are well-formed and can be successfully parsed -       o autobalanced -  all  transactions  are  balanced,  inferring  missing-         amounts  where  necessary,  and possibly converting commodities using+       o autobalanced  -  all  transactions  are  balanced,  inferring missing+         amounts where necessary, and possibly  converting  commodities  using          transaction prices or automatically-inferred transaction prices -       o assertions - all balance  assertions  in  the  journal  are  passing.+       o assertions  -  all  balance  assertions  in  the journal are passing.          (This check can be disabled with -I/--ignore-assertions.)     Strict checks-       These  are  always  run  by this and other commands when -s/--strict is+       These are always run by this and other  commands  when  -s/--strict  is        used (strict mode):         o accounts - all account names used by transactions have been declared@@ -2653,13 +2660,13 @@        o commodities - all commodity symbols used have been declared     Other checks-       These checks can be run by specifying their names as arguments  to  the+       These  checks  can be run by specifying their names as arguments to the        check command: -       o ordereddates  -  transactions are ordered by date (similar to the old+       o ordereddates - transactions are ordered by date (similar to  the  old          check-dates command) -       o uniqueleafnames - all account leaf names are unique (similar  to  the+       o uniqueleafnames  -  all account leaf names are unique (similar to the          old check-dupes command)     Add-on checks@@ -2667,10 +2674,10 @@        as add-on commands in https://github.com/simonmichael/hledger/tree/mas-        ter/bin: -       o hledger-check-tagfiles  -  all  tag  values  containing  / (a forward+       o hledger-check-tagfiles - all  tag  values  containing  /  (a  forward          slash) exist as file paths -       o hledger-check-fancyassertions - more complex balance  assertions  are+       o hledger-check-fancyassertions  -  more complex balance assertions are          passing         You could make your own similar scripts to perform custom checks; Cook-@@ -2678,64 +2685,64 @@     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:@@ -2776,13 +2783,13 @@        codes        List the codes seen in transactions, in the order parsed. -       This command prints the value of each transaction's code field, in  the-       order  transactions  were  parsed.  The transaction code is an optional-       value written in parentheses between the date  and  description,  often+       This  command prints the value of each transaction's code field, in the+       order transactions were parsed.  The transaction code  is  an  optional+       value  written  in  parentheses between the date and description, often        used to store a cheque number, order number or similar.         Transactions aren't required to have a code, and missing or empty codes-       will not be shown by default.  With the -E/--empty flag, they  will  be+       will  not  be shown by default.  With the -E/--empty flag, they will be        printed as blank lines.         You can add a query to select a subset of transactions.@@ -2822,7 +2829,7 @@        List the unique descriptions that appear in transactions.         This command lists the unique descriptions that appear in transactions,-       in alphabetic order.  You can add a query to select a subset of  trans-+       in  alphabetic order.  You can add a query to select a subset of trans-        actions.         Example:@@ -2834,18 +2841,18 @@     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. @@ -2863,20 +2870,20 @@     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:@@ -2903,9 +2910,9 @@     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@@ -2916,23 +2923,23 @@        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.)     Commodity display styles@@ -2941,13 +2948,13 @@     incomestatement        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-        tive sign, as in conventional financial statements.         The revenue and expense accounts shown are those accounts declared with-       the  Revenue  or  Expense  type, or otherwise all accounts under a top--       level revenue or income or expense account (case  insensitive,  plurals+       the Revenue or Expense type, or otherwise all  accounts  under  a  top-+       level  revenue  or income or expense account (case insensitive, plurals        allowed).         Example:@@ -2974,13 +2981,13 @@                                  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@@ -2988,8 +2995,8 @@        List the unique notes that appear in transactions.         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--       tions.   The  note is the part of the transaction description after a |+       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  |        character (or if there is no |, the whole description).         Example:@@ -3001,13 +3008,13 @@    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:@@ -3023,7 +3030,7 @@                 (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:@@ -3033,16 +3040,16 @@               $ 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. @@ -3057,7 +3064,7 @@                   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. @@ -3070,12 +3077,12 @@                                                               --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'@@ -3099,10 +3106,10 @@         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:@@ -3110,49 +3117,49 @@        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. -       This  command  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+       This command 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.         Note, in some cases this report can fail, for these reasons: -       o Error (NotBracketed): No solution for Internal Rate of Return  (IRR).-         Possible  causes:  IRR is huge (>1000000%), balance of investment be-+       o Error  (NotBracketed): No solution for Internal Rate of Return (IRR).+         Possible causes: IRR is huge (>1000000%), balance of  investment  be-          comes negative at some point in time. -       o Error (SearchFailed): Failed to find solution for  Internal  Rate  of+       o Error  (SearchFailed):  Failed  to find solution for Internal Rate of          Return (IRR).  Either search does not converge to a solution, or con-          verges too slowly. @@ -3163,67 +3170,67 @@         More background: -       "ROI"  stands  for "return on investment".  Traditionally this was com--       puted as a difference between current value of investment and its  ini-+       "ROI" stands for "return on investment".  Traditionally this  was  com-+       puted  as a difference between current value of investment and its ini-        tial value, expressed in percentage of the initial value.         However, this approach is only practical in simple cases, where invest--       ments receives no in-flows or out-flows of money,  and  where  rate  of+       ments  receives  no  in-flows  or out-flows of money, and where rate of        growth is fixed over time.  For more complex scenarios you need differ--       ent ways to compute rate of return, and this command implements two  of+       ent  ways to compute rate of return, and this command implements two of        them: IRR and TWR. -       Internal  rate of return, or "IRR" (also called "money-weighted rate of-       return")  takes  into  account  effects  of  in-flows  and   out-flows.+       Internal rate of return, or "IRR" (also called "money-weighted rate  of+       return")   takes  into  account  effects  of  in-flows  and  out-flows.        Naively, if you are withdrawing from your investment, your future gains-       would be smaller (in absolute numbers), and will be a smaller  percent--       age  of  your initial investment, and if you are adding to your invest--       ment, you will receive bigger absolute gains (but probably at the  same-       rate  of  return).  IRR is a way to compute rate of return for each pe--       riod between in-flow or out-flow of money, and then combine them  in  a+       would  be smaller (in absolute numbers), and will be a smaller percent-+       age of your initial investment, and if you are adding to  your  invest-+       ment,  you will receive bigger absolute gains (but probably at the same+       rate of return).  IRR is a way to compute rate of return for  each  pe-+       riod  between  in-flow or out-flow of money, and then combine them in a        way that gives you an annual rate of return that investment is expected        to generate. -       As mentioned before, in-flows and out-flows would be any cash that  you-       personally  put  in  or  withdraw, and for the "roi" command, these are-       transactions that involve account(s) matching --inv  argument  and  NOT+       As  mentioned before, in-flows and out-flows would be any cash that you+       personally put in or withdraw, and for the  "roi"  command,  these  are+       transactions  that  involve  account(s) matching --inv argument and NOT        involve account(s) matching --pnl argument. -       Presumably,  you  will also record changes in the value of your invest--       ment, and balance  them  against  "profit  and  loss"  (or  "unrealized+       Presumably, you will also record changes in the value of  your  invest-+       ment,  and  balance  them  against  "profit  and  loss" (or "unrealized        gains") account.  Note that in order for IRR to compute the precise ef--       fect of your in-flows and out-flows on the rate  of  return,  you  will-       need  to  record  the value of your investement on or close to the days+       fect  of  your  in-flows  and out-flows on the rate of return, you will+       need to record the value of your investement on or close  to  the  days        when in- or out-flows occur. -       Implementation of IRR in hledger should match the XIRR formula  in  Ex-+       Implementation  of  IRR in hledger should match the XIRR formula in Ex-        cel. -       Second  way  to  compute  rate of return that roi command implements is+       Second way to compute rate of return that  roi  command  implements  is        called "time-weighted rate of return" or "TWR".  Like IRR, it will also-       break  the history of your investment into periods between in-flows and+       break the history of your investment into periods between in-flows  and        out-flows to compute rate of return per each period and then a compound        rate of return.  However, internal workings of TWR are quite different. -       In  technical  terms,  IRR uses the same approach as computation of net+       In technical terms, IRR uses the same approach as  computation  of  net        present value, and tries to find a discount rate that makes net present        value of all the cash flows of your investment to add up to zero.  This-       could be hard to wrap your head around, especially if you haven't  done+       could  be hard to wrap your head around, especially if you haven't done        discounted cash flow analysis before. -       TWR  represents  your  investment as an imaginary "unit fund" where in--       flows/ out-flows lead to buying or selling "units" of  your  investment+       TWR represents your investment as an imaginary "unit  fund"  where  in-+       flows/  out-flows  lead to buying or selling "units" of your investment        and changes in its value change the value of "investment unit".  Change-       in "unit price" over the reporting period gives you rate of  return  of+       in  "unit  price" over the reporting period gives you rate of return of        your investment. -       References:  * Explanation of rate of return * Explanation of IRR * Ex--       planation of TWR * Examples of computing IRR and TWR and discussion  of+       References: * Explanation of rate of return * Explanation of IRR *  Ex-+       planation  of TWR * Examples of computing IRR and TWR and discussion of        the limitations of both metrics         More examples: -       Lets  say  that we found an investment in Snake Oil that is proising to+       Lets say that we found an investment in Snake Oil that is  proising  to        give us 10% annually:                2019-01-01 Investing in Snake Oil@@ -3234,7 +3241,7 @@                 investment:snake oil   = $110                 equity:unrealized gains -       For now, basic computation of the rate of return, as well  as  IRR  and+       For  now,  basic  computation of the rate of return, as well as IRR and        TWR, gives us the expected 10%:                $ hledger roi -Y --inv investment --pnl "unrealized"@@ -3244,10 +3251,10 @@               | 1 || 2019-01-01 | 2019-12-31 ||             0 |      100 |         110 |  10 || 10.00% | 10.00% |               +---++------------+------------++---------------+----------+-------------+-----++--------+--------+ -       However,  lets  say  that  shorty  after  investing in the Snake Oil we-       started to have second thoughs, so we  prompty  withdrew  $90,  leaving-       only  $10 in.  Before Christmas, though, we started to get the "fear of-       mission out", so we put the $90 back in.  So for most of the year,  our+       However, lets say that shorty after  investing  in  the  Snake  Oil  we+       started  to  have  second  thoughs, so we prompty withdrew $90, leaving+       only $10 in.  Before Christmas, though, we started to get the "fear  of+       mission  out", so we put the $90 back in.  So for most of the year, our        investment was just $10 dollars, and it gave us just $1 in growth:                2019-01-01 Investing in Snake Oil@@ -3278,10 +3285,10 @@        Here, IRR tells us that we made close to 10% on the $10 dollars that we        had in the account most of the time.  And TWR is ...  just 1%?  Why? -       Based on the transactions in our journal, TWR "think" that we are  buy--       ing  back  $90  worst of Snake Oil at the same price that it had at the+       Based  on the transactions in our journal, TWR "think" that we are buy-+       ing back $90 worst of Snake Oil at the same price that it  had  at  the        beginning of they year, and then after that our $100 investment gets $1-       increase  in value, or 1% of $100.  Let's take a closer look at what is+       increase in value, or 1% of $100.  Let's take a closer look at what  is        happening here by asking for quarterly reports instead of annual:                $ hledger roi -Q --inv investment --pnl "unrealized"@@ -3294,10 +3301,10 @@               | 4 || 2019-10-01 | 2019-12-31 ||            10 |       90 |         101 |   1 || 37.80% | 4.03% |               +---++------------+------------++---------------+----------+-------------+-----++--------+-------+ -       Now both IRR and TWR are thrown off by the fact that all of the  growth-       for  our investment happens in Q4 2019.  This happes because IRR compu-+       Now  both IRR and TWR are thrown off by the fact that all of the growth+       for our investment happens in Q4 2019.  This happes because IRR  compu-        tation is still yielding 9.32% and TWR is still 1%, but this time these-       are  rates for three month period instead of twelve, so in order to get+       are rates for three month period instead of twelve, so in order to  get        an annual rate they should be multiplied by four!         Let's try to keep a better record of how Snake Oil grew in value:@@ -3342,10 +3349,10 @@               | 4 || 2019-10-01 | 2019-12-31 ||         10.75 |       90 |      101.00 | 0.25 ||  8.05% |  1.00% |               +---++------------+------------++---------------+----------+-------------+------++--------+--------+ -       Something is still wrong with TWR computation for Q4, and if  you  have-       been  paying attention you know what it is already: big $90 buy-back is-       recorded prior to the only transaction  that  captures  the  change  of-       value  of  Snake  Oil  that happened in this time period.  Lets combine+       Something  is  still wrong with TWR computation for Q4, and if you have+       been paying attention you know what it is already: big $90 buy-back  is+       recorded  prior  to  the  only  transaction that captures the change of+       value of Snake Oil that happened in this  time  period.   Lets  combine        transactions from 30th and 31st of Dec into one:                2019-12-30 Fear of missing out and growth of Snake Oil@@ -3366,7 +3373,7 @@               | 4 || 2019-10-01 | 2019-12-31 ||         10.75 |       90 |      101.00 | 0.25 ||  8.05% |  9.57% |               +---++------------+------------++---------------+----------+-------------+------++--------+--------+ -       And  for  annual report, TWR now reports the exact profitability of our+       And for annual report, TWR now reports the exact profitability  of  our        investment:                $ hledger roi -Y --inv investment --pnl "unrealized"@@ -3380,8 +3387,8 @@        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:@@ -3399,35 +3406,35 @@               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  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)-       are  shown.  With QUERY arguments, only transactions matching the query+       are shown.  With QUERY arguments, only transactions matching the  query        are considered.         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. -       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.     test        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 --@@ -3436,12 +3443,12 @@                $ 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        Any programs or scripts in your PATH named named hledger-SOMETHING will-       also  appear  in  the  commands list (with a + mark).  These are called+       also appear in the commands list (with a +  mark).   These  are  called        add-on commands.         These offical add-ons are maintained and released along with hledger:@@ -3456,10 +3463,10 @@         o interest generates interest transactions according to various schemes -       o stockquotes downloads market prices for your commodities from  Alpha-+       o stockquotes  downloads market prices for your commodities from Alpha-          Vantage (experimental) -       Additional  experimental  add-ons, which may not be in a working state,+       Additional experimental add-ons, which may not be in a  working  state,        can be found in the bin/ directory in the hledger repo.     Add-on command flags@@ -3474,8 +3481,8 @@         (because the --serve flag belongs to hledger-web, not hledger). -       The  -h/--help and --version flags work without --, with their position-       deciding which  program  they  refer  to.   Eg  hledger  -h  web  shows+       The -h/--help and --version flags work without --, with their  position+       deciding  which  program  they  refer  to.   Eg  hledger  -h  web shows        hledger's help, hledger web -h shows hledger-web's help.         If you have any trouble with this, remember you can always run the add-@@ -3488,28 +3495,28 @@         o whose name starts with hledger- -       o whose name ends with a  recognised  file  extension:  .bat,.com,.exe,+       o whose  name  ends  with  a recognised file extension: .bat,.com,.exe,          .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none         o and (on unix, mac) which are executable by the current user. -       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 library-       functions that built-in commands use for command-line options,  parsing+       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  library+       functions  that built-in commands use for command-line options, parsing        and reporting.  ENVIRONMENT        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 @@ -3519,21 +3526,21 @@         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. -       NO_COLOR  If  this variable exists with any value, hledger will not use-       ANSI  color   codes   in   terminal   output.    This   overrides   the+       NO_COLOR If this variable exists with any value, hledger will  not  use+       ANSI   color   codes   in   terminal   output.    This   overrides  the        --color/--colour option.  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 add-on command options with --  when  invoked  from+       The  need  to  precede add-on command options with -- when invoked from        hledger is awkward.         When input data contains non-ascii characters, a suitable system locale@@ -3549,36 +3556,36 @@        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. -       Getting errors like "Illegal byte sequence" or "Invalid  or  incomplete-       multibyte  or wide character" or "commitAndReleaseBuffer: invalid argu-+       Getting  errors  like "Illegal byte sequence" or "Invalid or incomplete+       multibyte or wide character" or "commitAndReleaseBuffer: invalid  argu-        ment (invalid character)"        Programs compiled with GHC (hledger, haskell build tools, etc.) need to        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. -       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.         Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:@@ -3593,8 +3600,8 @@               POSIX               $ 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-       listed  by  locale  -a, you might need to install it.  Eg on Ubuntu/De-+       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-        bian:                $ apt-get install language-pack-fr@@ -3614,8 +3621,8 @@               $ echo "export LANG=en_US.utf8" >>~/.bash_profile               $ bash --login -       Exact spelling and capitalisation may be important.  Note  the  differ--       ence  on  MacOS  (UTF-8,  not  utf8).  Some platforms (eg ubuntu) allow+       Exact  spelling  and capitalisation may be important.  Note the differ-+       ence on MacOS (UTF-8, not utf8).   Some  platforms  (eg  ubuntu)  allow        variant spellings, but others (eg macos) require it to be exact:                $ locale -a | grep -iE en_us.*utf@@ -3625,7 +3632,7 @@   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)  @@ -3646,4 +3653,4 @@   -hledger-1.20.1                   December 2020                      HLEDGER(1)+hledger-1.20.3                   December 2020                      HLEDGER(1)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER_CSV" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals"+.TH "HLEDGER_CSV" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals"   

@@ -958,4 +958,4 @@   -hledger-lib-1.20.1               December 2020                  HLEDGER_CSV(5)+hledger-lib-1.20.3               December 2020                  HLEDGER_CSV(5)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals"+.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals"   

@@ -1575,4 +1575,4 @@   -hledger-lib-1.20.1               December 2020              HLEDGER_JOURNAL(5)+hledger-lib-1.20.3               December 2020              HLEDGER_JOURNAL(5)

@@ -1,5 +1,5 @@ -.TH "HLEDGER_TIMECLOCK" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals"+.TH "HLEDGER_TIMECLOCK" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals"   

@@ -77,4 +77,4 @@   -hledger-lib-1.20.1               December 2020            HLEDGER_TIMECLOCK(5)+hledger-lib-1.20.3               December 2020            HLEDGER_TIMECLOCK(5)

@@ -1,5 +1,5 @@ -.TH "HLEDGER_TIMEDOT" "5" "December 2020" "hledger-lib-1.20.1 " "hledger User Manuals"+.TH "HLEDGER_TIMEDOT" "5" "December 2020" "hledger-lib-1.20.3 " "hledger User Manuals"   

@@ -160,4 +160,4 @@   -hledger-lib-1.20.1               December 2020              HLEDGER_TIMEDOT(5)+hledger-lib-1.20.3               December 2020              HLEDGER_TIMEDOT(5)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2020" "hledger-1.20.1 " "hledger User Manuals"+.TH "HLEDGER" "1" "December 2020" "hledger-1.20.3 " "hledger User Manuals"   @@ -2798,231 +2798,95 @@ \f[C]csv\f[R], \f[C]html\f[R], and \f[C]json\f[R]. .PP The balance command can produce several styles of report:-.SS Classic balance report .PP-This is the original balance report, as found in Ledger.-It usually looks like this:+.SS Single-period flat balance report+.PP+This is the default for hledger\[aq]s balance command: a flat list of+all (or with a query, matched) accounts, showing full account names.+Accounts are sorted by declaration order if any, and then by account+name.+Accounts which have zero balance are not shown unless+\f[C]-E/--empty\f[R] is used.+The reported balances\[aq] total is shown as the last line, unless+disabled by \f[C]-N\f[R]/\f[C]--no-total\f[R]. .IP .nf \f[C]-$ hledger balance-                 $-1  assets-                  $1    bank:saving-                 $-2    cash-                  $2  expenses-                  $1    food-                  $1    supplies-                 $-2  income-                 $-1    gifts-                 $-1    salary+$ hledger bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary                   $1  liabilities:debts ---------------------                   0+                   0   \f[R] .fi .PP-By default, accounts are displayed hierarchically, with subaccounts-indented below their parent, with accounts at each level of the tree-sorted by declaration order if declared, then by account name.-.PP-\[dq]Boring\[dq] accounts, which contain a single interesting subaccount-and no balance of their own, are elided into the following line for more-compact output.-(Eg above, the \[dq]liabilities\[dq] account.) Use \f[C]--no-elide\f[R]-to prevent this.-.PP-Account balances are \[dq]inclusive\[dq] - they include the balances of-any subaccounts.-.PP-Accounts which have zero balance (and no non-zero subaccounts) are-omitted.-Use \f[C]-E/--empty\f[R] to show them.+.SS Single-period tree-mode balance report .PP-A final total is displayed by default; use \f[C]-N/--no-total\f[R] to-suppress it, eg:+With the \f[C]-t/--tree\f[R] flag, accounts are displayed+hierarchically, showing subaccounts as short names indented below their+parent.+(This is the default style in Ledger and in older hledger versions.) .IP .nf \f[C]-$ hledger balance -p 2008/6 expenses --no-total+$ hledger balance+                 $-1  assets+                  $1    bank:saving+                 $-2    cash                   $2  expenses                   $1    food                   $1    supplies-\f[R]-.fi-.SS Customising the classic balance report-.PP-You can customise the layout of classic balance reports with-\f[C]--format FMT\f[R]:-.IP-.nf-\f[C]-$ hledger balance --format \[dq]%20(account) %12(total)\[dq]-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1-----------------------------------                                0-\f[R]-.fi-.PP-The FMT format string (plus a newline) specifies the formatting applied-to each account/balance pair.-It may contain any suitable text, with data fields interpolated like so:-.PP-\f[C]%[MIN][.MAX](FIELDNAME)\f[R]-.IP \[bu] 2-MIN pads with spaces to at least this width (optional)-.IP \[bu] 2-MAX truncates at this width (optional)-.IP \[bu] 2-FIELDNAME must be enclosed in parentheses, and can be one of:-.RS 2-.IP \[bu] 2-\f[C]depth_spacer\f[R] - a number of spaces equal to the account\[aq]s-depth, or if MIN is specified, MIN * depth spaces.-.IP \[bu] 2-\f[C]account\f[R] - the account\[aq]s name-.IP \[bu] 2-\f[C]total\f[R] - the account\[aq]s balance/posted total, right-justified-.RE-.PP-Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:-.IP \[bu] 2-\f[C]%_\f[R] - render on multiple lines, bottom-aligned (the default)-.IP \[bu] 2-\f[C]%\[ha]\f[R] - render on multiple lines, top-aligned-.IP \[bu] 2-\f[C]%,\f[R] - render on one line, comma-separated-.PP-There are some quirks.-Eg in one-line mode, \f[C]%(depth_spacer)\f[R] has no effect, instead-\f[C]%(account)\f[R] has indentation built in.-Experimentation may be needed to get pleasing results.-.PP-Some example formats:-.IP \[bu] 2-\f[C]%(total)\f[R] - the account\[aq]s total-.IP \[bu] 2-\f[C]%-20.20(account)\f[R] - the account\[aq]s name, left justified,-padded to 20 characters and clipped at 20 characters-.IP \[bu] 2-\f[C]%,%-50(account)  %25(total)\f[R] - account name padded to 50-characters, total padded to 20 characters, with multiple commodities-rendered on one line-.IP \[bu] 2-\f[C]%20(total)  %2(depth_spacer)%-(account)\f[R] - the default format-for the single-column balance report-.SS Colour support-.PP-In terminal output, when colour is enabled, the balance command shows-negative amounts in red.-.SS Flat mode-.PP-To see a flat list instead of the default hierarchical display, use-\f[C]--flat\f[R].-In this mode, accounts (unless depth-clipped) show their full names and-\[dq]exclusive\[dq] balance, excluding any subaccount balances.-In this mode, you can also use \f[C]--drop N\f[R] to omit the first few-account name components.-.IP-.nf-\f[C]-$ hledger balance -p 2008/6 expenses -N --flat --drop 1-                  $1  food-                  $1  supplies-\f[R]-.fi-.SS Depth limited balance reports-.PP-With \f[C]--depth N\f[R] or \f[C]depth:N\f[R] or just \f[C]-N\f[R],-balance reports show accounts only to the specified numeric depth.-This is very useful to summarise a complex set of accounts and get an-overview.-.IP-.nf-\f[C]-$ hledger balance -N -1-                 $-1  assets-                  $2  expenses                  $-2  income-                  $1  liabilities-\f[R]-.fi-.PP-Flat-mode balance reports, which normally show exclusive balances, show-inclusive balances at the depth limit.-.SS Percentages-.PP-With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each-account\[aq]s value expressed as a percentage of the column\[aq]s total.-This is useful to get an overview of the relative sizes of account-balances.-For example to obtain an overview of expenses:-.IP-.nf-\f[C]-$ hledger balance expenses -%-             100.0 %  expenses-              50.0 %    food-              50.0 %    supplies+                 $-1    gifts+                 $-1    salary+                  $1  liabilities:debts ---------------------             100.0 %+                   0 \f[R] .fi .PP-Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].-The percentages are always relative to the total sum of each column,-they are never relative to the parent account.-.PP-Since the percentages are relative to the columns sum, it is usually not-useful to calculate percentages if the signs of the amounts are mixed.-Although the results are technically correct, they are most likely-useless.-Especially in a balance report that sums up to zero (eg-\f[C]hledger balance -B\f[R]) all percentage values will be zero.-.PP-This flag does not work if the report contains any mixed commodity-accounts.-If there are mixed commodity accounts in the report be sure to use-\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single-commodity.-.SS Sorting by amount+For more compact output, \[dq]boring\[dq] accounts containing a single+interesting subaccount and no balance of their own+(\f[C]assets:bank\f[R] and \f[C]liabilities\f[R] here) are elided into+the following line, unless \f[C]--no-elide\f[R] is used.+And accounts which have zero balance and no non-zero subaccounts are+omitted, unless \f[C]-E/--empty\f[R] is used. .PP-With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest-(most positive) balances are shown first.-For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest-averaged monthly expenses first.+Account balances in tree mode are \[dq]inclusive\[dq] - they include the+balances of any subaccounts.+Eg, the \f[C]assets\f[R] \f[C]$-1\f[R] balance here includes the+\f[C]$1\f[R] from \f[C]assets:bank:saving\f[R] and the \f[C]$-2\f[R]+from \f[C]assets:cash\f[R].+(And it would include balance posted to the \f[C]assets\f[R] account+itself, if there was any).+Note this causes some repetition, and the final total (\f[C]0\f[R]) is+the sum of the top-level balances, not of all the balances shown. .PP-Revenues and liability balances are typically negative, however, so-\f[C]-S\f[R] shows these in reverse order.-To work around this, you can add \f[C]--invert\f[R] to flip the signs.-Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or-\f[C]incomestatement\f[R], which also support \f[C]-S\f[R].-Eg: \f[C]hledger is -MAS\f[R].-.SS Multicolumn balance report+Each group of sibling accounts is sorted separately, by declaration+order and then by account name.+.SS Multi-period balance report .PP-Multicolumn or tabular balance reports are a very useful hledger-feature, and usually the preferred style.-They share many of the above features, but they show the report as a-table, with columns representing time periods.-This mode is activated by providing a reporting interval.+Multi-period balance reports are a very useful hledger feature,+activated if you provide one of the reporting interval flags, such as+\f[C]-M\f[R]/\f[C]--monthly\f[R].+They are similar to single-period balance reports, but they show the+report as a table, with columns representing one or more successive time+periods.+This is the usually the preferred style of balance report in hledger+(even for a single period). .PP-There are three types of multicolumn balance report, showing different+Multi-period balance reports come in several types, showing different information: .IP "1." 3-By default: each column shows the sum of postings in that period, ie the-account\[aq]s change of balance in that period.+A balance change report: by default, each column shows the sum of+postings in that period, ie the account\[aq]s change of balance in that+period. This is useful eg for a monthly income statement:-.RS 4 .IP .nf \f[C]@@ -3039,11 +2903,10 @@                    ||     $-1      $1       0       0  \f[R] .fi-.RE .IP "2." 3-With \f[C]--cumulative\f[R]: each column shows the ending balance for-that period, accumulating the changes across periods, starting from 0 at-the report start date:+A cumulative end balance report: with \f[C]--cumulative\f[R], each+column shows the end balance for that period, accumulating the changes+across periods, starting from 0 at the report start date: .RS 4 .IP .nf@@ -3063,11 +2926,12 @@ .fi .RE .IP "3." 3-With \f[C]--historical/-H\f[R]: each column shows the actual historical-ending balance for that period, accumulating the changes across periods,-starting from the actual balance at the report start date.-This is useful eg for a multi-period balance sheet, and when you are-showing only the data after a certain start date:+A historical end balance report: with \f[C]--historical/-H\f[R], each+column shows the actual historical end balance for that period,+accumulating the changes across periods, and including the balance from+any postings before the report start date.+This is useful eg for a multi-period balance sheet, and when you want to+see balances only after a certain date: .RS 4 .IP .nf@@ -3091,9 +2955,6 @@ \f[C]--row-total/-T\f[R], since summing end balances generally does not make sense. .PP-Multicolumn balance reports display accounts in flat mode by default; to-see the hierarchy, use \f[C]--tree\f[R].-.PP With a reporting interval (like \f[C]--quarterly\f[R] above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods.@@ -3150,14 +3011,166 @@ When the report is still too wide, a good workaround is to pipe it into \f[C]less -RS\f[R] (-R for colour, -S to chop long lines). Eg: \f[C]hledger bal -D --color=yes | less -RS\f[R].+.SS Depth limiting+.PP+With a \f[C]depth:N\f[R] query, or \f[C]--depth N\f[R] option, or just+\f[C]-N\f[R], balance reports will show accounts only to the specified+depth.+This is very useful to hide low-level accounts and get an overview.+Eg, limiting to depth 1 shows the top-level accounts:+.IP+.nf+\f[C]+$ hledger balance -N -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities+\f[R]+.fi+.PP+Accounts at the depth limit will include the balances of any hidden+subaccounts (even in flat mode, which normally shows exclusive+balances).+.PP+You can also drop account name components from the start of account+names, using \f[C]--drop N\f[R].+This can be useful to hide unwanted top-level detail.+.SS Colour support+.PP+In terminal output, when colour is enabled, the balance command shows+negative amounts in red.+.SS Sorting by amount+.PP+With \f[C]-S\f[R]/\f[C]--sort-amount\f[R], accounts with the largest+(most positive) balances are shown first.+For example, \f[C]hledger bal expenses -MAS\f[R] shows your biggest+averaged monthly expenses first.+.PP+Revenues and liability balances are typically negative, however, so+\f[C]-S\f[R] shows these in reverse order.+To work around this, you can add \f[C]--invert\f[R] to flip the signs.+Or, use one of the sign-flipping reports like \f[C]balancesheet\f[R] or+\f[C]incomestatement\f[R], which also support \f[C]-S\f[R].+Eg: \f[C]hledger is -MAS\f[R].+.SS Percentages+.PP+With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each+account\[aq]s value expressed as a percentage of the column\[aq]s total.+This is useful to get an overview of the relative sizes of account+balances.+For example to obtain an overview of expenses:+.IP+.nf+\f[C]+$ hledger balance expenses -%+             100.0 %  expenses+              50.0 %    food+              50.0 %    supplies+--------------------+             100.0 %+\f[R]+.fi+.PP+Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].+The percentages are always relative to the total sum of each column,+they are never relative to the parent account.+.PP+Since the percentages are relative to the columns sum, it is usually not+useful to calculate percentages if the signs of the amounts are mixed.+Although the results are technically correct, they are most likely+useless.+Especially in a balance report that sums up to zero (eg+\f[C]hledger balance -B\f[R]) all percentage values will be zero.+.PP+This flag does not work if the report contains any mixed commodity+accounts.+If there are mixed commodity accounts in the report be sure to use+\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single+commodity.+.PP+.SS Customising single-period balance reports+.PP+You can customise the layout of single-period balance reports with+\f[C]--format FMT\f[R], which sets the format of each line.+Eg:+.IP+.nf+\f[C]+$ hledger balance --format \[dq]%20(account) %12(total)\[dq]+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0+\f[R]+.fi+.PP+The FMT format string (plus a newline) specifies the formatting applied+to each account/balance pair.+It may contain any suitable text, with data fields interpolated like so:+.PP+\f[C]%[MIN][.MAX](FIELDNAME)\f[R]+.IP \[bu] 2+MIN pads with spaces to at least this width (optional)+.IP \[bu] 2+MAX truncates at this width (optional)+.IP \[bu] 2+FIELDNAME must be enclosed in parentheses, and can be one of:+.RS 2+.IP \[bu] 2+\f[C]depth_spacer\f[R] - a number of spaces equal to the account\[aq]s+depth, or if MIN is specified, MIN * depth spaces.+.IP \[bu] 2+\f[C]account\f[R] - the account\[aq]s name+.IP \[bu] 2+\f[C]total\f[R] - the account\[aq]s balance/posted total, right+justified+.RE+.PP+Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:+.IP \[bu] 2+\f[C]%_\f[R] - render on multiple lines, bottom-aligned (the default)+.IP \[bu] 2+\f[C]%\[ha]\f[R] - render on multiple lines, top-aligned+.IP \[bu] 2+\f[C]%,\f[R] - render on one line, comma-separated+.PP+There are some quirks.+Eg in one-line mode, \f[C]%(depth_spacer)\f[R] has no effect, instead+\f[C]%(account)\f[R] has indentation built in.+Experimentation may be needed to get pleasing results.+.PP+Some example formats:+.IP \[bu] 2+\f[C]%(total)\f[R] - the account\[aq]s total+.IP \[bu] 2+\f[C]%-20.20(account)\f[R] - the account\[aq]s name, left justified,+padded to 20 characters and clipped at 20 characters+.IP \[bu] 2+\f[C]%,%-50(account)  %25(total)\f[R] - account name padded to 50+characters, total padded to 20 characters, with multiple commodities+rendered on one line+.IP \[bu] 2+\f[C]%20(total)  %2(depth_spacer)%-(account)\f[R] - the default format+for the single-column balance report .SS Budget report .PP-With \f[C]--budget\f[R], extra columns are displayed showing budget+There is also a special balance report mode for showing budget+performance.+The \f[C]--budget\f[R] flag activates extra columns showing the budget goals for each account and period, if any.-Budget goals are defined by periodic transactions.+For this report, budget goals are defined by periodic transactions. This is very useful for comparing planned and actual income, expenses, time usage, etc.---budget is most often combined with a report interval. .PP For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:

@@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack ----- hash: dca1e9c2b2f3e690ccfc6a9b754ad06c5c7d43f1c0bd5ee04d6e1937ede8d08b+-- hash: c1a1aa83c66d0124e20f453304814e71a4a7fba409f00386ca6c831ec839b386  name:           hledger-version:        1.20.2+version:        1.20.3 synopsis:       Command-line interface for the hledger accounting system description:    The command-line interface for the hledger accounting system.                 Its basic function is to read a plain text file describing@@ -150,7 +150,7 @@   other-modules:       Paths_hledger   ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path-  cpp-options: -DVERSION="1.20.2"+  cpp-options: -DVERSION="1.20.3"   build-depends:       Decimal >=0.5.1     , Diff@@ -167,7 +167,7 @@     , filepath     , hashable >=1.2.4     , haskeline >=0.6-    , hledger-lib >=1.20.2 && <1.21+    , hledger-lib >=1.20.3 && <1.21     , lucid     , math-functions >=0.3.3.0     , megaparsec >=7.0.0 && <9.1@@ -201,7 +201,7 @@   hs-source-dirs:       app   ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path-  cpp-options: -DVERSION="1.20.2"+  cpp-options: -DVERSION="1.20.3"   build-depends:       Decimal >=0.5.1     , aeson >=1@@ -217,7 +217,7 @@     , filepath     , haskeline >=0.6     , hledger-    , hledger-lib >=1.20.2 && <1.21+    , hledger-lib >=1.20.3 && <1.21     , math-functions >=0.3.3.0     , megaparsec >=7.0.0 && <9.1     , mtl >=2.2.1@@ -251,7 +251,7 @@   hs-source-dirs:       test   ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path-  cpp-options: -DVERSION="1.20.2"+  cpp-options: -DVERSION="1.20.3"   build-depends:       Decimal >=0.5.1     , aeson >=1@@ -267,7 +267,7 @@     , filepath     , haskeline >=0.6     , hledger-    , hledger-lib >=1.20.2 && <1.21+    , hledger-lib >=1.20.3 && <1.21     , math-functions >=0.3.3.0     , megaparsec >=7.0.0 && <9.1     , mtl >=2.2.1@@ -315,7 +315,7 @@     , filepath     , haskeline >=0.6     , hledger-    , hledger-lib >=1.20.2 && <1.21+    , hledger-lib >=1.20.3 && <1.21     , html     , math-functions >=0.3.3.0     , megaparsec >=7.0.0 && <9.1

@@ -2274,25 +2274,50 @@  * Menu: -* Classic balance report::-* Customising the classic balance report::+* Single-period flat balance report::+* Single-period tree-mode balance report::+* Multi-period balance report::+* Depth limiting:: * Colour support::-* Flat mode::-* Depth limited balance reports::-* Percentages:: * Sorting by amount::-* Multicolumn balance report::+* Percentages::+* Customising single-period balance reports:: * Budget report::  -File: hledger.info,  Node: Classic balance report,  Next: Customising the classic balance report,  Up: balance+File: hledger.info,  Node: Single-period flat balance report,  Next: Single-period tree-mode balance report,  Up: balance -3.5.1 Classic balance report-----------------------------+3.5.1 Single-period flat balance report+--------------------------------------- -This is the original balance report, as found in Ledger.  It usually-looks like this:+This is the default for hledger's balance command: a flat list of all+(or with a query, matched) accounts, showing full account names.+Accounts are sorted by declaration order if any, and then by account+name.  Accounts which have zero balance are not shown unless+'-E/--empty' is used.  The reported balances' total is shown as the last+line, unless disabled by '-N'/'--no-total'. +$ hledger bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  +++File: hledger.info,  Node: Single-period tree-mode balance report,  Next: Multi-period balance report,  Prev: Single-period flat balance report,  Up: balance++3.5.2 Single-period tree-mode balance report+--------------------------------------------++With the '-t/--tree' flag, accounts are displayed hierarchically,+showing subaccounts as short names indented below their parent.  (This+is the default style in Ledger and in older hledger versions.)+ $ hledger balance                  $-1  assets                   $1    bank:saving@@ -2307,216 +2332,58 @@ --------------------                    0 -   By default, accounts are displayed hierarchically, with subaccounts-indented below their parent, with accounts at each level of the tree-sorted by declaration order if declared, then by account name.--   "Boring" accounts, which contain a single interesting subaccount and-no balance of their own, are elided into the following line for more-compact output.  (Eg above, the "liabilities" account.)  Use-'--no-elide' to prevent this.--   Account balances are "inclusive" - they include the balances of any-subaccounts.--   Accounts which have zero balance (and no non-zero subaccounts) are-omitted.  Use '-E/--empty' to show them.+   For more compact output, "boring" accounts containing a single+interesting subaccount and no balance of their own ('assets:bank' and+'liabilities' here) are elided into the following line, unless+'--no-elide' is used.  And accounts which have zero balance and no+non-zero subaccounts are omitted, unless '-E/--empty' is used. -   A final total is displayed by default; use '-N/--no-total' to-suppress it, eg:+   Account balances in tree mode are "inclusive" - they include the+balances of any subaccounts.  Eg, the 'assets' '$-1' balance here+includes the '$1' from 'assets:bank:saving' and the '$-2' from+'assets:cash'.  (And it would include balance posted to the 'assets'+account itself, if there was any).  Note this causes some repetition,+and the final total ('0') is the sum of the top-level balances, not of+all the balances shown. -$ hledger balance -p 2008/6 expenses --no-total-                  $2  expenses-                  $1    food-                  $1    supplies+   Each group of sibling accounts is sorted separately, by declaration+order and then by account name.  -File: hledger.info,  Node: Customising the classic balance report,  Next: Colour support,  Prev: Classic balance report,  Up: balance--3.5.2 Customising the classic balance report-----------------------------------------------You can customise the layout of classic balance reports with '--format-FMT':+File: hledger.info,  Node: Multi-period balance report,  Next: ,  Prev: Single-period tree-mode balance report,  Up: balance -$ hledger balance --format "%20(account) %12(total)"-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1+3.5.3 Multi-period balance report ----------------------------------                                0 -   The FMT format string (plus a newline) specifies the formatting-applied to each account/balance pair.  It may contain any suitable text,-with data fields interpolated like so:--   '%[MIN][.MAX](FIELDNAME)'--   * MIN pads with spaces to at least this width (optional)--   * MAX truncates at this width (optional)--   * FIELDNAME must be enclosed in parentheses, and can be one of:--        * 'depth_spacer' - a number of spaces equal to the account's-          depth, or if MIN is specified, MIN * depth spaces.-        * 'account' - the account's name-        * 'total' - the account's balance/posted total, right justified--   Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:--   * '%_' - render on multiple lines, bottom-aligned (the default)-   * '%^' - render on multiple lines, top-aligned-   * '%,' - render on one line, comma-separated--   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no-effect, instead '%(account)' has indentation built in.  Experimentation-may be needed to get pleasing results.--   Some example formats:--   * '%(total)' - the account's total-   * '%-20.20(account)' - the account's name, left justified, padded to-     20 characters and clipped at 20 characters-   * '%,%-50(account) %25(total)' - account name padded to 50-     characters, total padded to 20 characters, with multiple-     commodities rendered on one line-   * '%20(total) %2(depth_spacer)%-(account)' - the default format for-     the single-column balance report---File: hledger.info,  Node: Colour support,  Next: Flat mode,  Prev: Customising the classic balance report,  Up: balance--3.5.3 Colour support-----------------------In terminal output, when colour is enabled, the balance command shows-negative amounts in red.---File: hledger.info,  Node: Flat mode,  Next: Depth limited balance reports,  Prev: Colour support,  Up: balance--3.5.4 Flat mode------------------To see a flat list instead of the default hierarchical display, use-'--flat'.  In this mode, accounts (unless depth-clipped) show their full-names and "exclusive" balance, excluding any subaccount balances.  In-this mode, you can also use '--drop N' to omit the first few account-name components.--$ hledger balance -p 2008/6 expenses -N --flat --drop 1-                  $1  food-                  $1  supplies---File: hledger.info,  Node: Depth limited balance reports,  Next: Percentages,  Prev: Flat mode,  Up: balance--3.5.5 Depth limited balance reports--------------------------------------With '--depth N' or 'depth:N' or just '-N', balance reports show-accounts only to the specified numeric depth.  This is very useful to-summarise a complex set of accounts and get an overview.--$ hledger balance -N -1-                 $-1  assets-                  $2  expenses-                 $-2  income-                  $1  liabilities--   Flat-mode balance reports, which normally show exclusive balances,-show inclusive balances at the depth limit.---File: hledger.info,  Node: Percentages,  Next: Sorting by amount,  Prev: Depth limited balance reports,  Up: balance--3.5.6 Percentages--------------------With '-%' or '--percent', balance reports show each account's value-expressed as a percentage of the column's total.  This is useful to get-an overview of the relative sizes of account balances.  For example to-obtain an overview of expenses:--$ hledger balance expenses -%-             100.0 %  expenses-              50.0 %    food-              50.0 %    supplies----------------------             100.0 %--   Note that '--tree' does not have an effect on '-%'.  The percentages-are always relative to the total sum of each column, they are never-relative to the parent account.--   Since the percentages are relative to the columns sum, it is usually-not useful to calculate percentages if the signs of the amounts are-mixed.  Although the results are technically correct, they are most-likely useless.  Especially in a balance report that sums up to zero (eg-'hledger balance -B') all percentage values will be zero.--   This flag does not work if the report contains any mixed commodity-accounts.  If there are mixed commodity accounts in the report be sure-to use '-V' or '-B' to coerce the report into using a single commodity.---File: hledger.info,  Node: Sorting by amount,  Next: Multicolumn balance report,  Prev: Percentages,  Up: balance--3.5.7 Sorting by amount--------------------------With '-S'/'--sort-amount', accounts with the largest (most positive)-balances are shown first.  For example, 'hledger bal expenses -MAS'-shows your biggest averaged monthly expenses first.--   Revenues and liability balances are typically negative, however, so-'-S' shows these in reverse order.  To work around this, you can add-'--invert' to flip the signs.  Or, use one of the sign-flipping reports-like 'balancesheet' or 'incomestatement', which also support '-S'.  Eg:-'hledger is -MAS'.---File: hledger.info,  Node: Multicolumn balance report,  Next: Budget report,  Prev: Sorting by amount,  Up: balance--3.5.8 Multicolumn balance report---------------------------------+Multi-period balance reports are a very useful hledger feature,+activated if you provide one of the reporting interval flags, such as+'-M'/'--monthly'.  They are similar to single-period balance reports,+but they show the report as a table, with columns representing one or+more successive time periods.  This is the usually the preferred style+of balance report in hledger (even for a single period). -Multicolumn or tabular balance reports are a very useful hledger-feature, and usually the preferred style.  They share many of the above-features, but they show the report as a table, with columns representing-time periods.  This mode is activated by providing a reporting interval.+   Multi-period balance reports come in several types, showing different+information: -   There are three types of multicolumn balance report, showing-different information:+  1. A balance change report: by default, each column shows the sum of+     postings in that period, ie the account's change of balance in that+     period.  This is useful eg for a monthly income statement: -  1. By default: each column shows the sum of postings in that period,-     ie the account's change of balance in that period.  This is useful-     eg for a monthly income statement:+$ hledger balance --quarterly income expenses -E+Balance changes in 2008: -     $ hledger balance --quarterly income expenses -E-     Balance changes in 2008:-     -                        ||  2008q1  2008q2  2008q3  2008q4 -     ===================++=================================-      expenses:food     ||       0      $1       0       0 -      expenses:supplies ||       0      $1       0       0 -      income:gifts      ||       0     $-1       0       0 -      income:salary     ||     $-1       0       0       0 -     -------------------++----------------------------------                        ||     $-1      $1       0       0 +                   ||  2008q1  2008q2  2008q3  2008q4 +===================++=================================+ expenses:food     ||       0      $1       0       0 + expenses:supplies ||       0      $1       0       0 + income:gifts      ||       0     $-1       0       0 + income:salary     ||     $-1       0       0       0 +-------------------++---------------------------------+                   ||     $-1      $1       0       0  -  2. With '--cumulative': each column shows the ending balance for that-     period, accumulating the changes across periods, starting from 0 at-     the report start date:+  2. A cumulative end balance report: with '--cumulative', each column+     shows the end balance for that period, accumulating the changes+     across periods, starting from 0 at the report start date:       $ hledger balance --quarterly income expenses -E --cumulative      Ending balances (cumulative) in 2008:@@ -2530,11 +2397,12 @@      -------------------++-------------------------------------------------                         ||         $-1           0           0           0  -  3. With '--historical/-H': each column shows the actual historical-     ending balance for that period, accumulating the changes across-     periods, starting from the actual balance at the report start date.-     This is useful eg for a multi-period balance sheet, and when you-     are showing only the data after a certain start date:+  3. A historical end balance report: with '--historical/-H', each+     column shows the actual historical end balance for that period,+     accumulating the changes across periods, and including the balance+     from any postings before the report start date.  This is useful eg+     for a multi-period balance sheet, and when you want to see balances+     only after a certain date:       $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1      Ending balances (historical) in 2008/04/01-2008/12/31:@@ -2552,9 +2420,6 @@ '--row-total/-T', since summing end balances generally does not make sense. -   Multicolumn balance reports display accounts in flat mode by default;-to see the hierarchy, use '--tree'.-    With a reporting interval (like '--quarterly' above), the report start/end dates will be adjusted if necessary so that they encompass the displayed report periods.  This is so that the first and last periods@@ -2605,17 +2470,158 @@ into 'less -RS' (-R for colour, -S to chop long lines).  Eg: 'hledger bal -D --color=yes | less -RS'. +3.5.4 Depth limiting+--------------------++With a 'depth:N' query, or '--depth N' option, or just '-N', balance+reports will show accounts only to the specified depth.  This is very+useful to hide low-level accounts and get an overview.  Eg, limiting to+depth 1 shows the top-level accounts:++$ hledger balance -N -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities++   Accounts at the depth limit will include the balances of any hidden+subaccounts (even in flat mode, which normally shows exclusive+balances).++   You can also drop account name components from the start of account+names, using '--drop N'.  This can be useful to hide unwanted top-level+detail.+ -File: hledger.info,  Node: Budget report,  Prev: Multicolumn balance report,  Up: balance+File: hledger.info,  Node: Colour support,  Next: Sorting by amount,  Prev: ,  Up: balance +3.5.5 Colour support+--------------------++In terminal output, when colour is enabled, the balance command shows+negative amounts in red.+++File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Colour support,  Up: balance++3.5.6 Sorting by amount+-----------------------++With '-S'/'--sort-amount', accounts with the largest (most positive)+balances are shown first.  For example, 'hledger bal expenses -MAS'+shows your biggest averaged monthly expenses first.++   Revenues and liability balances are typically negative, however, so+'-S' shows these in reverse order.  To work around this, you can add+'--invert' to flip the signs.  Or, use one of the sign-flipping reports+like 'balancesheet' or 'incomestatement', which also support '-S'.  Eg:+'hledger is -MAS'.+++File: hledger.info,  Node: Percentages,  Next: Customising single-period balance reports,  Prev: Sorting by amount,  Up: balance++3.5.7 Percentages+-----------------++With '-%' or '--percent', balance reports show each account's value+expressed as a percentage of the column's total.  This is useful to get+an overview of the relative sizes of account balances.  For example to+obtain an overview of expenses:++$ hledger balance expenses -%+             100.0 %  expenses+              50.0 %    food+              50.0 %    supplies+--------------------+             100.0 %++   Note that '--tree' does not have an effect on '-%'.  The percentages+are always relative to the total sum of each column, they are never+relative to the parent account.++   Since the percentages are relative to the columns sum, it is usually+not useful to calculate percentages if the signs of the amounts are+mixed.  Although the results are technically correct, they are most+likely useless.  Especially in a balance report that sums up to zero (eg+'hledger balance -B') all percentage values will be zero.++   This flag does not work if the report contains any mixed commodity+accounts.  If there are mixed commodity accounts in the report be sure+to use '-V' or '-B' to coerce the report into using a single commodity.+++File: hledger.info,  Node: Customising single-period balance reports,  Next: Budget report,  Prev: Percentages,  Up: balance++3.5.8 Customising single-period balance reports+-----------------------------------------------++You can customise the layout of single-period balance reports with+'--format FMT', which sets the format of each line.  Eg:++$ hledger balance --format "%20(account) %12(total)"+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0++   The FMT format string (plus a newline) specifies the formatting+applied to each account/balance pair.  It may contain any suitable text,+with data fields interpolated like so:++   '%[MIN][.MAX](FIELDNAME)'++   * MIN pads with spaces to at least this width (optional)++   * MAX truncates at this width (optional)++   * FIELDNAME must be enclosed in parentheses, and can be one of:++        * 'depth_spacer' - a number of spaces equal to the account's+          depth, or if MIN is specified, MIN * depth spaces.+        * 'account' - the account's name+        * 'total' - the account's balance/posted total, right justified++   Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++   * '%_' - render on multiple lines, bottom-aligned (the default)+   * '%^' - render on multiple lines, top-aligned+   * '%,' - render on one line, comma-separated++   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no+effect, instead '%(account)' has indentation built in.  Experimentation+may be needed to get pleasing results.++   Some example formats:++   * '%(total)' - the account's total+   * '%-20.20(account)' - the account's name, left justified, padded to+     20 characters and clipped at 20 characters+   * '%,%-50(account) %25(total)' - account name padded to 50+     characters, total padded to 20 characters, with multiple+     commodities rendered on one line+   * '%20(total) %2(depth_spacer)%-(account)' - the default format for+     the single-column balance report+++File: hledger.info,  Node: Budget report,  Prev: Customising single-period balance reports,  Up: balance+ 3.5.9 Budget report ------------------- -With '--budget', extra columns are displayed showing budget goals for-each account and period, if any.  Budget goals are defined by periodic-transactions.  This is very useful for comparing planned and actual-income, expenses, time usage, etc.  -budget is most often combined with-a report interval.+There is also a special balance report mode for showing budget+performance.  The '--budget' flag activates extra columns showing the+budget goals for each account and period, if any.  For this report,+budget goals are defined by periodic transactions.  This is very useful+for comparing planned and actual income, expenses, time usage, etc.     For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:@@ -4297,99 +4303,98 @@ Ref: #aregister-and-custom-posting-dates76676 Node: balance77497 Ref: #balance77614-Node: Classic balance report79240-Ref: #classic-balance-report79413-Node: Customising the classic balance report80737-Ref: #customising-the-classic-balance-report80965-Node: Colour support83041-Ref: #colour-support83208-Node: Flat mode83304-Ref: #flat-mode83452-Node: Depth limited balance reports83865-Ref: #depth-limited-balance-reports84050-Node: Percentages84506-Ref: #percentages84663-Node: Sorting by amount85800-Ref: #sorting-by-amount85966-Node: Multicolumn balance report86460-Ref: #multicolumn-balance-report86646-Node: Budget report92243-Ref: #budget-report92377-Node: Budget report start date97666-Ref: #budget-report-start-date97831-Node: Nested budgets99163-Ref: #nested-budgets99308-Node: balancesheet102748-Ref: #balancesheet102884-Node: balancesheetequity104396-Ref: #balancesheetequity104545-Node: cashflow105621-Ref: #cashflow105743-Node: check106959-Ref: #check107062-Node: Basic checks107667-Ref: #basic-checks107783-Node: Strict checks108276-Ref: #strict-checks108415-Node: Other checks108658-Ref: #other-checks108796-Node: Add-on checks109094-Ref: #add-on-checks109212-Node: close109665-Ref: #close109767-Node: close usage111289-Ref: #close-usage111382-Node: codes114195-Ref: #codes114303-Node: commodities115015-Ref: #commodities115142-Node: descriptions115224-Ref: #descriptions115352-Node: diff115656-Ref: #diff115762-Node: files116809-Ref: #files116909-Node: help117056-Ref: #help117156-Node: import118237-Ref: #import118351-Node: Importing balance assignments119273-Ref: #importing-balance-assignments119454-Node: Commodity display styles120103-Ref: #commodity-display-styles120274-Node: incomestatement120403-Ref: #incomestatement120536-Node: notes121881-Ref: #notes121995-Node: rewrite122363-Ref: #rewrite122469-Node: Re-write rules in a file124375-Ref: #re-write-rules-in-a-file124536-Node: Diff output format125685-Ref: #diff-output-format125866-Node: rewrite vs print --auto126958-Ref: #rewrite-vs.-print---auto127116-Node: roi127672-Ref: #roi127770-Node: stats139980-Ref: #stats140079-Node: tags140867-Ref: #tags140965-Node: test141484-Ref: #test141592-Node: Add-on commands142339-Ref: #add-on-commands142485-Node: Add-on command flags143249-Ref: #add-on-command-flags143423-Node: Making add-on commands144003-Ref: #making-add-on-commands144157-Node: ENVIRONMENT144750-Ref: #environment144862-Node: FILES145847-Ref: #files-1145950-Node: LIMITATIONS146163-Ref: #limitations146282-Node: TROUBLESHOOTING147025-Ref: #troubleshooting147138+Node: Single-period flat balance report79269+Ref: #single-period-flat-balance-report79475+Node: Single-period tree-mode balance report80179+Ref: #single-period-tree-mode-balance-report80431+Node: Multi-period balance report81876+Ref: #multi-period-balance-report82073+Ref: #depth-limiting-187766+Node: Colour support88462+Ref: #colour-support88599+Node: Sorting by amount88695+Ref: #sorting-by-amount88849+Node: Percentages89343+Ref: #percentages89512+Node: Customising single-period balance reports90649+Ref: #customising-single-period-balance-reports90874+Node: Budget report92997+Ref: #budget-report93146+Node: Budget report start date98476+Ref: #budget-report-start-date98641+Node: Nested budgets99973+Ref: #nested-budgets100118+Node: balancesheet103558+Ref: #balancesheet103694+Node: balancesheetequity105206+Ref: #balancesheetequity105355+Node: cashflow106431+Ref: #cashflow106553+Node: check107769+Ref: #check107872+Node: Basic checks108477+Ref: #basic-checks108593+Node: Strict checks109086+Ref: #strict-checks109225+Node: Other checks109468+Ref: #other-checks109606+Node: Add-on checks109904+Ref: #add-on-checks110022+Node: close110475+Ref: #close110577+Node: close usage112099+Ref: #close-usage112192+Node: codes115005+Ref: #codes115113+Node: commodities115825+Ref: #commodities115952+Node: descriptions116034+Ref: #descriptions116162+Node: diff116466+Ref: #diff116572+Node: files117619+Ref: #files117719+Node: help117866+Ref: #help117966+Node: import119047+Ref: #import119161+Node: Importing balance assignments120083+Ref: #importing-balance-assignments120264+Node: Commodity display styles120913+Ref: #commodity-display-styles121084+Node: incomestatement121213+Ref: #incomestatement121346+Node: notes122691+Ref: #notes122805+Node: rewrite123173+Ref: #rewrite123279+Node: Re-write rules in a file125185+Ref: #re-write-rules-in-a-file125346+Node: Diff output format126495+Ref: #diff-output-format126676+Node: rewrite vs print --auto127768+Ref: #rewrite-vs.-print---auto127926+Node: roi128482+Ref: #roi128580+Node: stats140790+Ref: #stats140889+Node: tags141677+Ref: #tags141775+Node: test142294+Ref: #test142402+Node: Add-on commands143149+Ref: #add-on-commands143295+Node: Add-on command flags144059+Ref: #add-on-command-flags144233+Node: Making add-on commands144813+Ref: #making-add-on-commands144967+Node: ENVIRONMENT145560+Ref: #environment145672+Node: FILES146657+Ref: #files-1146760+Node: LIMITATIONS146973+Ref: #limitations147092+Node: TROUBLESHOOTING147835+Ref: #troubleshooting147948  End Tag Table

@@ -1969,10 +1969,30 @@         The balance command can produce several styles of report: -   Classic balance report-       This is the original balance report, as found in  Ledger.   It  usually-       looks like this:+   Single-period flat balance report+       This is the default for hledger's balance command: a flat list  of  all+       (or  with  a query, matched) accounts, showing full account names.  Ac-+       counts are sorted by declaration order if  any,  and  then  by  account+       name.  Accounts which have zero balance are not shown unless -E/--empty+       is used.  The reported balances' total is shown as the last  line,  un-+       less disabled by -N/--no-total. +              $ hledger bal+                                $1  assets:bank:saving+                               $-2  assets:cash+                                $1  expenses:food+                                $1  expenses:supplies+                               $-1  income:gifts+                               $-1  income:salary+                                $1  liabilities:debts+              --------------------+                                 0++   Single-period tree-mode balance report+       With the -t/--tree flag, accounts are displayed hierarchically, showing+       subaccounts as short names indented below their parent.  (This  is  the+       default style in Ledger and in older hledger versions.)+               $ hledger balance                                $-1  assets                                 $1    bank:saving@@ -1987,189 +2007,52 @@               --------------------                                  0 -       By default, accounts are displayed hierarchically, with subaccounts in--       dented below their parent, with accounts at  each  level  of  the  tree-       sorted by declaration order if declared, then by account name.--       "Boring" accounts, which contain a single interesting subaccount and no-       balance of their own, are elided into the following line for more  com--       pact  output.  (Eg above, the "liabilities" account.) Use --no-elide to-       prevent this.--       Account balances are "inclusive" - they include  the  balances  of  any-       subaccounts.--       Accounts  which  have  zero  balance  (and no non-zero subaccounts) are-       omitted.  Use -E/--empty to show them.--       A final total is displayed by default; use  -N/--no-total  to  suppress-       it, eg:--              $ hledger balance -p 2008/6 expenses --no-total-                                $2  expenses-                                $1    food-                                $1    supplies--   Customising the classic balance report-       You  can  customise the layout of classic balance reports with --format-       FMT:--              $ hledger balance --format "%20(account) %12(total)"-                            assets          $-1-                       bank:saving           $1-                              cash          $-2-                          expenses           $2-                              food           $1-                          supplies           $1-                            income          $-2-                             gifts          $-1-                            salary          $-1-                 liabilities:debts           $1-              ----------------------------------                                              0--       The FMT format string (plus a newline) specifies the formatting applied-       to  each  account/balance pair.  It may contain any suitable text, with-       data fields interpolated like so:--       %[MIN][.MAX](FIELDNAME)--       o MIN pads with spaces to at least this width (optional)--       o MAX truncates at this width (optional)--       o FIELDNAME must be enclosed in parentheses, and can be one of:--         o depth_spacer - a number of spaces equal to the account's depth,  or-           if MIN is specified, MIN * depth spaces.--         o account - the account's name--         o total - the account's balance/posted total, right justified--       Also,  FMT  can begin with an optional prefix to control how multi-com--       modity amounts are rendered:--       o %_ - render on multiple lines, bottom-aligned (the default)--       o %^ - render on multiple lines, top-aligned--       o %, - render on one line, comma-separated--       There are some quirks.  Eg in one-line mode, %(depth_spacer) has no ef--       fect, instead %(account) has indentation built in.  Experimentation may-       be needed to get pleasing results.--       Some example formats:--       o %(total) - the account's total--       o %-20.20(account) - the account's name, left justified, padded  to  20-         characters and clipped at 20 characters--       o %,%-50(account)   %25(total)  - account name padded to 50 characters,-         total padded to 20 characters, with multiple commodities rendered  on-         one line--       o %20(total)   %2(depth_spacer)%-(account) - the default format for the-         single-column balance report--   Colour support-       In terminal output, when colour is enabled, the balance  command  shows-       negative amounts in red.--   Flat mode-       To  see  a  flat  list instead of the default hierarchical display, use-       --flat.  In this mode, accounts (unless depth-clipped) show their  full-       names  and  "exclusive" balance, excluding any subaccount balances.  In-       this mode, you can also use --drop N to omit the first few account name-       components.--              $ hledger balance -p 2008/6 expenses -N --flat --drop 1-                                $1  food-                                $1  supplies--   Depth limited balance reports-       With  --depth  N  or  depth:N or just -N, balance reports show accounts-       only to the specified numeric depth.  This is very useful to  summarise-       a complex set of accounts and get an overview.--              $ hledger balance -N -1-                               $-1  assets-                                $2  expenses-                               $-2  income-                                $1  liabilities--       Flat-mode balance reports, which normally show exclusive balances, show-       inclusive balances at the depth limit.--   Percentages-       With -% or --percent, balance reports show  each  account's  value  ex--       pressed  as  a percentage of the column's total.  This is useful to get-       an overview of the relative sizes of account balances.  For example  to-       obtain an overview of expenses:--              $ hledger balance expenses -%-                           100.0 %  expenses-                            50.0 %    food-                            50.0 %    supplies-              ---------------------                           100.0 %--       Note  that  --tree  does not have an effect on -%.  The percentages are-       always relative to the total sum of each column, they are  never  rela--       tive to the parent account.--       Since  the  percentages  are relative to the columns sum, it is usually-       not useful to calculate percentages if the signs  of  the  amounts  are-       mixed.   Although  the  results  are technically correct, they are most-       likely useless.  Especially in a balance report that sums  up  to  zero-       (eg hledger balance -B) all percentage values will be zero.--       This  flag does not work if the report contains any mixed commodity ac--       counts.  If there are mixed commodity accounts in the report be sure to-       use -V or -B to coerce the report into using a single commodity.+       For  more  compact output, "boring" accounts containing a single inter-+       esting subaccount and no balance of their own (assets:bank and liabili-+       ties  here)  are  elided  into the following line, unless --no-elide is+       used.  And accounts which have zero balance and no non-zero subaccounts+       are omitted, unless -E/--empty is used. -   Sorting by amount-       With  -S/--sort-amount,  accounts with the largest (most positive) bal--       ances are shown first.  For example, hledger bal  expenses  -MAS  shows-       your biggest averaged monthly expenses first.+       Account  balances  in tree mode are "inclusive" - they include the bal-+       ances of any subaccounts.  Eg, the assets $-1 balance here includes the+       $1 from assets:bank:saving and the $-2 from assets:cash.  (And it would+       include balance posted to the assets account itself, if there was any).+       Note this causes some repetition, and the final total (0) is the sum of+       the top-level balances, not of all the balances shown. -       Revenues  and liability balances are typically negative, however, so -S-       shows these in reverse order.  To work around this, you can  add  --in--       vert  to flip the signs.  Or, use one of the sign-flipping reports like-       balancesheet or incomestatement, which also support -S.  Eg: hledger is-       -MAS.+       Each group of sibling accounts is sorted separately, by declaration or-+       der and then by account name. -   Multicolumn balance report-       Multicolumn  or  tabular balance reports are a very useful hledger fea--       ture, and usually the preferred style.  They share many  of  the  above-       features,  but they show the report as a table, with columns represent--       ing time periods.  This mode is activated by providing a reporting  in--       terval.+   Multi-period balance report+       Multi-period  balance  reports are a very useful hledger feature, acti-+       vated if you provide one of  the  reporting  interval  flags,  such  as+       -M/--monthly.   They  are similar to single-period balance reports, but+       they show the report as a table, with columns representing one or  more+       successive  time  periods.   This is the usually the preferred style of+       balance report in hledger (even for a single period). -       There  are three types of multicolumn balance report, showing different+       Multi-period balance reports come in several types,  showing  different        information: -       1. By default: each column shows the sum of postings in that period, ie-          the  account's  change of balance in that period.  This is useful eg-          for a monthly income statement:+       1. A  balance  change  report: by default, each column shows the sum of+          postings in that period, ie the account's change of balance in  that+          period.  This is useful eg for a monthly income statement: -                  $ hledger balance --quarterly income expenses -E-                  Balance changes in 2008:+          $ hledger balance --quarterly income expenses -E+          Balance changes in 2008: -                                     ||  2008q1  2008q2  2008q3  2008q4-                  ===================++=================================-                   expenses:food     ||       0      $1       0       0-                   expenses:supplies ||       0      $1       0       0-                   income:gifts      ||       0     $-1       0       0-                   income:salary     ||     $-1       0       0       0-                  -------------------++----------------------------------                                     ||     $-1      $1       0       0+                             ||  2008q1  2008q2  2008q3  2008q4+          ===================++=================================+           expenses:food     ||       0      $1       0       0+           expenses:supplies ||       0      $1       0       0+           income:gifts      ||       0     $-1       0       0+           income:salary     ||     $-1       0       0       0+          -------------------++---------------------------------+                             ||     $-1      $1       0       0 -       2. With --cumulative: each column shows the ending balance for that pe--          riod,  accumulating  the  changes across periods, starting from 0 at-          the report start date:+       2. A  cumulative  end  balance  report:  with --cumulative, each column+          shows the end balance for  that  period,  accumulating  the  changes+          across periods, starting from 0 at the report start date:                    $ hledger balance --quarterly income expenses -E --cumulative                   Ending balances (cumulative) in 2008:@@ -2183,11 +2066,12 @@                   -------------------++-------------------------------------------------                                      ||         $-1           0           0           0 -       3. With --historical/-H: each column shows the actual historical ending-          balance  for  that  period, accumulating the changes across periods,-          starting from the actual balance at the report start date.  This  is-          useful eg for a multi-period balance sheet, and when you are showing-          only the data after a certain start date:+       3. A  historical  end balance report: with --historical/-H, each column+          shows the actual historical end balance for that period,  accumulat-+          ing  the  changes across periods, and including the balance from any+          postings before the report start date.  This  is  useful  eg  for  a+          multi-period  balance  sheet, and when you want to see balances only+          after a certain date:                    $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1                   Ending balances (historical) in 2008/04/01-2008/12/31:@@ -2204,26 +2088,23 @@        Note that --cumulative or --historical/-H disable --row-total/-T, since        summing end balances generally does not make sense. -       Multicolumn  balance  reports display accounts in flat mode by default;-       to see the hierarchy, use --tree.--       With  a  reporting  interval  (like  --quarterly  above),  the   report-       start/end  dates  will  be adjusted if necessary so that they encompass+       With   a  reporting  interval  (like  --quarterly  above),  the  report+       start/end dates will be adjusted if necessary so  that  they  encompass        the displayed report periods.  This is so that the first and last peri-        ods will be "full" and comparable to the others. -       The  -E/--empty  flag  does  two things in multicolumn balance reports:+       The -E/--empty flag does two things  in  multicolumn  balance  reports:        first, the report will show all columns within the specified report pe--       riod  (without -E, leading and trailing columns with all zeroes are not-       shown).  Second, all accounts which existed at the  report  start  date-       will  be  considered, not just the ones with activity during the report-       period (use -E to include low-activity accounts which  would  otherwise+       riod (without -E, leading and trailing columns with all zeroes are  not+       shown).   Second,  all  accounts which existed at the report start date+       will be considered, not just the ones with activity during  the  report+       period  (use  -E to include low-activity accounts which would otherwise        would be omitted).         The -T/--row-total flag adds an additional column showing the total for        each row. -       The -A/--average flag adds a column showing the average value  in  each+       The  -A/--average  flag adds a column showing the average value in each        row.         Here's an example of all three:@@ -2244,27 +2125,153 @@                (Average is rounded to the dollar here since all journal amounts are) -       The  --transpose flag can be used to exchange the rows and columns of a+       The --transpose flag can be used to exchange the rows and columns of  a        multicolumn report. -       When showing multicommodity amounts, multicolumn balance  reports  will+       When  showing  multicommodity amounts, multicolumn balance reports will        elide any amounts which have more than two commodities, since otherwise-       columns could get very wide.  The --no-elide flag disables this.   Hid--       ing  totals  with the -N/--no-total flag can also help reduce the width+       columns  could get very wide.  The --no-elide flag disables this.  Hid-+       ing totals with the -N/--no-total flag can also help reduce  the  width        of multicommodity reports.         When the report is still too wide, a good workaround is to pipe it into-       less  -RS  (-R  for colour, -S to chop long lines).  Eg: hledger bal -D+       less -RS (-R for colour, -S to chop long lines).  Eg:  hledger  bal  -D        --color=yes | less -RS. +   Depth limiting+       With  a depth:N query, or --depth N option, or just -N, balance reports+       will show accounts only to the specified depth.  This is very useful to+       hide  low-level  accounts and get an overview.  Eg, limiting to depth 1+       shows the top-level accounts:++              $ hledger balance -N -1+                               $-1  assets+                                $2  expenses+                               $-2  income+                                $1  liabilities++       Accounts at the depth limit will include the  balances  of  any  hidden+       subaccounts  (even  in  flat  mode, which normally shows exclusive bal-+       ances).++       You can also drop account name components from  the  start  of  account+       names,  using  --drop N.  This can be useful to hide unwanted top-level+       detail.++   Colour support+       In terminal output, when colour is enabled, the balance  command  shows+       negative amounts in red.++   Sorting by amount+       With  -S/--sort-amount,  accounts with the largest (most positive) bal-+       ances are shown first.  For example, hledger bal  expenses  -MAS  shows+       your biggest averaged monthly expenses first.++       Revenues  and liability balances are typically negative, however, so -S+       shows these in reverse order.  To work around this, you can  add  --in-+       vert  to flip the signs.  Or, use one of the sign-flipping reports like+       balancesheet or incomestatement, which also support -S.  Eg: hledger is+       -MAS.++   Percentages+       With  -%  or  --percent,  balance reports show each account's value ex-+       pressed as a percentage of the column's total.  This is useful  to  get+       an  overview of the relative sizes of account balances.  For example to+       obtain an overview of expenses:++              $ hledger balance expenses -%+                           100.0 %  expenses+                            50.0 %    food+                            50.0 %    supplies+              --------------------+                           100.0 %++       Note that --tree does not have an effect on -%.   The  percentages  are+       always  relative  to the total sum of each column, they are never rela-+       tive to the parent account.++       Since the percentages are relative to the columns sum,  it  is  usually+       not  useful  to  calculate  percentages if the signs of the amounts are+       mixed.  Although the results are technically  correct,  they  are  most+       likely  useless.   Especially  in a balance report that sums up to zero+       (eg hledger balance -B) all percentage values will be zero.++       This flag does not work if the report contains any mixed commodity  ac-+       counts.  If there are mixed commodity accounts in the report be sure to+       use -V or -B to coerce the report into using a single commodity.++   Customising single-period balance reports+       You can customise the layout  of  single-period  balance  reports  with+       --format FMT, which sets the format of each line.  Eg:++              $ hledger balance --format "%20(account) %12(total)"+                            assets          $-1+                       bank:saving           $1+                              cash          $-2+                          expenses           $2+                              food           $1+                          supplies           $1+                            income          $-2+                             gifts          $-1+                            salary          $-1+                 liabilities:debts           $1+              ---------------------------------+                                              0++       The FMT format string (plus a newline) specifies the formatting applied+       to each account/balance pair.  It may contain any suitable  text,  with+       data fields interpolated like so:++       %[MIN][.MAX](FIELDNAME)++       o MIN pads with spaces to at least this width (optional)++       o MAX truncates at this width (optional)++       o FIELDNAME must be enclosed in parentheses, and can be one of:++         o depth_spacer  - a number of spaces equal to the account's depth, or+           if MIN is specified, MIN * depth spaces.++         o account - the account's name++         o total - the account's balance/posted total, right justified++       Also, FMT can begin with an optional prefix to control  how  multi-com-+       modity amounts are rendered:++       o %_ - render on multiple lines, bottom-aligned (the default)++       o %^ - render on multiple lines, top-aligned++       o %, - render on one line, comma-separated++       There are some quirks.  Eg in one-line mode, %(depth_spacer) has no ef-+       fect, instead %(account) has indentation built in.  Experimentation may+       be needed to get pleasing results.++       Some example formats:++       o %(total) - the account's total++       o %-20.20(account)  -  the account's name, left justified, padded to 20+         characters and clipped at 20 characters++       o %,%-50(account)  %25(total) - account name padded to  50  characters,+         total  padded to 20 characters, with multiple commodities rendered on+         one line++       o %20(total)  %2(depth_spacer)%-(account) - the default format for  the+         single-column balance report+    Budget report-       With --budget, extra columns are displayed  showing  budget  goals  for-       each  account and period, if any.  Budget goals are defined by periodic-       transactions.  This is very useful for comparing planned and actual in--       come,  expenses, time usage, etc.  --budget is most often combined with-       a report interval.+       There  is also a special balance report mode for showing budget perfor-+       mance.  The --budget flag activates extra columns  showing  the  budget+       goals  for  each  account  and period, if any.  For this report, budget+       goals are defined by periodic transactions.  This is  very  useful  for+       comparing planned and actual income, expenses, time usage, etc. -       For example, you can take average monthly expenses in  the  common  ex-+       For  example,  you  can take average monthly expenses in the common ex-        pense categories to construct a minimal monthly budget:                ;; Budget@@ -2311,26 +2318,26 @@         This is different from a normal balance report in several ways: -       o Only  accounts  with budget goals during the report period are shown,+       o Only accounts with budget goals during the report period  are  shown,          by default. -       o In each column, in square brackets after the  actual  amount,  budget-         goal  amounts are shown, and the actual/goal percentage.  (Note: bud-+       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@@ -2372,12 +2379,12 @@        For more examples and notes, see Budgeting.     Budget report start date-       This  might  be  a bug, but for now: when making budget reports, it's a+       This might be a bug, but for now: when making budget  reports,  it's  a        good idea to explicitly set the report's start date to the first day of-       a  reporting  period,  because a periodic rule like ~ monthly generates-       its transactions on the 1st of each month, and if your journal  has  no-       regular  transactions  on  the 1st, the default report start date could-       exclude that budget goal, which can be a little  surprising.   Eg  here+       a reporting period, because a periodic rule like  ~  monthly  generates+       its  transactions  on the 1st of each month, and if your journal has no+       regular transactions on the 1st, the default report  start  date  could+       exclude  that  budget  goal, which can be a little surprising.  Eg here        the default report period is just the day of 2020-01-15:                ~ monthly in 2020@@ -2396,9 +2403,9 @@               --------------++------------                             ||       $400 -       To  avoid  this,  specify  the  budget report's period, or at least the-       start date, with -b/-e/-p/date:, to ensure it includes the budget  goal-       transactions  (periodic  transactions)  that  you  want.  Eg, adding -b+       To avoid this, specify the budget report's  period,  or  at  least  the+       start  date, with -b/-e/-p/date:, to ensure it includes the budget goal+       transactions (periodic transactions) that  you  want.   Eg,  adding  -b        2020/1/1 to the above:                $ hledger bal expenses --budget -b 2020/1/1@@ -2411,12 +2418,12 @@                              ||     $400 [80% of $500]     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:@@ -2426,13 +2433,13 @@                   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:@@ -2458,9 +2465,9 @@                   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: @@ -2476,7 +2483,7 @@               -------------------------------++-------------------------------                                              ||        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@@ -2495,14 +2502,14 @@     balancesheet        balancesheet, bs-       This command displays a balance sheet, showing historical  ending  bal-+       This  command  displays a balance sheet, showing historical ending bal-        ances of asset and liability accounts.  (To see equity as well, use the-       balancesheetequity command.) Amounts are  shown  with  normal  positive+       balancesheetequity  command.)  Amounts  are  shown with normal positive        sign, as in conventional financial statements.         The asset and liability accounts shown are those accounts declared with-       the Asset or Cash or Liability type, or otherwise all accounts under  a-       top-level  asset  or  liability  account (case insensitive, plurals al-+       the  Asset or Cash or Liability type, or otherwise all accounts under a+       top-level asset or liability account  (case  insensitive,  plurals  al-        lowed).         Example:@@ -2527,25 +2534,25 @@                                  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-       This  command  displays a balance sheet, showing historical ending bal--       ances of asset, liability and equity accounts.  Amounts are shown  with+       This command displays a balance sheet, showing historical  ending  bal-+       ances  of asset, liability and equity accounts.  Amounts are shown with        normal positive sign, as in conventional financial statements. -       The  asset,  liability and equity accounts shown are those accounts de-+       The asset, liability and equity accounts shown are those  accounts  de-        clared with the Asset, Cash, Liability or Equity type, or otherwise all        accounts under a top-level asset, liability or equity account (case in-        sensitive, plurals allowed).@@ -2577,18 +2584,18 @@                                  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 cashflow statement,  showing  the  inflows  and-       outflows  affecting "cash" (ie, liquid) assets.  Amounts are shown with+       This  command  displays  a  cashflow statement, showing the inflows and+       outflows affecting "cash" (ie, liquid) assets.  Amounts are shown  with        normal positive sign, as in conventional financial statements. -       The "cash" accounts shown are those accounts  declared  with  the  Cash-       type,  or  otherwise all accounts under a top-level asset account (case-       insensitive, plural allowed) which do not have fixed,  investment,  re-+       The  "cash"  accounts  shown  are those accounts declared with the Cash+       type, or otherwise all accounts under a top-level asset  account  (case+       insensitive,  plural  allowed) which do not have fixed, investment, re-        ceivable or A/R in their name.         Example:@@ -2608,22 +2615,22 @@                                $-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        check        Check for various kinds of errors in your data.  experimental -       hledger  provides  a  number  of  built-in error checks to help prevent-       problems in your data.  Some of these are run  automatically;  or,  you-       can  use this check command to run them on demand, with no output and a+       hledger provides a number of built-in  error  checks  to  help  prevent+       problems  in  your  data.  Some of these are run automatically; or, you+       can use this check command to run them on demand, with no output and  a        zero exit code if all is well.  Some examples:                hledger check      # basic checks@@ -2637,15 +2644,15 @@         o parseable - data files are well-formed and can be successfully parsed -       o autobalanced -  all  transactions  are  balanced,  inferring  missing-         amounts  where  necessary,  and possibly converting commodities using+       o autobalanced  -  all  transactions  are  balanced,  inferring missing+         amounts where necessary, and possibly  converting  commodities  using          transaction prices or automatically-inferred transaction prices -       o assertions - all balance  assertions  in  the  journal  are  passing.+       o assertions  -  all  balance  assertions  in  the journal are passing.          (This check can be disabled with -I/--ignore-assertions.)     Strict checks-       These  are  always  run  by this and other commands when -s/--strict is+       These are always run by this and other  commands  when  -s/--strict  is        used (strict mode):         o accounts - all account names used by transactions have been declared@@ -2653,13 +2660,13 @@        o commodities - all commodity symbols used have been declared     Other checks-       These checks can be run by specifying their names as arguments  to  the+       These  checks  can be run by specifying their names as arguments to the        check command: -       o ordereddates  -  transactions are ordered by date (similar to the old+       o ordereddates - transactions are ordered by date (similar to  the  old          check-dates command) -       o uniqueleafnames - all account leaf names are unique (similar  to  the+       o uniqueleafnames  -  all account leaf names are unique (similar to the          old check-dupes command)     Add-on checks@@ -2667,10 +2674,10 @@        as add-on commands in https://github.com/simonmichael/hledger/tree/mas-        ter/bin: -       o hledger-check-tagfiles  -  all  tag  values  containing  / (a forward+       o hledger-check-tagfiles - all  tag  values  containing  /  (a  forward          slash) exist as file paths -       o hledger-check-fancyassertions - more complex balance  assertions  are+       o hledger-check-fancyassertions  -  more complex balance assertions are          passing         You could make your own similar scripts to perform custom checks; Cook-@@ -2678,64 +2685,64 @@     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:@@ -2776,13 +2783,13 @@        codes        List the codes seen in transactions, in the order parsed. -       This command prints the value of each transaction's code field, in  the-       order  transactions  were  parsed.  The transaction code is an optional-       value written in parentheses between the date  and  description,  often+       This  command prints the value of each transaction's code field, in the+       order transactions were parsed.  The transaction code  is  an  optional+       value  written  in  parentheses between the date and description, often        used to store a cheque number, order number or similar.         Transactions aren't required to have a code, and missing or empty codes-       will not be shown by default.  With the -E/--empty flag, they  will  be+       will  not  be shown by default.  With the -E/--empty flag, they will be        printed as blank lines.         You can add a query to select a subset of transactions.@@ -2822,7 +2829,7 @@        List the unique descriptions that appear in transactions.         This command lists the unique descriptions that appear in transactions,-       in alphabetic order.  You can add a query to select a subset of  trans-+       in  alphabetic order.  You can add a query to select a subset of trans-        actions.         Example:@@ -2834,18 +2841,18 @@     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. @@ -2863,20 +2870,20 @@     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:@@ -2903,9 +2910,9 @@     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@@ -2916,23 +2923,23 @@        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.)     Commodity display styles@@ -2941,13 +2948,13 @@     incomestatement        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-        tive sign, as in conventional financial statements.         The revenue and expense accounts shown are those accounts declared with-       the  Revenue  or  Expense  type, or otherwise all accounts under a top--       level revenue or income or expense account (case  insensitive,  plurals+       the Revenue or Expense type, or otherwise all  accounts  under  a  top-+       level  revenue  or income or expense account (case insensitive, plurals        allowed).         Example:@@ -2974,13 +2981,13 @@                                  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@@ -2988,8 +2995,8 @@        List the unique notes that appear in transactions.         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--       tions.   The  note is the part of the transaction description after a |+       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  |        character (or if there is no |, the whole description).         Example:@@ -3001,13 +3008,13 @@    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:@@ -3023,7 +3030,7 @@                 (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:@@ -3033,16 +3040,16 @@               $ 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. @@ -3057,7 +3064,7 @@                   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. @@ -3070,12 +3077,12 @@                                                               --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'@@ -3099,10 +3106,10 @@         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:@@ -3110,49 +3117,49 @@        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. -       This  command  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+       This command 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.         Note, in some cases this report can fail, for these reasons: -       o Error (NotBracketed): No solution for Internal Rate of Return  (IRR).-         Possible  causes:  IRR is huge (>1000000%), balance of investment be-+       o Error  (NotBracketed): No solution for Internal Rate of Return (IRR).+         Possible causes: IRR is huge (>1000000%), balance of  investment  be-          comes negative at some point in time. -       o Error (SearchFailed): Failed to find solution for  Internal  Rate  of+       o Error  (SearchFailed):  Failed  to find solution for Internal Rate of          Return (IRR).  Either search does not converge to a solution, or con-          verges too slowly. @@ -3163,67 +3170,67 @@         More background: -       "ROI"  stands  for "return on investment".  Traditionally this was com--       puted as a difference between current value of investment and its  ini-+       "ROI" stands for "return on investment".  Traditionally this  was  com-+       puted  as a difference between current value of investment and its ini-        tial value, expressed in percentage of the initial value.         However, this approach is only practical in simple cases, where invest--       ments receives no in-flows or out-flows of money,  and  where  rate  of+       ments  receives  no  in-flows  or out-flows of money, and where rate of        growth is fixed over time.  For more complex scenarios you need differ--       ent ways to compute rate of return, and this command implements two  of+       ent  ways to compute rate of return, and this command implements two of        them: IRR and TWR. -       Internal  rate of return, or "IRR" (also called "money-weighted rate of-       return")  takes  into  account  effects  of  in-flows  and   out-flows.+       Internal rate of return, or "IRR" (also called "money-weighted rate  of+       return")   takes  into  account  effects  of  in-flows  and  out-flows.        Naively, if you are withdrawing from your investment, your future gains-       would be smaller (in absolute numbers), and will be a smaller  percent--       age  of  your initial investment, and if you are adding to your invest--       ment, you will receive bigger absolute gains (but probably at the  same-       rate  of  return).  IRR is a way to compute rate of return for each pe--       riod between in-flow or out-flow of money, and then combine them  in  a+       would  be smaller (in absolute numbers), and will be a smaller percent-+       age of your initial investment, and if you are adding to  your  invest-+       ment,  you will receive bigger absolute gains (but probably at the same+       rate of return).  IRR is a way to compute rate of return for  each  pe-+       riod  between  in-flow or out-flow of money, and then combine them in a        way that gives you an annual rate of return that investment is expected        to generate. -       As mentioned before, in-flows and out-flows would be any cash that  you-       personally  put  in  or  withdraw, and for the "roi" command, these are-       transactions that involve account(s) matching --inv  argument  and  NOT+       As  mentioned before, in-flows and out-flows would be any cash that you+       personally put in or withdraw, and for the  "roi"  command,  these  are+       transactions  that  involve  account(s) matching --inv argument and NOT        involve account(s) matching --pnl argument. -       Presumably,  you  will also record changes in the value of your invest--       ment, and balance  them  against  "profit  and  loss"  (or  "unrealized+       Presumably, you will also record changes in the value of  your  invest-+       ment,  and  balance  them  against  "profit  and  loss" (or "unrealized        gains") account.  Note that in order for IRR to compute the precise ef--       fect of your in-flows and out-flows on the rate  of  return,  you  will-       need  to  record  the value of your investement on or close to the days+       fect  of  your  in-flows  and out-flows on the rate of return, you will+       need to record the value of your investement on or close  to  the  days        when in- or out-flows occur. -       Implementation of IRR in hledger should match the XIRR formula  in  Ex-+       Implementation  of  IRR in hledger should match the XIRR formula in Ex-        cel. -       Second  way  to  compute  rate of return that roi command implements is+       Second way to compute rate of return that  roi  command  implements  is        called "time-weighted rate of return" or "TWR".  Like IRR, it will also-       break  the history of your investment into periods between in-flows and+       break the history of your investment into periods between in-flows  and        out-flows to compute rate of return per each period and then a compound        rate of return.  However, internal workings of TWR are quite different. -       In  technical  terms,  IRR uses the same approach as computation of net+       In technical terms, IRR uses the same approach as  computation  of  net        present value, and tries to find a discount rate that makes net present        value of all the cash flows of your investment to add up to zero.  This-       could be hard to wrap your head around, especially if you haven't  done+       could  be hard to wrap your head around, especially if you haven't done        discounted cash flow analysis before. -       TWR  represents  your  investment as an imaginary "unit fund" where in--       flows/ out-flows lead to buying or selling "units" of  your  investment+       TWR represents your investment as an imaginary "unit  fund"  where  in-+       flows/  out-flows  lead to buying or selling "units" of your investment        and changes in its value change the value of "investment unit".  Change-       in "unit price" over the reporting period gives you rate of  return  of+       in  "unit  price" over the reporting period gives you rate of return of        your investment. -       References:  * Explanation of rate of return * Explanation of IRR * Ex--       planation of TWR * Examples of computing IRR and TWR and discussion  of+       References: * Explanation of rate of return * Explanation of IRR *  Ex-+       planation  of TWR * Examples of computing IRR and TWR and discussion of        the limitations of both metrics         More examples: -       Lets  say  that we found an investment in Snake Oil that is proising to+       Lets say that we found an investment in Snake Oil that is  proising  to        give us 10% annually:                2019-01-01 Investing in Snake Oil@@ -3234,7 +3241,7 @@                 investment:snake oil   = $110                 equity:unrealized gains -       For now, basic computation of the rate of return, as well  as  IRR  and+       For  now,  basic  computation of the rate of return, as well as IRR and        TWR, gives us the expected 10%:                $ hledger roi -Y --inv investment --pnl "unrealized"@@ -3244,10 +3251,10 @@               | 1 || 2019-01-01 | 2019-12-31 ||             0 |      100 |         110 |  10 || 10.00% | 10.00% |               +---++------------+------------++---------------+----------+-------------+-----++--------+--------+ -       However,  lets  say  that  shorty  after  investing in the Snake Oil we-       started to have second thoughs, so we  prompty  withdrew  $90,  leaving-       only  $10 in.  Before Christmas, though, we started to get the "fear of-       mission out", so we put the $90 back in.  So for most of the year,  our+       However, lets say that shorty after  investing  in  the  Snake  Oil  we+       started  to  have  second  thoughs, so we prompty withdrew $90, leaving+       only $10 in.  Before Christmas, though, we started to get the "fear  of+       mission  out", so we put the $90 back in.  So for most of the year, our        investment was just $10 dollars, and it gave us just $1 in growth:                2019-01-01 Investing in Snake Oil@@ -3278,10 +3285,10 @@        Here, IRR tells us that we made close to 10% on the $10 dollars that we        had in the account most of the time.  And TWR is ...  just 1%?  Why? -       Based on the transactions in our journal, TWR "think" that we are  buy--       ing  back  $90  worst of Snake Oil at the same price that it had at the+       Based  on the transactions in our journal, TWR "think" that we are buy-+       ing back $90 worst of Snake Oil at the same price that it  had  at  the        beginning of they year, and then after that our $100 investment gets $1-       increase  in value, or 1% of $100.  Let's take a closer look at what is+       increase in value, or 1% of $100.  Let's take a closer look at what  is        happening here by asking for quarterly reports instead of annual:                $ hledger roi -Q --inv investment --pnl "unrealized"@@ -3294,10 +3301,10 @@               | 4 || 2019-10-01 | 2019-12-31 ||            10 |       90 |         101 |   1 || 37.80% | 4.03% |               +---++------------+------------++---------------+----------+-------------+-----++--------+-------+ -       Now both IRR and TWR are thrown off by the fact that all of the  growth-       for  our investment happens in Q4 2019.  This happes because IRR compu-+       Now  both IRR and TWR are thrown off by the fact that all of the growth+       for our investment happens in Q4 2019.  This happes because IRR  compu-        tation is still yielding 9.32% and TWR is still 1%, but this time these-       are  rates for three month period instead of twelve, so in order to get+       are rates for three month period instead of twelve, so in order to  get        an annual rate they should be multiplied by four!         Let's try to keep a better record of how Snake Oil grew in value:@@ -3342,10 +3349,10 @@               | 4 || 2019-10-01 | 2019-12-31 ||         10.75 |       90 |      101.00 | 0.25 ||  8.05% |  1.00% |               +---++------------+------------++---------------+----------+-------------+------++--------+--------+ -       Something is still wrong with TWR computation for Q4, and if  you  have-       been  paying attention you know what it is already: big $90 buy-back is-       recorded prior to the only transaction  that  captures  the  change  of-       value  of  Snake  Oil  that happened in this time period.  Lets combine+       Something  is  still wrong with TWR computation for Q4, and if you have+       been paying attention you know what it is already: big $90 buy-back  is+       recorded  prior  to  the  only  transaction that captures the change of+       value of Snake Oil that happened in this  time  period.   Lets  combine        transactions from 30th and 31st of Dec into one:                2019-12-30 Fear of missing out and growth of Snake Oil@@ -3366,7 +3373,7 @@               | 4 || 2019-10-01 | 2019-12-31 ||         10.75 |       90 |      101.00 | 0.25 ||  8.05% |  9.57% |               +---++------------+------------++---------------+----------+-------------+------++--------+--------+ -       And  for  annual report, TWR now reports the exact profitability of our+       And for annual report, TWR now reports the exact profitability  of  our        investment:                $ hledger roi -Y --inv investment --pnl "unrealized"@@ -3380,8 +3387,8 @@        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:@@ -3399,35 +3406,35 @@               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  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)-       are  shown.  With QUERY arguments, only transactions matching the query+       are shown.  With QUERY arguments, only transactions matching the  query        are considered.         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. -       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.     test        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 --@@ -3436,12 +3443,12 @@                $ 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        Any programs or scripts in your PATH named named hledger-SOMETHING will-       also  appear  in  the  commands list (with a + mark).  These are called+       also appear in the commands list (with a +  mark).   These  are  called        add-on commands.         These offical add-ons are maintained and released along with hledger:@@ -3456,10 +3463,10 @@         o interest generates interest transactions according to various schemes -       o stockquotes downloads market prices for your commodities from  Alpha-+       o stockquotes  downloads market prices for your commodities from Alpha-          Vantage (experimental) -       Additional  experimental  add-ons, which may not be in a working state,+       Additional experimental add-ons, which may not be in a  working  state,        can be found in the bin/ directory in the hledger repo.     Add-on command flags@@ -3474,8 +3481,8 @@         (because the --serve flag belongs to hledger-web, not hledger). -       The  -h/--help and --version flags work without --, with their position-       deciding which  program  they  refer  to.   Eg  hledger  -h  web  shows+       The -h/--help and --version flags work without --, with their  position+       deciding  which  program  they  refer  to.   Eg  hledger  -h  web shows        hledger's help, hledger web -h shows hledger-web's help.         If you have any trouble with this, remember you can always run the add-@@ -3488,28 +3495,28 @@         o whose name starts with hledger- -       o whose name ends with a  recognised  file  extension:  .bat,.com,.exe,+       o whose  name  ends  with  a recognised file extension: .bat,.com,.exe,          .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none         o and (on unix, mac) which are executable by the current user. -       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 library-       functions that built-in commands use for command-line options,  parsing+       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  library+       functions  that built-in commands use for command-line options, parsing        and reporting.  ENVIRONMENT        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 @@ -3519,21 +3526,21 @@         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. -       NO_COLOR  If  this variable exists with any value, hledger will not use-       ANSI  color   codes   in   terminal   output.    This   overrides   the+       NO_COLOR If this variable exists with any value, hledger will  not  use+       ANSI   color   codes   in   terminal   output.    This   overrides  the        --color/--colour option.  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 add-on command options with --  when  invoked  from+       The  need  to  precede add-on command options with -- when invoked from        hledger is awkward.         When input data contains non-ascii characters, a suitable system locale@@ -3549,36 +3556,36 @@        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. -       Getting errors like "Illegal byte sequence" or "Invalid  or  incomplete-       multibyte  or wide character" or "commitAndReleaseBuffer: invalid argu-+       Getting  errors  like "Illegal byte sequence" or "Invalid or incomplete+       multibyte or wide character" or "commitAndReleaseBuffer: invalid  argu-        ment (invalid character)"        Programs compiled with GHC (hledger, haskell build tools, etc.) need to        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. -       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.         Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:@@ -3593,8 +3600,8 @@               POSIX               $ 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-       listed  by  locale  -a, you might need to install it.  Eg on Ubuntu/De-+       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-        bian:                $ apt-get install language-pack-fr@@ -3614,8 +3621,8 @@               $ echo "export LANG=en_US.utf8" >>~/.bash_profile               $ bash --login -       Exact spelling and capitalisation may be important.  Note  the  differ--       ence  on  MacOS  (UTF-8,  not  utf8).  Some platforms (eg ubuntu) allow+       Exact  spelling  and capitalisation may be important.  Note the differ-+       ence on MacOS (UTF-8, not utf8).   Some  platforms  (eg  ubuntu)  allow        variant spellings, but others (eg macos) require it to be exact:                $ locale -a | grep -iE en_us.*utf@@ -3625,7 +3632,7 @@   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)  @@ -3646,4 +3653,4 @@   -hledger-1.20.1                   December 2020                      HLEDGER(1)+hledger-1.20.3                   December 2020                      HLEDGER(1)