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

;bal: doc: more updates & cleanups (#1496)

Browse Source
This commit is contained in:
Simon Michael 2021-03-05 10:21:46 -08:00
parent baab33b58d
commit 2023e9cd65
1 changed files with 95 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
hledger/Hledger/Cli/Commands/Balance.md
View File

@ -3,12 +3,10 @@ Show accounts and their balances.
_FLAGS _FLAGS
`balance` is a flexible command for listing account balances, balance `balance` is one of hledger's oldest and most versatile commands,
changes, values, value changes, and more. for listing account balances, balance changes, values, value changes and more,
Generally it shows a table, with rows representing accounts, and during one time period or many.
columns representing time periods. Generally it shows a table, with rows representing accounts, and columns representing periods.
Compared to Ledger's balance command, hledger's `balance` adds the
significant feature of multi-period reports.
Note there are some higher-level variants of the `balance` command Note there are some higher-level variants of the `balance` command
with convenient defaults, which can be simpler to use: with convenient defaults, which can be simpler to use:
@ -18,9 +16,11 @@ with convenient defaults, which can be simpler to use:
[`incomestatement`](#incomestatement). [`incomestatement`](#incomestatement).
When you need more control, then use `balance`. When you need more control, then use `balance`.
Here's a quick overview of `balance` features ### balance features
(many of these work with the higher-level commands as well),
Here's a quick overview of the `balance` command's features,
followed by more detailed descriptions and examples. followed by more detailed descriptions and examples.
Many of these work with the higher-level commands as well.
`balance` can show.. `balance` can show..
- accounts as a [list (`-l`) or a tree (`-t`)](#list-or-tree-mode) - accounts as a [list (`-l`) or a tree (`-t`)](#list-or-tree-mode)
@ -30,10 +30,10 @@ followed by more detailed descriptions and examples.
..and their.. ..and their..
- balance changes ([`--change`](#simple-balance-report), the default report type) - balance changes (the default)
- or actual and planned balance changes ([`--budget`](#budget-report)) - or actual and planned balance changes ([`--budget`](#budget-report))
- or value of balance changes ([`--change -V`](#valuation-type)) - or value of balance changes ([`-V`](#valuation-type))
- or change of balance value ([`--valuechange`](#report-type)) - or change of balance values ([`--valuechange`](#report-type))
..in.. ..in..
@ -42,13 +42,13 @@ followed by more detailed descriptions and examples.
..either.. ..either..
- per period ([`--change`](#accumulation-type), the default accumulation type) - per period (the default)
- or accumulated since report start date ([`--cumulative`](#accumulation-type)) - or accumulated since report start date ([`--cumulative`](#accumulation-type))
- or accumulated since account creation ([`--historical/-H`](#accumulation-type)) - or accumulated since account creation ([`--historical/-H`](#accumulation-type))
..possibly converted to.. ..possibly converted to..
- cost ([`--value=cost[,COMM]/--cost/-B`](#valuation-type)) - cost ([`--value=cost[,COMM]`/`--cost`/`-B`](#valuation-type))
- or market value, as of transaction dates ([`--value=then[,COMM]`](#valuation-type)) - or market value, as of transaction dates ([`--value=then[,COMM]`](#valuation-type))
- or at period ends ([`--value=end[,COMM]`](#valuation-type)) - or at period ends ([`--value=end[,COMM]`](#valuation-type))
- or now ([`--value=now`](#valuation-type)) - or now ([`--value=now`](#valuation-type))
@ -70,8 +70,6 @@ This command supports the
with output formats `txt`, `csv`, `json`, and (multi-period reports only:) `html`. with output formats `txt`, `csv`, `json`, and (multi-period reports only:) `html`.
In `txt` output in a colour-supporting terminal, negative amounts are shown in red. In `txt` output in a colour-supporting terminal, negative amounts are shown in red.
<a name="classic-balance-report"></a>
### Simple balance report ### Simple balance report
With no arguments, `balance` shows a list of all accounts and their With no arguments, `balance` shows a list of all accounts and their
@ -198,6 +196,8 @@ $ hledger bal expenses --drop 1
$2 $2
``` ```
<a name="multicolumn-balance-report"></a>
### Multi-period balance report ### Multi-period balance report
With a [report interval](#report-intervals) (set by the `-D/--daily`, With a [report interval](#report-intervals) (set by the `-D/--daily`,
@ -300,9 +300,7 @@ $ hledger bal -% cur:\\$
$ hledger bal -% cur:€ $ hledger bal -% cur:€
``` ```
<a name="multicolumn-balance-report"></a> ### Balance change, end balance
### Balance change, end balance, historical end balance
It's important to be clear on the meaning of the numbers shown in It's important to be clear on the meaning of the numbers shown in
balance reports. Here is some terminology we use: balance reports. Here is some terminology we use:
@ -310,7 +308,7 @@ balance reports. Here is some terminology we use:
A ***balance change*** is the net amount added to, or removed from, an account during some period. A ***balance change*** is the net amount added to, or removed from, an account during some period.
An ***end balance*** is the amount accumulated in an account as of some date An ***end balance*** is the amount accumulated in an account as of some date
(and some time, but hledger doesn't model that; assume end of day in your timezone). (and some time, but hledger doesn't store that; assume end of day in your timezone).
It is the sum of previous balance changes. It is the sum of previous balance changes.
We call it a ***historical end balance*** if it includes all balance changes since the account was created. We call it a ***historical end balance*** if it includes all balance changes since the account was created.
@ -321,68 +319,63 @@ In general, balance changes are what you want to see when reviewing
revenues and expenses, and historical end balances are what you want revenues and expenses, and historical end balances are what you want
to see when reviewing or reconciling asset, liability and equity accounts. to see when reviewing or reconciling asset, liability and equity accounts.
As mentioned above, the default `balance` report shows balance changes. `balance` shows balance changes by default.
To ensure that you see accurate historical end balances: To see accurate historical end balances:
1. If the account's full lifetime is not recorded in the journal, 1. Initialise account starting balances with an "opening balances"
there should be an "opening balances" transaction (a transfer from transaction (a transfer from equity to the account),
equity to the account) that initialises its balance on some date unless the journal covers the account's full lifetime.
(often the first day of a year).
2. The report should include all of the account's prior postings, eg 2. Include all of of the account's prior postings in the report,
by leaving the [report start date](#report-start-end-date) eg by leaving the [report start date](#report-start-end-date) unspecified,
unspecified, or by using the `-H/--historical` flag, described or by using the `-H/--historical` flag.
below.
### Balance report types ### Balance report types
Fair warning: balance report modes can get confusing, so feel free to
just mimic the examples below, or just use the higher-level
bs/bse/cf/is commands.
For more flexible reporting, there are three important option groups: For more flexible reporting, there are three important option groups:
`hledger balance [REPORTTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...` `hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...`
#### Report type The first two are the most important:
The general thing that is calculated/shown in each cell. calculation type selects the basic calculation to perform for each table cell, while
accumulation type says which postings should be included in each cell's calculation.
Typically one or both of these are selected by default, so you don't need to write them explicitly.
A valuation type can be added if you want to convert the basic report to value or cost.
**Calculation type:**\
The basic calculation to perform for each table cell.
It is one of: It is one of:
- `--sum` : show a sum of posting amounts (**default**) - `--sum` : sum the posting amounts (**default**)
- `--budget` : like --sum but also show a budget goal amount - `--budget` : like --sum but also show a goal amount
- `--valuechange` : show change of value of period-end historical balances - `--valuechange` : show the change in period-end historical balance values
<!-- - `--gain` : show change of value of period-end historical balances caused by market price fluctuations --> <!-- - `--gain` : show the change in period-end historical balances values caused by market price fluctuations -->
#### Accumulation type **Accumulation type:**\
Which previous periods' postings should be included in calculations Which postings should be included in each cell's calculation.
(especially in multiperiod reports).
It is one of: It is one of:
- `--change` : postings from column start to column end. Ie, show - `--change` : postings from column start to column end, ie within the cell's period.
[changes] in each period. Typically used when reviewing Typically used with `--sum` to see revenues/expenses.
revenues/expenses. (**default for balance, incomestatement**) (**default for balance, incomestatement**)
<!-- /--periodic -->
- `--cumulative` : postings from report start (specified by - `--cumulative` : postings from report start to column end, eg to show
-b/--begin, eg) to column end. Ie, show [accumulated changes] since changes accumulated since the report's start date. Rarely used.
start of report. Rarely used.
- `--historical/-H` : postings from journal start to column end. Ie, - `--historical/-H` : postings from journal start to column end, ie
show [historical balance] at end of each period. Typically used when all postings from account creation to the end of the cell's period.
reviewing assets/liabilities/equity. (**default for balancesheet, Typically used to see historical end balances of assets/liabilities/equity.
balancesheetequity, cashflow**) (**default for balancesheet, balancesheetequity, cashflow**)
[changes]: #balance-change-end-balance-historical-end-balance **Valuation type:**\
[accumulated changes]: #balance-change-end-balance-historical-end-balance
[historical balance]: #balance-change-end-balance-historical-end-balance
#### Valuation type
Which kind of [valuation], [valuation date(s)] and optionally a target [valuation commodity] to use. Which kind of [valuation], [valuation date(s)] and optionally a target [valuation commodity] to use.
It is one of: It is one of:
- no valuation, show amounts in their original commodities (**default**) - no valuation, show amounts in their original commodities (**default**)
- `--value=cost[,COMM]` : no valuation, show amounts converted to cost - `--value=cost[,COMM]` : no valuation, show amounts converted to cost
- `--value=then[,COMM]` : show value at transaction dates - `--value=then[,COMM]` : show value at transaction dates
- `--value=end[,COMM]` : show value at period end date(s) - `--value=end[,COMM]` : show value at period end date(s) (**default with `--valuechange`**)
- `--value=now[,COMM]` : show value at today's date - `--value=now[,COMM]` : show value at today's date
- `--value=YYYY-MM-DD[,COMM]` : show value at another date - `--value=YYYY-MM-DD[,COMM]` : show value at another date
@ -392,39 +385,57 @@ or one of their aliases: [`--cost/-B`], [`--market/-V`] or [`--exchange/-X`].
[`--market/-V`]: #-v-value [`--market/-V`]: #-v-value
[`--exchange/-X`]: #-x-value-in-specified-commodity [`--exchange/-X`]: #-x-value-in-specified-commodity
### Combining balance report options <!-- ### Combining balance report types -->
Many but not all combinations of balance report options are useful. Most combinations of these options should produce reasonable reports,
Eg, `--row-total/-T` is disabled by `--cumulative` or `--historical`, but if you find any that seem wrong or misleading, let us know.
since summing already-summed end balances usually does not make sense. The following restrictions are applied:
Some important reports are: - `--valuechange` implies `--value=end`
- `--cumulative` or `--historical` disables `--row-total/-T`
- `bal revenues expenses` (`bal --change --sum revenues expenses`)\ For reference, here is what the combinations of accumulation and valuation show:
revenues/expenses in each period, an income statement / profit & loss report
- `bal -H assets liabilities` (`bal --historical --sum assets liabilities`)\ | Valuation: ><br>Accumulation: v | no valuation | `--value= then` | `--value= end` | `--value= YYYY-MM-DD /now` |
historical asset/liability balances at end of each period, a simplified balance sheet |---------------------------------|------------------------------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------|-------------------------------------------------------|
| `--periodic` | change in period | sum of posting-date market values in period | period-end value of change in period | DATE-value of change in period |
| `--cumulative` | change from report start to period end | sum of posting-date market values from report start to period end | period-end value of change from report start to period end | DATE-value of change from report start to period end |
| `--historical /-H` | change from journal start to period end (historical end balance) | sum of posting-date market values from journal start to period end | period-end value of change from journal start to period end | DATE-value of change from journal start to period end |
- `bal -H assets liabilities equity` (`bal --historical --change assets liabilities equity`)\ ### Frequently used balance reports
historical asset/liability/equity balances at end of each period, a full balance sheet
- `bal assets not:receivable` (`bal --change --sum assets not:receivable`)\ Some frequently used `balance` options/reports are:
liquid asset changes in each period, a cashflow report
Since these are so often used, they are also available as (enhanced) separate commands:\ - `bal -M revenues expenses`\
Show revenues/expenses in each month.
Also available as the [`incomestatement`](#incomestatement) command.
<!-- (= `bal --monthly --sum --change revenues expenses`)\ -->
- [`is`] (`incomestatement`) - `bal -M -H assets liabilities`\
- [`bs`] (`balancesheet`) Show historical asset/liability balances at each month end.
- [`bse`] (`balancesheetequity`) Also available as the [`balancesheet`](#balancesheet) command.
- [`cf`] (`cashflow`) <!-- (= `bal --monthly --sum --historical assets liabilities`)\ -->
[`is`]: #incomestatement - `bal -M -H assets liabilities equity`\
[`bs`]: #balancesheet Show historical asset/liability/equity balances at each month end.
[`bse`]: #balancesheetequity Also available as the [`balancesheetequity`](#balancesheetequity) command.
[`cf`]: #cashflow <!-- (= `bal --monthly --sum --historical assets liabilities equity`)\ -->
Here is what the accumulation / valuation type combinations show: - `bal -M assets not:receivable`\
Show changes to liquid assets in each month.
Also available as the [`cashflow`](#cashflow) command.
<!-- (= `bal --monthly --sum --change assets not:receivable`)\ -->
Also:
- `bal -M expenses -2 -SA`\
Show monthly expenses summarised to depth 2 and sorted by average amount.
- `bal -M --budget expenses`\
Show monthly expenses and budget goals.
- `bal -M --valuechange investments`\
Show monthly change in market value of investment assets.
| Valuation: ><br>Accumulation: v | no valuation | `--value= then` | `--value= end` | `--value= YYYY-MM-DD /now` | | Valuation: ><br>Accumulation: v | no valuation | `--value= then` | `--value= end` | `--value= YYYY-MM-DD /now` |
|---------------------------------|------------------------------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------|-------------------------------------------------------| |---------------------------------|------------------------------------------------------------------|--------------------------------------------------------------------|-------------------------------------------------------------|-------------------------------------------------------|
@ -433,6 +444,7 @@ Here is what the accumulation / valuation type combinations show:
| `--historical /-H` | change from journal start to period end (historical end balance) | sum of posting-date market values from journal start to period end | period-end value of change from journal start to period end | DATE-value of change from journal start to period end | | `--historical /-H` | change from journal start to period end (historical end balance) | sum of posting-date market values from journal start to period end | period-end value of change from journal start to period end | DATE-value of change from journal start to period end |
<!-- <!--
### Balance report examples ### Balance report examples
```shell ```shell