diff --git a/hledger/hledger_balance.m4.md b/hledger/hledger_balance.m4.md index ea32d3e08..798030e89 100644 --- a/hledger/hledger_balance.m4.md +++ b/hledger/hledger_balance.m4.md @@ -56,8 +56,29 @@ txt, csv, html. `--show-unbudgeted` : with --budget, show unbudgeted accounts also -The balance command displays accounts and balances. -It is hledger's most featureful and versatile command. +The balance command is hledger's most versatile command. +Note, despite the name, it is not always used for showing real-world account balances; +the more accounting-aware [balancesheet](#balancesheet) +and [incomestatement](#incomestatement) may be more convenient for that. + +By default, it displays all accounts, +and each account's change in balance during the entire period of the journal. +Balance changes are calculated by adding up the postings in each account. +You can limit the postings matched, by a [query](#queries), to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. + +If you include an account's complete history of postings in the report, +the balance change is equivalent to the account's current ending balance. +For a real-world account, typically you won't have all transactions in the journal; +instead you'll have all transactions after a certain date, and an "opening balances" +transaction setting the correct starting balance on that date. +Then the balance command will show real-world account balances. +In some cases the -H/--historical flag is used to ensure this (more below). + +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: ```shell $ hledger balance @@ -75,23 +96,20 @@ $ hledger balance 0 ``` -More precisely, the balance command shows the *change* to each account's balance caused by all (matched) postings. -In the common case where you do not filter by date and your journal sets the correct opening balances, this is the same as the account's ending balance. - By default, accounts are displayed hierarchically, with subaccounts indented below their parent. At each level of the tree, accounts are sorted by [account code](/manual.html#account-directive) if any, then by account name. Or with `-S/--sort-amount`, by their balance amount. "Boring" accounts, which contain a single interesting subaccount and no balance of their own, are elided into the following line for more compact output. -(Not yet supported in tabular reports.) Use `--no-elide` to prevent this. +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: +A final total is displayed by default; use `-N/--no-total` to suppress it, eg: ```shell $ hledger balance -p 2008/6 expenses --no-total @@ -100,10 +118,73 @@ $ hledger balance -p 2008/6 expenses --no-total $1 supplies ``` +### Customising the classic balance report + +You can customise the layout of classic balance reports with `--format FMT`: + +```shell +$ 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 + +The balance command shows negative amounts in red, if: + +- the `TERM` environment variable is not set to `dumb` +- the output is not being redirected or piped anywhere + ### Flat mode -To see a flat list of full account names instead of the default hierarchical display, use `--flat`. -In this mode, accounts (unless depth-clipped) show their "exclusive" balance, excluding any subaccount balances. +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. ```shell @@ -114,31 +195,34 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1 ### Depth limited balance reports -With `--depth N`, balance shows accounts only to the specified depth. -This is very useful to show a complex charts of accounts in less detail. -In flat mode, balances from accounts below the depth limit will be shown as part of a parent account at the depth limit. - +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. ```shell -$ hledger balance -N --depth 1 +$ 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. + -### Multicolumn balance reports +### Multicolumn balance report -With a [reporting interval](#reporting-interval), multiple balance -columns will be shown, one for each report period. -There are three types of multi-column balance report, showing different information: +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](#reporting-interval). + +There are three types of multicolumn balance report, 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: -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 - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. - -### Colour support - -The balance command shows negative amounts in red, if: - -- the `TERM` environment variable is not set to `dumb` -- the output is not being redirected or piped anywhere - - ### Budget report -With `--budget`, extra columns are displayed showing budget goals for each account and period, -and how the actual amounts compare with the goals. -Budget goals are defined by [periodic transactions](journal.html#periodic-transactions) in the journal. - +With `--budget`, extra columns are displayed showing budget goals for each account and period, if any. +Budget goals are defined by [periodic transactions](journal.html#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](manual.html#report-intervals). For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: @@ -350,63 +370,48 @@ For example, you can take average monthly expenses in the common expense categor assets:bank:checking ``` -You can now see a monthly budget performance report: +You can now see a monthly budget report: ```shell $ hledger balance -M --budget -Balance changes in 2017/11/01-2017/12/31: - - || 2017/11 2017/12 -=======================++================================================= - :expenses || $20 $100 - assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] - expenses:bus || $49 [98% of $50] $53 [106% of $50] - expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:movies || $30 [100% of $30] 0 [0% of $30] - income || $1950 [98% of $2000] $2100 [105% of $2000] ------------------------++------------------------------------------------- - || 0 0 -``` - -You can roll over unspent budgets to next period with `--cumulative`: -```shell -$ hledger balance -M --budget --cumulative -Ending balances (cumulative) in 2017/11/01-2017/12/31: - - || 2017/11/30 2017/12/31 -=======================++================================================= - :expenses || $20 $120 - assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] - expenses:bus || $49 [98% of $50] $102 [102% of $100] - expenses:food || $396 [99% of $400] $808 [101% of $800] - expenses:movies || $30 [100% of $30] $30 [50% of $60] - income || $1950 [98% of $2000] $4050 [101% of $4000] ------------------------++------------------------------------------------- - || 0 0 -``` - -Accounts with no budget goals (not mentioned in the periodic transactions) -will be aggregated under ``, unless you add the -`--show-unbudgeted` flag to display them normally: -```shell -$ hledger balance --budget --show-unbudgeted -Balance changes in 2017/11/01-2017/12/31: +Budget performance in 2017/11/01-2017/12/31: || 2017/11 2017/12 ======================++================================================= + || $20 $100 assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] expenses:bus || $49 [98% of $50] $53 [106% of $50] expenses:food || $396 [99% of $400] $412 [103% of $400] - expenses:gifts || 0 $100 expenses:movies || $30 [100% of $30] 0 [0% of $30] - expenses:supplies || $20 0 income || $1950 [98% of $2000] $2100 [105% of $2000] ----------------------++------------------------------------------------- || 0 0 ``` +By default, only accounts with budget goals during the report period are shown. +`--show-unbudgeted` shows unbudgeted accounts as well. +Top-level accounts with no budget goals anywhere below them are grouped under ``. -Note --budget first arrived in hledger in 1.5 and is still pretty young; -join the discussions on mail list and issue tracker to help us refine it. -Also, the `-S/--sort-amount` flag is not yet supported with --budget. +You can roll over unspent budgets to next period with `--cumulative`: +```shell +$ hledger balance -M --budget --cumulative +Budget performance in 2017/11/01-2017/12/31: + + || 2017/11/30 2017/12/31 +======================++================================================= + || $20 $120 + assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] + expenses:bus || $49 [98% of $50] $102 [102% of $100] + expenses:food || $396 [99% of $400] $808 [101% of $800] + expenses:movies || $30 [100% of $30] $30 [50% of $60] + income || $1950 [98% of $2000] $4050 [101% of $4000] +----------------------++------------------------------------------------- + || 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). +### Output format + +The balance command supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +