A ledger-compatible balance command, with additional support for multi-column reports.

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 examples/sample.journal, which defines the following account tree:

 assets
   bank
     checking
     saving
   cash
 expenses
   food
   supplies
 income
   gifts
   salary
 liabilities
   debts

the basic 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. (With --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. (The --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. (The --empty/-E flag forces such accounts to be displayed.) Eg, above 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. (The --no-elide flag prevents this.) Eg, above bank is elided to bank:saving because it has only a single displayed subaccount (saving) and their balance is the same ($1). Similarly, liabilities is elided to liabilities:debts.

Date limiting

The default report period is that of the whole journal, including all known transactions. The --begin/-b, --end/-e, --period/-p options or date:/date2: patterns can be used to report only on transactions before and/or after specified dates.

Depth limiting

The --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

Account limiting

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

• The o pattern matched food and 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-elide is in effect.
• An account with a zero inclusive balance and less than two interesting subaccounts is not displayed at all, unless --empty is in effect.
• Multi-column balance reports show full account names with no eliding (like --flat). Accounts (and periods) are omitted as described below.

Which accounts to show in balance reports

By default:

• single-column: accounts with non-zero balance in report period. (With --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

With -E/--empty:

• 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.

Currently,

by default:

• 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

With -E/--empty:

• 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.