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

doc: update balance docs

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2018-04-25 16:08:14 -07:00
parent 9e2e5adfaa
commit c4d18d1fe5
1 changed files with 138 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
hledger/hledger_balance.m4.md
View File

@ -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.
<!-- XXX retest:
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
-->
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.
<!-- $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done -->
### 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:
<!--
multi-column income statement:
multicolumn income statement:
$ hledger balance ^income ^expense -p 'monthly this year' --depth 3
@ -202,7 +286,7 @@ you are showing only the data after a certain start date:
```
Multi-column balance reports display accounts in flat mode by default;
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
@ -245,82 +329,18 @@ Balance changes in 2008:
```
Eliding of boring parent accounts, as in the classic balance report,
is not yet supported in multicolumn reports.
Currently, the [`-V/--value` flag](#market-value) has a limitation in
multicolumn reports: it uses the market prices on the report end date
for all columns. (Instead of the prices on each column's end date.)
### Custom balance output
You can customise the layout of simple (non-tabular) 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.
<!-- XXX retest:
Consistent column widths are not well enforced, causing ragged edges unless you set suitable widths.
Beware of specifying a maximum width; it will clip account names and amounts that are too wide, with no visible indication.
-->
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:
Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
=======================++=================================================
<unbudgeted>:expenses || $20 $100
======================++=================================================
<unbudgeted> || $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
```
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 `<unbudgeted>`.
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:
Budget performance in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31
=======================++=================================================
<unbudgeted>:expenses || $20 $120
======================++=================================================
<unbudgeted> || $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 `<unbudgeted>`, 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:
|| 2017/11 2017/12
======================++=================================================
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
```
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.
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.