balance command, with additional support for
Here is a description/specification for the balance command. See also Hledger.Reports -> "Balance reports".
Basic balance report
With no report interval (
--monthly etc.), hledger's balance
command emulates ledger's, showing accounts indented according to
hierarchy, along with their total amount posted (including subaccounts).
Here's an example. With
data/sample.journal, which defines the following account tree:
assets bank checking saving cash expenses food supplies income gifts salary liabilities debts
balance command gives this output:
$ hledger -f sample.journal balance $-1 assets $1 bank:saving $-2 cash $2 expenses $1 food $1 supplies $-2 income $-1 gifts $-1 salary $1 liabilities:debts -------------------- 0
Subaccounts are displayed indented below their parent. Only the account leaf name (the final part) is shown.
--flat, account names are shown in full and unindented.)
Each account's "balance" is the sum of postings in that account and any subaccounts during the report period. When the report period includes all transactions, this is equivalent to the account's current balance.
The overall total of the highest-level displayed accounts is shown below the line.
--no-total/-N flag prevents this.)
Eliding and omitting
Accounts which have a zero balance, and no non-zero subaccount
balances, are normally omitted from the report.
--empty/-E flag forces such accounts to be displayed.)
checking is omitted because it has a zero balance and no subaccounts.
Accounts which have a single subaccount also being displayed, with the same balance,
are normally elided into the subaccount's line.
--no-elide flag prevents this.)
bank is elided to
bank:saving because it has only a
single displayed subaccount (
saving) and their balance is the same
liabilities is elided to
The default report period is that of the whole journal, including all
known transactions. The
date2: patterns can be used to report only
on transactions before and/or after specified dates.
--depth option can be used to limit the depth of the balance report.
Eg, to see just the top level accounts (still including their subaccount balances):
$ hledger -f sample.journal balance --depth 1 $-1 assets $2 expenses $-2 income $1 liabilities -------------------- 0
With one or more account pattern arguments, the report is restricted
to accounts whose name matches one of the patterns, plus their parents
and subaccounts. Eg, adding the pattern
o to the first example gives:
$ hledger -f sample.journal balance o $1 expenses:food $-2 income $-1 gifts $-1 salary -------------------- $-1
income, so they are shown.
food's parent (
expenses) is shown even though the pattern didn't match it, to clarify the hierarchy. The usual eliding rules cause it to be elided here.
income's subaccounts are also shown.
Multi-column balance report
hledger's balance command will show multiple columns when a reporting
interval is specified (eg with
--monthly), one column for each sub-period.
There are three kinds of multi-column balance report, indicated by the heading:
- A "period balance" (or "flow") report (the default) shows the change of account balance in each period, which is equivalent to the sum of postings in each period. Here, checking's balance increased by 10 in Feb:
Change of balance (flow): Jan Feb Mar assets:checking 20 10 -5
- A "cumulative balance" report (with
--cumulative) shows the accumulated ending balance across periods, starting from zero at the report's start date. Here, 30 is the sum of checking postings during Jan and Feb:
Ending balance (cumulative): Jan Feb Mar assets:checking 20 30 25
- A "historical balance" report (with
--historical/-H) also shows ending balances, but it includes the starting balance from any postings before the report start date. Here, 130 is the balance from all checking postings at the end of Feb, including pre-Jan postings which created a starting balance of 100:
Ending balance (historical): Jan Feb Mar assets:checking 120 130 125
Eliding and omitting, 2
Here's a (imperfect?) specification for the eliding/omitting behaviour:
- Each account is normally displayed on its own line.
- An account less deep than the report's max depth, with just one
interesting subaccount, and the same balance as the subaccount, is
non-interesting, and prefixed to the subaccount's line, unless
--no-elideis in effect.
- An account with a zero inclusive balance and less than two interesting
subaccounts is not displayed at all, unless
--emptyis in effect.
- Multi-column balance reports show full account names with no eliding
--flat). Accounts (and periods) are omitted as described below.
Which accounts to show in balance reports
- single-column: accounts with non-zero balance in report period.
--flat: accounts with non-zero balance and postings.)
- periodic: accounts with postings and non-zero period balance in any period
- cumulative: accounts with non-zero cumulative balance in any period
- historical: accounts with non-zero historical balance in any period
- single-column: accounts with postings in report period
- periodic: accounts with postings in report period
- cumulative: accounts with postings in report period
- historical: accounts with non-zero starting balance + accounts with postings in report period
Which periods (columns) to show in balance reports
An empty period/column is one where no report account has any postings. A zero period/column is one where no report account has a non-zero period balance.
- single-column: N/A
- periodic: all periods within the overall report period, except for leading and trailing empty periods
- cumulative: all periods within the overall report period, except for leading and trailing empty periods
- historical: all periods within the overall report period, except for leading and trailing empty periods
- single-column: N/A
- periodic: all periods within the overall report period
- cumulative: all periods within the overall report period
- historical: all periods within the overall report period
What to show in empty cells
An empty periodic balance report cell is one which has no corresponding postings. An empty cumulative/historical balance report cell is one which has no correponding or prior postings, ie the account doesn't exist yet. Currently, empty cells show 0.
- balancemode :: Mode RawOpts
- balance :: CliOpts -> Journal -> IO ()
- balanceReportAsText :: ReportOpts -> BalanceReport -> String
- balanceReportItemAsText :: ReportOpts -> StringFormat -> BalanceReportItem -> [String]
- periodChangeReportAsText :: ReportOpts -> MultiBalanceReport -> String
- cumulativeChangeReportAsText :: ReportOpts -> MultiBalanceReport -> String
- historicalBalanceReportAsText :: ReportOpts -> MultiBalanceReport -> String
- tests_Hledger_Cli_Balance :: Test
Render a single-column balance report as plain text.
Render one balance report line item as plain text suitable for console output (or whatever string format is specified). Note, prices will not be rendered, and differently-priced quantities of the same commodity will appear merged. The output will be one or more lines depending on the format and number of commodities.
Render a multi-column period balance report as plain text suitable for console output.
Render a multi-column cumulative balance report as plain text suitable for console output.
Render a multi-column historical balance report as plain text suitable for console output.