507 lines
20 KiB
Plaintext
507 lines
20 KiB
Plaintext
balance, bal, b
|
|
Show accounts and their balances.
|
|
|
|
_FLAGS
|
|
|
|
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 and 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, 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:
|
|
|
|
$ hledger balance
|
|
$-1 assets
|
|
$1 bank:saving
|
|
$-2 cash
|
|
$2 expenses
|
|
$1 food
|
|
$1 supplies
|
|
$-2 income
|
|
$-1 gifts
|
|
$-1 salary
|
|
$1 liabilities:debts
|
|
--------------------
|
|
0
|
|
|
|
By default, accounts are displayed hierarchically, with subaccounts
|
|
indented below their parent. At each level of the tree, accounts are
|
|
sorted by account code if any, then by account name. Or with
|
|
-S/--sort-amount, by their balance amount, largest first. (Note: -S has
|
|
a problem in hledger 1.11-1.18).
|
|
|
|
"Boring" accounts, which contain a single interesting subaccount and no
|
|
balance of their own, are elided into the following line for more
|
|
compact output. (Eg above, the "liabilities" account.) 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,
|
|
eg:
|
|
|
|
$ hledger balance -p 2008/6 expenses --no-total
|
|
$2 expenses
|
|
$1 food
|
|
$1 supplies
|
|
|
|
Customising the classic balance report
|
|
|
|
You can customise the layout of classic balance reports with
|
|
--format FMT:
|
|
|
|
$ 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 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.
|
|
|
|
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
|
|
$1 food
|
|
$1 supplies
|
|
|
|
Depth limited balance reports
|
|
|
|
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.
|
|
|
|
$ 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.
|
|
|
|
Percentages
|
|
|
|
With -% or --percent, balance reports show each account's value
|
|
expressed as a percentage of the column's total. This is useful to get
|
|
an overview of the relative sizes of account balances. For example to
|
|
obtain an overview of expenses:
|
|
|
|
$ hledger balance expenses -%
|
|
100.0 % expenses
|
|
50.0 % food
|
|
50.0 % supplies
|
|
--------------------
|
|
100.0 %
|
|
|
|
Note that --tree does not have an effect on -%. The percentages are
|
|
always relative to the total sum of each column, they are never relative
|
|
to the parent account.
|
|
|
|
Since the percentages are relative to the columns sum, it is usually not
|
|
useful to calculate percentages if the signs of the amounts are mixed.
|
|
Although the results are technically correct, they are most likely
|
|
useless. Especially in a balance report that sums up to zero (eg
|
|
hledger balance -B) all percentage values will be zero.
|
|
|
|
This flag does not work if the report contains any mixed commodity
|
|
accounts. If there are mixed commodity accounts in the report be sure to
|
|
use -V or -B to coerce the report into using a single commodity.
|
|
|
|
Multicolumn balance report
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
$ hledger balance --quarterly income expenses -E
|
|
Balance changes in 2008:
|
|
|
|
|| 2008q1 2008q2 2008q3 2008q4
|
|
===================++=================================
|
|
expenses:food || 0 $1 0 0
|
|
expenses:supplies || 0 $1 0 0
|
|
income:gifts || 0 $-1 0 0
|
|
income:salary || $-1 0 0 0
|
|
-------------------++---------------------------------
|
|
|| $-1 $1 0 0
|
|
|
|
2. With --cumulative: each column shows the ending balance for that
|
|
period, accumulating the changes across periods, starting from 0 at
|
|
the report start date:
|
|
|
|
$ hledger balance --quarterly income expenses -E --cumulative
|
|
Ending balances (cumulative) in 2008:
|
|
|
|
|| 2008/03/31 2008/06/30 2008/09/30 2008/12/31
|
|
===================++=================================================
|
|
expenses:food || 0 $1 $1 $1
|
|
expenses:supplies || 0 $1 $1 $1
|
|
income:gifts || 0 $-1 $-1 $-1
|
|
income:salary || $-1 $-1 $-1 $-1
|
|
-------------------++-------------------------------------------------
|
|
|| $-1 0 0 0
|
|
|
|
3. With --historical/-H: each column shows the actual historical ending
|
|
balance for that period, accumulating the changes across periods,
|
|
starting from the actual balance at the report start date. This is
|
|
useful eg for a multi-period balance sheet, and when you are showing
|
|
only the data after a certain start date:
|
|
|
|
$ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
|
|
Ending balances (historical) in 2008/04/01-2008/12/31:
|
|
|
|
|| 2008/06/30 2008/09/30 2008/12/31
|
|
======================++=====================================
|
|
assets:bank:checking || $1 $1 0
|
|
assets:bank:saving || $1 $1 $1
|
|
assets:cash || $-2 $-2 $-2
|
|
liabilities:debts || 0 0 $1
|
|
----------------------++-------------------------------------
|
|
|| 0 0 0
|
|
|
|
Note that --cumulative or --historical/-H disable --row-total/-T, since
|
|
summing end balances generally does not make sense.
|
|
|
|
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 start/end
|
|
dates will be adjusted if necessary so that they encompass the displayed
|
|
report periods. This is so that the first and last periods will be
|
|
"full" and comparable to the others.
|
|
|
|
The -E/--empty flag does two things in multicolumn balance reports:
|
|
first, the report will show all columns within the specified report
|
|
period (without -E, leading and trailing columns with all zeroes are not
|
|
shown). Second, all accounts which existed at the report start date will
|
|
be considered, not just the ones with activity during the report period
|
|
(use -E to include low-activity accounts which would otherwise would be
|
|
omitted).
|
|
|
|
The -T/--row-total flag adds an additional column showing the total for
|
|
each row.
|
|
|
|
The -A/--average flag adds a column showing the average value in each
|
|
row.
|
|
|
|
Here's an example of all three:
|
|
|
|
$ hledger balance -Q income expenses --tree -ETA
|
|
Balance changes in 2008:
|
|
|
|
|| 2008q1 2008q2 2008q3 2008q4 Total Average
|
|
============++===================================================
|
|
expenses || 0 $2 0 0 $2 $1
|
|
food || 0 $1 0 0 $1 0
|
|
supplies || 0 $1 0 0 $1 0
|
|
income || $-1 $-1 0 0 $-2 $-1
|
|
gifts || 0 $-1 0 0 $-1 0
|
|
salary || $-1 0 0 0 $-1 0
|
|
------------++---------------------------------------------------
|
|
|| $-1 $1 0 0 0 0
|
|
|
|
(Average is rounded to the dollar here since all journal amounts are)
|
|
|
|
A limitation of multicolumn balance reports: eliding of boring parent
|
|
accounts in tree mode, as in the classic balance report, is not yet
|
|
supported.
|
|
|
|
The --transpose flag can be used to exchange the rows and columns of a
|
|
multicolumn report.
|
|
|
|
Budget report
|
|
|
|
With --budget, extra columns are displayed showing budget goals for each
|
|
account and period, if any. Budget goals are defined by 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.
|
|
|
|
For example, you can take average monthly expenses in the common expense
|
|
categories to construct a minimal monthly budget:
|
|
|
|
;; Budget
|
|
~ monthly
|
|
income $2000
|
|
expenses:food $400
|
|
expenses:bus $50
|
|
expenses:movies $30
|
|
assets:bank:checking
|
|
|
|
;; Two months worth of expenses
|
|
2017-11-01
|
|
income $1950
|
|
expenses:food $396
|
|
expenses:bus $49
|
|
expenses:movies $30
|
|
expenses:supplies $20
|
|
assets:bank:checking
|
|
|
|
2017-12-01
|
|
income $2100
|
|
expenses:food $412
|
|
expenses:bus $53
|
|
expenses:gifts $100
|
|
assets:bank:checking
|
|
|
|
You can now see a monthly budget report:
|
|
|
|
$ hledger balance -M --budget
|
|
Budget performance in 2017/11/01-2017/12/31:
|
|
|
|
|| Nov Dec
|
|
======================++====================================================
|
|
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
|
|
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] 0 [ 0]
|
|
|
|
This is different from a normal balance report in several ways:
|
|
|
|
- Only accounts with budget goals during the report period are shown,
|
|
by default.
|
|
|
|
- In each column, in square brackets after the actual amount, budget
|
|
goal amounts are shown, and the actual/goal percentage. (Note:
|
|
budget goals should be in the same commodity as the actual amount.)
|
|
|
|
- All parent accounts are always shown, even in flat mode. Eg assets,
|
|
assets:bank, and expenses above.
|
|
|
|
- Amounts always include all subaccounts, budgeted or unbudgeted, even
|
|
in flat mode.
|
|
|
|
This means that the numbers displayed will not always add up! Eg above,
|
|
the expenses actual amount includes the gifts and supplies transactions,
|
|
but the expenses:gifts and expenses:supplies accounts are not shown, as
|
|
they have no budget amounts declared.
|
|
|
|
This can be confusing. When you need to make things clearer, use the
|
|
-E/--empty flag, which will reveal all accounts including unbudgeted
|
|
ones, giving the full picture. Eg:
|
|
|
|
$ hledger balance -M --budget --empty
|
|
Budget performance in 2017/11/01-2017/12/31:
|
|
|
|
|| Nov Dec
|
|
======================++====================================================
|
|
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
|
|
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] 0 [ 0]
|
|
|
|
You can roll over unspent budgets to next period with --cumulative:
|
|
|
|
$ hledger balance -M --budget --cumulative
|
|
Budget performance in 2017/11/01-2017/12/31:
|
|
|
|
|| Nov Dec
|
|
======================++====================================================
|
|
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
|
|
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
|
|
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
|
|
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
|
|
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] 0 [ 0]
|
|
|
|
For more examples, see Budgeting and Forecasting.
|
|
|
|
Nested budgets
|
|
|
|
You can add budgets to any account in your account hierarchy. If you
|
|
have budgets on both parent account and some of its children, then
|
|
budget(s) of the child account(s) would be added to the budget of their
|
|
parent, much like account balances behave.
|
|
|
|
In the most simple case this means that once you add a budget to any
|
|
account, all its parents would have budget as well.
|
|
|
|
To illustrate this, consider the following budget:
|
|
|
|
~ monthly from 2019/01
|
|
expenses:personal $1,000.00
|
|
expenses:personal:electronics $100.00
|
|
liabilities
|
|
|
|
With this, monthly budget for electronics is defined to be $100 and
|
|
budget for personal expenses is an additional $1000, which implicitly
|
|
means that budget for both expenses:personal and expenses is $1100.
|
|
|
|
Transactions in expenses:personal:electronics will be counted both
|
|
towards its $100 budget and $1100 of expenses:personal , and
|
|
transactions in any other subaccount of expenses:personal would be
|
|
counted towards only towards the budget of expenses:personal.
|
|
|
|
For example, let's consider these transactions:
|
|
|
|
~ monthly from 2019/01
|
|
expenses:personal $1,000.00
|
|
expenses:personal:electronics $100.00
|
|
liabilities
|
|
|
|
2019/01/01 Google home hub
|
|
expenses:personal:electronics $90.00
|
|
liabilities $-90.00
|
|
|
|
2019/01/02 Phone screen protector
|
|
expenses:personal:electronics:upgrades $10.00
|
|
liabilities
|
|
|
|
2019/01/02 Weekly train ticket
|
|
expenses:personal:train tickets $153.00
|
|
liabilities
|
|
|
|
2019/01/03 Flowers
|
|
expenses:personal $30.00
|
|
liabilities
|
|
|
|
As you can see, we have transactions in
|
|
expenses:personal:electronics:upgrades and
|
|
expenses:personal:train tickets, and since both of these accounts are
|
|
without explicitly defined budget, these transactions would be counted
|
|
towards budgets of expenses:personal:electronics and expenses:personal
|
|
accordingly:
|
|
|
|
$ hledger balance --budget -M
|
|
Budget performance in 2019/01:
|
|
|
|
|| Jan
|
|
===============================++===============================
|
|
expenses || $283.00 [ 26% of $1100.00]
|
|
expenses:personal || $283.00 [ 26% of $1100.00]
|
|
expenses:personal:electronics || $100.00 [ 100% of $100.00]
|
|
liabilities || $-283.00 [ 26% of $-1100.00]
|
|
-------------------------------++-------------------------------
|
|
|| 0 [ 0]
|
|
|
|
And with --empty, we can get a better picture of budget allocation and
|
|
consumption:
|
|
|
|
$ hledger balance --budget -M --empty
|
|
Budget performance in 2019/01:
|
|
|
|
|| Jan
|
|
========================================++===============================
|
|
expenses || $283.00 [ 26% of $1100.00]
|
|
expenses:personal || $283.00 [ 26% of $1100.00]
|
|
expenses:personal:electronics || $100.00 [ 100% of $100.00]
|
|
expenses:personal:electronics:upgrades || $10.00
|
|
expenses:personal:train tickets || $153.00
|
|
liabilities || $-283.00 [ 26% of $-1100.00]
|
|
----------------------------------------++-------------------------------
|
|
|| 0 [ 0]
|
|
|
|
Output format
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, (multicolumn
|
|
non-budget reports only) html, and (experimental) json.
|