From 3dbd1378debc5bd0ec4bb14d8b59ef835f4620c3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 24 Feb 2019 20:36:04 -0800 Subject: [PATCH] bal: doc: clarify budget report differences; drop sorting limitation [ci skip] --- hledger/Hledger/Cli/Commands/Balance.md | 27 +++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index 09614b7b8..64ed3dcd1 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -247,8 +247,7 @@ period (without -E, leading and trailing columns with all zeroes are not shown). Second, all accounts which existed at the report start date will be considered, not just the ones with activity during the report period (use -E to include low-activity accounts which would -otherwise would be omitted). With `--budget`, `--empty` also shows -unbudgeted accounts. +otherwise would be omitted). The `-T/--row-total` flag adds an additional column showing the total for each row. @@ -339,12 +338,26 @@ Budget performance in 2017/11/01-2017/12/31: || 0 [ 0] 0 [ 0] ``` -By default, only accounts with budget goals during the report period are shown. In the example -above, transactions in `expenses:gifts` and `expenses:supplies` are counted towards `expenses` budget, -but accounts `expenses:gifts` and `expenses:supplies` are not shown, as they don't have any budgets. +Note this is different from a normal balance report in several ways: +- Only accounts with budget goals during the report period are shown, by default. + +- In each column, in square brackets after the actual amount, budgeted amounts are shown, + along with the percentage of budget used. + +- All parent accounts are always shown, even in flat mode. + Eg assets, assets:bank, and expenses above. + +- 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 transactions, +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 ones, giving the full picture. Eg: -You can use `--empty` shows unbudgeted accounts as well: ```shell $ hledger balance -M --budget --empty Budget performance in 2017/11/01-2017/12/31: @@ -385,8 +398,6 @@ Budget performance in 2017/11/01-2017/12/31: || 0 [ 0] 0 [ 0] ``` -Note, the `-S/--sort-amount` flag is not yet fully supported with `--budget`. - For more examples, see [Budgeting and Forecasting](https://github.com/simonmichael/hledger/wiki/Budgeting and forecasting). #### Nested budgets