807 lines
32 KiB
Plaintext
807 lines
32 KiB
Plaintext
balance, bal
|
|
Show accounts and their balances.
|
|
|
|
_FLAGS
|
|
|
|
balance is one of hledger's oldest and most versatile commands, for
|
|
listing account balances, balance changes, values, value changes and
|
|
more, during one time period or many. Generally it shows a table, with
|
|
rows representing accounts, and columns representing periods.
|
|
|
|
Note there are some higher-level variants of the balance command with
|
|
convenient defaults, which can be simpler to use: balancesheet,
|
|
balancesheetequity, cashflow and incomestatement. When you need more
|
|
control, then use balance.
|
|
|
|
balance features
|
|
|
|
Here's a quick overview of the balance command's features, followed by
|
|
more detailed descriptions and examples. Many of these work with the
|
|
higher-level commands as well.
|
|
|
|
balance can show..
|
|
|
|
- accounts as a list (-l) or a tree (-t)
|
|
- optionally depth-limited (-[1-9])
|
|
- sorted by declaration order and name, or by amount
|
|
|
|
..and their..
|
|
|
|
- balance changes (the default)
|
|
- or actual and planned balance changes (--budget)
|
|
- or value of balance changes (-V)
|
|
- or change of balance values (--valuechange)
|
|
|
|
..in..
|
|
|
|
- one time period (the whole journal period by default)
|
|
- or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
|
|
|
|
..either..
|
|
|
|
- per period (the default)
|
|
- or accumulated since report start date (--cumulative)
|
|
- or accumulated since account creation (--historical/-H)
|
|
|
|
..possibly converted to..
|
|
|
|
- cost (--value=cost[,COMM]/--cost/-B)
|
|
- or market value, as of transaction dates (--value=then[,COMM])
|
|
- or at period ends (--value=end[,COMM])
|
|
- or now (--value=now)
|
|
- or at some other date (--value=YYYY-MM-DD)
|
|
|
|
..with..
|
|
|
|
- totals (-T), averages (-A), percentages (-%), inverted sign
|
|
(--invert)
|
|
- rows and columns swapped (--transpose)
|
|
- another field used as account name (--pivot)
|
|
- custom-formatted line items (single-period reports only) (--format)
|
|
- commodities shown in a separate column, one per row
|
|
(--commodity-column)
|
|
|
|
This command supports the output destination and output format options,
|
|
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.
|
|
|
|
Simple balance report
|
|
|
|
With no arguments, balance shows a list of all accounts and their change
|
|
of balance - ie, the sum of posting amounts, both inflows and outflows -
|
|
during the entire period of the journal. For real-world accounts, this
|
|
should also match their end balance at the end of the journal period
|
|
(more on this below).
|
|
|
|
Accounts are sorted by declaration order if any, and then alphabetically
|
|
by account name. For instance, using examples/sample.journal:
|
|
|
|
$ hledger bal
|
|
$1 assets:bank:saving
|
|
$-2 assets:cash
|
|
$1 expenses:food
|
|
$1 expenses:supplies
|
|
$-1 income:gifts
|
|
$-1 income:salary
|
|
$1 liabilities:debts
|
|
--------------------
|
|
0
|
|
|
|
Accounts with a zero balance (and no non-zero subaccounts, in tree mode
|
|
- see below) are hidden by default. Use -E/--empty to show them
|
|
(revealing assets:bank:checking here):
|
|
|
|
$ hledger -f examples/sample.journal bal -E
|
|
0 assets:bank:checking
|
|
$1 assets:bank:saving
|
|
$-2 assets:cash
|
|
$1 expenses:food
|
|
$1 expenses:supplies
|
|
$-1 income:gifts
|
|
$-1 income:salary
|
|
$1 liabilities:debts
|
|
--------------------
|
|
0
|
|
|
|
The total of the amounts displayed is shown as the last line, unless
|
|
-N/--no-total is used.
|
|
|
|
Filtered balance report
|
|
|
|
You can show fewer accounts, a different time period, totals from
|
|
cleared transactions only, etc. by using query arguments or options to
|
|
limit the postings being matched. Eg:
|
|
|
|
$ hledger bal --cleared assets date:200806
|
|
$-2 assets:cash
|
|
--------------------
|
|
$-2
|
|
|
|
List or tree mode
|
|
|
|
By default, or with -l/--flat, accounts are shown as a flat list with
|
|
their full names visible, as in the examples above.
|
|
|
|
With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf"
|
|
names indented below their parent:
|
|
|
|
$ 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
|
|
|
|
Notes:
|
|
|
|
- "Boring" accounts are combined with their subaccount for more
|
|
compact output, unless --no-elide is used. Boring accounts have no
|
|
balance of their own and just one subaccount (eg assets:bank and
|
|
liabilities above).
|
|
|
|
- All balances shown are "inclusive", ie including the balances from
|
|
all subaccounts. Note this means some repetition in the output,
|
|
which requires explanation when sharing reports with
|
|
non-plaintextaccounting-users. A tree mode report's final total is
|
|
the sum of the top-level balances shown, not of all the balances
|
|
shown.
|
|
|
|
- Each group of sibling accounts (ie, under a common parent) is sorted
|
|
separately.
|
|
|
|
Depth limiting
|
|
|
|
With a depth:N query, or --depth N option, or just -N, balance reports
|
|
will show accounts only to the specified depth, hiding the deeper
|
|
subaccounts. Account balances at the depth limit always include the
|
|
balances from any hidden subaccounts (even in list mode). This can be
|
|
useful for getting an overview. Eg, limiting to depth 1:
|
|
|
|
$ hledger balance -N -1
|
|
$-1 assets
|
|
$2 expenses
|
|
$-2 income
|
|
$1 liabilities
|
|
|
|
You can also hide top-level account name parts, using --drop N. This can
|
|
be useful for hiding repetitive top-level account names:
|
|
|
|
$ hledger bal expenses --drop 1
|
|
$1 food
|
|
$1 supplies
|
|
--------------------
|
|
$2
|
|
|
|
Multi-period balance report
|
|
|
|
With a report interval (set by the -D/--daily, -W/--weekly,
|
|
-M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), balance
|
|
shows a tabular report, with columns representing successive time
|
|
periods (and a title):
|
|
|
|
$ 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
|
|
|
|
Notes:
|
|
|
|
- The report's start/end dates will be expanded, if necessary, to
|
|
fully encompass the displayed subperiods (so that the first and last
|
|
subperiods have the same duration as the others).
|
|
- Leading and trailing periods (columns) containing all zeroes are not
|
|
shown, unless -E/--empty is used.
|
|
- Accounts (rows) containing all zeroes are not shown, unless
|
|
-E/--empty is used.
|
|
- Amounts with many commodities are shown in abbreviated form, unless
|
|
--no-elide is used. (experimental)
|
|
- Average and/or total columns can be added with the -A/--average and
|
|
-T/--row-total flags.
|
|
- The --transpose flag can be used to exchange rows and columns.
|
|
- The --pivot FIELD option causes a different transaction field to be
|
|
used as "account name". See PIVOTING.
|
|
|
|
Multi-period reports with many periods can be too wide for easy viewing
|
|
in the terminal. Here are some ways to handle that:
|
|
|
|
- Hide the totals row with -N/--no-total
|
|
- Convert to a single currency with -V
|
|
- Maximize the terminal window
|
|
- Reduce the terminal's font size
|
|
- View with a pager like less, eg:
|
|
hledger bal -D --color=yes | less -RS
|
|
- Output as CSV and use a CSV viewer like visidata
|
|
(hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
|
|
(M-x csv-mode, C-c C-a), or a spreadsheet
|
|
(hledger bal -D -o a.csv && open a.csv)
|
|
- Output as HTML and view with a browser:
|
|
hledger bal -D -o a.html && open a.html
|
|
|
|
Commodity column
|
|
|
|
With --commodity-column, commodity symbols are displayed in a separate
|
|
column, and amounts are displayed as bare numbers. In this mode, each
|
|
report row will show amounts for a single commodity, using extra rows
|
|
when necessary. It can be useful for a cleaner display of reports with
|
|
many commodities:
|
|
|
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y
|
|
Balance changes in 2012-01-01..2014-12-31:
|
|
|
|
|| 2012 2013 2014 Total
|
|
==================++===========================================================================================================================
|
|
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
|
|
------------------++---------------------------------------------------------------------------------------------------------------------------
|
|
|| 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
|
|
|
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --commodity-column
|
|
Balance changes in 2012-01-01..2014-12-31:
|
|
|
|
|| Commodity 2012 2013 2014 Total
|
|
==================++=============================================
|
|
Assets:US:ETrade || GLD 0 70.00 0 70.00
|
|
Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
|
|
Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
|
|
Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
|
|
Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
|
|
------------------++---------------------------------------------
|
|
|| GLD 0 70.00 0 70.00
|
|
|| ITOT 10.00 18.00 -11.00 17.00
|
|
|| USD 337.18 -98.12 4881.44 5120.50
|
|
|| VEA 12.00 10.00 14.00 36.00
|
|
|| VHT 106.00 18.00 170.00 294.00
|
|
|
|
This flag also affects CSV output, which is useful for producing data
|
|
that is easier to consume, eg when making charts:
|
|
|
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv
|
|
"account","balance"
|
|
"Assets:US:ETrade","70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT"
|
|
"total","70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT"
|
|
|
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --commodity-column
|
|
"account","commodity","balance"
|
|
"Assets:US:ETrade","GLD","70.00"
|
|
"Assets:US:ETrade","ITOT","17.00"
|
|
"Assets:US:ETrade","USD","5120.50"
|
|
"Assets:US:ETrade","VEA","36.00"
|
|
"Assets:US:ETrade","VHT","294.00"
|
|
"total","GLD","70.00"
|
|
"total","ITOT","17.00"
|
|
"total","USD","5120.50"
|
|
"total","VEA","36.00"
|
|
"total","VHT","294.00"
|
|
|
|
Sorting by amount
|
|
|
|
With -S/--sort-amount, accounts with the largest (most positive)
|
|
balances are shown first. Eg: hledger bal expenses -MAS shows your
|
|
biggest averaged monthly expenses first. When more than one commodity is
|
|
present, they will be sorted by the alphabetically earliest commodity
|
|
first, and then by subsequent commodities (if an amount is missing a
|
|
commodity, it is treated as 0).
|
|
|
|
Revenues and liability balances are typically negative, however, so -S
|
|
shows these in reverse order. To work around this, you can add --invert
|
|
to flip the signs. (Or, use one of the higher-level reports, which flip
|
|
the sign automatically. Eg: hledger incomestatement -MAS).
|
|
|
|
Percentages
|
|
|
|
With -%/--percent, balance reports show each account's value expressed
|
|
as a percentage of the (column) total:
|
|
|
|
$ hledger bal expenses -Q -%
|
|
Balance changes in 2008:
|
|
|
|
|| 2008Q1 2008Q2 2008Q3 2008Q4
|
|
===================++=================================
|
|
expenses:food || 0 50.0 % 0 0
|
|
expenses:supplies || 0 50.0 % 0 0
|
|
-------------------++---------------------------------
|
|
|| 0 100.0 % 0 0
|
|
|
|
Note it is not useful to calculate percentages if the amounts in a
|
|
column have mixed signs. In this case, make a separate report for each
|
|
sign, eg:
|
|
|
|
$ hledger bal -% amt:`>0`
|
|
$ hledger bal -% amt:`<0`
|
|
|
|
Similarly, if the amounts in a column have mixed commodities, convert
|
|
them to one commodity with -B, -V, -X or --value, or make a separate
|
|
report for each commodity:
|
|
|
|
$ hledger bal -% cur:\\$
|
|
$ hledger bal -% cur:€
|
|
|
|
Balance change, end balance
|
|
|
|
It's important to be clear on the meaning of the numbers shown in
|
|
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.
|
|
|
|
An end balance is the amount accumulated in an account as of some date
|
|
(and some time, but hledger doesn't store that; assume end of day in
|
|
your timezone). 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. For a real world account, this means it
|
|
will match the "historical record", eg the balances reported in your
|
|
bank statements or bank web UI. (If they are correct!)
|
|
|
|
In general, balance changes are what you want to see when reviewing
|
|
revenues and expenses, and historical end balances are what you want to
|
|
see when reviewing or reconciling asset, liability and equity accounts.
|
|
|
|
balance shows balance changes by default. To see accurate historical end
|
|
balances:
|
|
|
|
1. Initialise account starting balances with an "opening balances"
|
|
transaction (a transfer from equity to the account), unless the
|
|
journal covers the account's full lifetime.
|
|
|
|
2. Include all of of the account's prior postings in the report, by not
|
|
specifying a report start date, or by using the -H/--historical
|
|
flag. (-H causes report start date to be ignored when summing
|
|
postings.)
|
|
|
|
Balance report types
|
|
|
|
For more flexible reporting, there are three important option groups:
|
|
|
|
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
|
|
|
|
The first two are the most important: 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:
|
|
|
|
- --sum : sum the posting amounts (default)
|
|
- --budget : like --sum but also show a goal amount
|
|
- --valuechange : show the change in period-end historical balance
|
|
values
|
|
|
|
Accumulation type:
|
|
Which postings should be included in each cell's calculation. It is one
|
|
of:
|
|
|
|
- --change : postings from column start to column end, ie within the
|
|
cell's period. Typically used to see revenues/expenses. (default for
|
|
balance, incomestatement)
|
|
|
|
- --cumulative : postings from report start to column end, eg to show
|
|
changes accumulated since the report's start date. Rarely used.
|
|
|
|
- --historical/-H : postings from journal start to column end, ie all
|
|
postings from account creation to the end of the cell's period.
|
|
Typically used to see historical end balances of
|
|
assets/liabilities/equity. (default for balancesheet,
|
|
balancesheetequity, cashflow)
|
|
|
|
Valuation type:
|
|
Which kind of valuation, valuation date(s) and optionally a target
|
|
valuation commodity to use. It is one of:
|
|
|
|
- no valuation, show amounts in their original commodities (default)
|
|
- --value=cost[,COMM] : no valuation, show amounts converted to cost
|
|
- --value=then[,COMM] : show value at transaction dates
|
|
- --value=end[,COMM] : show value at period end date(s) (default with
|
|
--valuechange)
|
|
- --value=now[,COMM] : show value at today's date
|
|
- --value=YYYY-MM-DD[,COMM] : show value at another date
|
|
|
|
or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
|
|
|
|
Most combinations of these options should produce reasonable reports,
|
|
but if you find any that seem wrong or misleading, let us know. The
|
|
following restrictions are applied:
|
|
|
|
- --valuechange implies --value=end
|
|
- --valuechange makes --change the default when used with the
|
|
balancesheet/balancesheetequity commands
|
|
- --cumulative or --historical disables --row-total/-T
|
|
|
|
For reference, here is what the combinations of accumulation and
|
|
valuation show:
|
|
|
|
------------------------------------------------------------------------------------------------
|
|
Valuation: no valuation --value= then --value= end --value= YYYY-MM-DD /now
|
|
>Accumulation: v
|
|
------------------ ---------------- ----------------- --------------- --------------------------
|
|
--change change in period sum of period-end DATE-value of change in
|
|
posting-date value of change period
|
|
market values in in period
|
|
period
|
|
|
|
--cumulative change from sum of period-end DATE-value of change from
|
|
report start to posting-date value of change report start to period end
|
|
period end market values from report
|
|
from report start start to period
|
|
to period end end
|
|
|
|
--historical /-H change from sum of period-end DATE-value of change from
|
|
journal start to posting-date value of change journal start to period
|
|
period end market values from journal end
|
|
(historical end from journal start to period
|
|
balance) start to period end
|
|
end
|
|
------------------------------------------------------------------------------------------------
|
|
|
|
Useful balance reports
|
|
|
|
Some frequently used balance options/reports are:
|
|
|
|
- bal -M revenues expenses
|
|
Show revenues/expenses in each month. Also available as the
|
|
incomestatement command.
|
|
|
|
- bal -M -H assets liabilities
|
|
Show historical asset/liability balances at each month end. Also
|
|
available as the balancesheet command.
|
|
|
|
- bal -M -H assets liabilities equity
|
|
Show historical asset/liability/equity balances at each month end.
|
|
Also available as the balancesheetequity command.
|
|
|
|
- bal -M assets not:receivable
|
|
Show changes to liquid assets in each month. Also available as the
|
|
cashflow command.
|
|
|
|
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.
|
|
|
|
- bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
|
|
Show top gainers [or losers] last week
|
|
|
|
Budget report
|
|
|
|
The --budget report type activates extra columns showing any budget
|
|
goals for each account and period. The budget goals are defined by
|
|
periodic transactions. This is very useful for comparing planned and
|
|
actual income, expenses, time usage, etc.
|
|
|
|
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 list mode. Eg assets,
|
|
assets:bank, and expenses above.
|
|
|
|
- Amounts always include all subaccounts, budgeted or unbudgeted, even
|
|
in list 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 and notes, see Budgeting.
|
|
|
|
Budget report start date
|
|
|
|
This might be a bug, but for now: when making budget reports, it's a
|
|
good idea to explicitly set the report's start date to the first day of
|
|
a reporting period, because a periodic rule like ~ monthly generates its
|
|
transactions on the 1st of each month, and if your journal has no
|
|
regular transactions on the 1st, the default report start date could
|
|
exclude that budget goal, which can be a little surprising. Eg here the
|
|
default report period is just the day of 2020-01-15:
|
|
|
|
~ monthly in 2020
|
|
(expenses:food) $500
|
|
|
|
2020-01-15
|
|
expenses:food $400
|
|
assets:checking
|
|
|
|
$ hledger bal expenses --budget
|
|
Budget performance in 2020-01-15:
|
|
|
|
|| 2020-01-15
|
|
==============++============
|
|
<unbudgeted> || $400
|
|
--------------++------------
|
|
|| $400
|
|
|
|
To avoid this, specify the budget report's period, or at least the start
|
|
date, with -b/-e/-p/date:, to ensure it includes the budget goal
|
|
transactions (periodic transactions) that you want. Eg, adding
|
|
-b 2020/1/1 to the above:
|
|
|
|
$ hledger bal expenses --budget -b 2020/1/1
|
|
Budget performance in 2020-01-01..2020-01-15:
|
|
|
|
|| 2020-01-01..2020-01-15
|
|
===============++========================
|
|
expenses:food || $400 [80% of $500]
|
|
---------------++------------------------
|
|
|| $400 [80% of $500]
|
|
|
|
Budgets and subaccounts
|
|
|
|
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]
|
|
|
|
Selecting budget goals
|
|
|
|
The budget report evaluates periodic transaction rules to generate
|
|
special "goal transactions", which generate the goal amounts for each
|
|
account in each report subperiod. When troubleshooting, you can use the
|
|
print command to show these as forecasted transactions:
|
|
|
|
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
|
|
|
|
By default, the budget report uses all available periodic transaction
|
|
rules to generate goals. This includes rules with a different report
|
|
interval from your report. Eg if you have daily, weekly and monthly
|
|
periodic rules, all of these will contribute to the goals in a monthly
|
|
budget report.
|
|
|
|
You can select a subset of periodic rules by providing an argument to
|
|
the --budget flag. --budget=DESCPAT will match all periodic rules whose
|
|
description contains DESCPAT, a case-insensitive substring (not a
|
|
regular expression or query). This means you can give your periodic
|
|
rules descriptions (remember that two spaces are needed), and then
|
|
select from multiple budgets defined in your journal.
|
|
|
|
Customising single-period balance reports
|
|
|
|
For single-period balance reports displayed in the terminal (only), you
|
|
can use --format FMT to customise the format and content of each line.
|
|
Eg:
|
|
|
|
$ 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
|