simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-09-18 17:57:11 +03:00
Code Issues Projects Releases Wiki Activity

doc: regenerate embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2018-04-25 17:43:34 -07:00
parent 541e517221
commit d7f6ff0e18
6 changed files with 901 additions and 820 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
hledger-lib/hledger_journal.5
View File

@ -1061,11 +1061,8 @@ and a line containing just \f[C]end\ comment\f[] ends it.
See comments.
.SS commodity directive
.PP
The \f[C]commodity\f[] directive predefines commodities (currently this
is just informational), and also it may define the display format for
amounts in this commodity (overriding the automatically inferred
format).
.PP
The \f[C]commodity\f[] directive declares commodities which may be used
in the journal (though currently we do not enforce this).
It may be written on a single line, like this:
.IP
.nf
@ -1095,6 +1092,15 @@ commodity\ INR
\ \ format\ INR\ 9,99,99,999.00
\f[]
.fi
.PP
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity.
Normally the display format is inferred from journal entries, but this
can be unpredictable; declaring it with a commodity directive overrides
this and removes ambiguity.
Towards this end, amounts in commodity directives must always be written
with a decimal point (a period or comma, followed by 0 or more decimal
digits).
.SS Default commodity
.PP
The D directive sets a default commodity (and display format), to be
@ -1114,6 +1120,9 @@ D\ $1,000.00
\ \ b
\f[]
.fi
.PP
As with the \f[C]commodity\f[] directive, the amount must always be
written with a decimal point.
.SS Default year
.PP
You can set a default year to be used for subsequent dates which don't

43
hledger-lib/hledger_journal.info
View File

@ -997,11 +997,9 @@ File: hledger_journal.info, Node: commodity directive, Next: Default commodity
1.14.5 commodity directive
--------------------------
The 'commodity' directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts in
this commodity (overriding the automatically inferred format).
It may be written on a single line, like this:
The 'commodity' directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written on
a single line, like this:
; commodity EXAMPLEAMOUNT
@ -1023,6 +1021,14 @@ places:
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display
format is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by 0
or more decimal digits).

File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
@ -1043,6 +1049,9 @@ D $1,000.00
a 5 ; <- commodity-less amount, becomes $1
b
As with the 'commodity' directive, the amount must always be written
with a decimal point.

File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
@ -1259,17 +1268,17 @@ Node: Multi-line comments35168
Ref: #multi-line-comments35358
Node: commodity directive35486
Ref: #commodity-directive35670
Node: Default commodity36542
Ref: #default-commodity36715
Node: Default year37252
Ref: #default-year37417
Node: Including other files37840
Ref: #including-other-files37997
Node: Periodic transactions38394
Ref: #periodic-transactions38560
Node: Automated postings39549
Ref: #automated-postings39712
Node: EDITOR SUPPORT40840
Ref: #editor-support40965
Node: Default commodity36897
Ref: #default-commodity37070
Node: Default year37702
Ref: #default-year37867
Node: Including other files38290
Ref: #including-other-files38447
Node: Periodic transactions38844
Ref: #periodic-transactions39010
Node: Automated postings39999
Ref: #automated-postings40162
Node: EDITOR SUPPORT41290
Ref: #editor-support41415

End Tag Table

79
hledger-lib/hledger_journal.txt
View File

@ -770,11 +770,9 @@ FILE FORMAT
containing just end comment ends it. See comments.
commodity directive
The commodity directive predefines commodities (currently this is just
informational), and also it may define the display format for amounts
in this commodity (overriding the automatically inferred format).
It may be written on a single line, like this:
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -796,6 +794,14 @@ FILE FORMAT
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
@ -811,9 +817,12 @@ FILE FORMAT
a 5 ; <- commodity-less amount, becomes $1
b
As with the commodity directive, the amount must always be written with
a decimal point.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -833,58 +842,58 @@ FILE FORMAT
assets
Including other files
You can pull in the content of additional journal files by writing an
You can pull in the content of additional journal files by writing an
include directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
If the path does not begin with a slash, it is relative to the current
file. Glob patterns (*) are not currently supported.
The include directive can only be used in journal files. It can
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Periodic transactions
Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with --forecast), or budget
goals (with --budget). They look a bit like a transaction, except the
Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with --forecast), or budget
goals (with --budget). They look a bit like a transaction, except the
first line is a tilde (~) followed by a period expression:
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
With --forecast, each periodic transaction rule generates recurring
"forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are
no transactions) and ending 6 months from today (or at the report end
With --forecast, each periodic transaction rule generates recurring
"forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are
no transactions) and ending 6 months from today (or at the report end
date, if specified).
With balance --budget, each periodic transaction declares recurring
With balance --budget, each periodic transaction declares recurring
budget goals for the specified accounts. Eg the example above declares
the goal of receiving $400 from income:acme inc (and also, depositing
the goal of receiving $400 from income:acme inc (and also, depositing
$400 into assets:bank:checking) every week.
For more details, see: balance: Budgeting and Budgeting and Forecast-
For more details, see: balance: Budgeting and Budgeting and Forecast-
ing.
Automated postings
Automated postings are postings added automatically by rule to certain
transactions (with --auto). An automated posting rule looks like a
transaction where the first line is an equal sign (=) followed by a
Automated postings are postings added automatically by rule to certain
transactions (with --auto). An automated posting rule looks like a
transaction where the first line is an equal sign (=) followed by a
query:
= expenses:gifts
budget:gifts *-1
assets:budget *1
The posting amounts can be of the form *N, which means "the amount of
the matched transaction's first posting, multiplied by N". They can
The posting amounts can be of the form *N, which means "the amount of
the matched transaction's first posting, multiplied by N". They can
also be ordinary fixed amounts. Fixed amounts with no commodity symbol
will be given the same commodity as the matched transaction's first
will be given the same commodity as the matched transaction's first
posting.
This example adds a corresponding (unbalanced) budget posting to every
This example adds a corresponding (unbalanced) budget posting to every
transaction involving the expenses:gifts account:
= expenses:gifts
@ -900,18 +909,18 @@ Automated postings
(budget:gifts) $-20
assets
Automated postings would not be distinguishable from equivalent post-
ings written by hand. In particular, they would affect [amount infer-
ence|#postings] and [balance assertion|#balance-assertions] checks in
Automated postings would not be distinguishable from equivalent post-
ings written by hand. In particular, they would affect [amount infer-
ence|#postings] and [balance assertion|#balance-assertions] checks in
the usual way.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger
These were written with Ledger in mind, but also work with hledger
files:
@ -930,7 +939,7 @@ EDITOR SUPPORT
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -944,7 +953,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

342
hledger/hledger.1
View File

@ -1018,8 +1018,8 @@ $\ hledger\ \-f\ t.j\ bal\ \-N\ euros\ \-V
Currently, hledger's \-V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
.PP
Currently, the \-V has a limitation with in multicolumn balance reports:
it uses the market prices on the report end date for all columns.
Currently, \-V has a limitation in multicolumn balance reports: it uses
the market prices on the report end date for all columns.
(Instead of the prices on each column's end date.)
.SS Combining \-B and \-V
.PP
@ -1550,8 +1550,35 @@ with \[en]budget, show unbudgeted accounts also
.RS
.RE
.PP
The balance command displays accounts and balances.
It is hledger's most featureful and versatile command.
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.
.PP
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.
.PP
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 \[lq]opening balances\[rq] transaction setting the correct
starting balance on that date.
Then the balance command will show real\-world account balances.
In some cases the \-H/\[en]historical flag is used to ensure this (more
below).
.PP
The balance command can produce several styles of report:
.SS Classic balance report
.PP
This is the original balance report, as found in Ledger.
It usually looks like this:
.IP
.nf
\f[C]
@ -1571,12 +1598,6 @@ $\ hledger\ balance
\f[]
.fi
.PP
More precisely, the balance command shows the \f[I]change\f[] to each
account's balance caused by all (matched) postings.
In the common case where you do not filter by date and your journal sets
the correct opening balances, this is the same as the account's ending
balance.
.PP
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,
@ -1586,8 +1607,7 @@ Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount.
\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more
compact output.
(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to
prevent this.
Use \f[C]\-\-no\-elide\f[] to prevent this.
.PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts.
@ -1597,7 +1617,7 @@ omitted.
Use \f[C]\-E/\-\-empty\f[] to show them.
.PP
A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to
suppress it:
suppress it, eg:
.IP
.nf
\f[C]
@ -1607,11 +1627,89 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
\f[]
.fi
.SS Customising the classic balance report
.PP
You can customise the layout of classic balance reports with
\f[C]\-\-format\ FMT\f[]:
.IP
.nf
\f[C]
$\ 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
\f[]
.fi
.PP
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:
.PP
\f[C]%[MIN][.MAX](FIELDNAME)\f[]
.IP \[bu] 2
MIN pads with spaces to at least this width (optional)
.IP \[bu] 2
MAX truncates at this width (optional)
.IP \[bu] 2
FIELDNAME must be enclosed in parentheses, and can be one of:
.RS 2
.IP \[bu] 2
\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
depth, or if MIN is specified, MIN * depth spaces.
.IP \[bu] 2
\f[C]account\f[] \- the account's name
.IP \[bu] 2
\f[C]total\f[] \- the account's balance/posted total, right justified
.RE
.PP
Also, FMT can begin with an optional prefix to control how
multi\-commodity amounts are rendered:
.IP \[bu] 2
\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
.IP \[bu] 2
\f[C]%^\f[] \- render on multiple lines, top\-aligned
.IP \[bu] 2
\f[C]%,\f[] \- render on one line, comma\-separated
.PP
There are some quirks.
Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
\f[C]%(account)\f[] has indentation built in.
Experimentation may be needed to get pleasing results.
.PP
Some example formats:
.IP \[bu] 2
\f[C]%(total)\f[] \- the account's total
.IP \[bu] 2
\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
to 20 characters and clipped at 20 characters
.IP \[bu] 2
\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
characters, total padded to 20 characters, with multiple commodities
rendered on one line
.IP \[bu] 2
\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
format for the single\-column balance report
.SS Colour support
.PP
The balance command shows negative amounts in red, if:
.IP \[bu] 2
the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
.IP \[bu] 2
the output is not being redirected or piped anywhere
.SS Flat mode
.PP
To see a flat list of full account names instead of the default
hierarchical display, use \f[C]\-\-flat\f[].
In this mode, accounts (unless depth\-clipped) show their
To see a flat list instead of the default hierarchical display, use
\f[C]\-\-flat\f[].
In this mode, accounts (unless depth\-clipped) show their full names and
\[lq]exclusive\[rq] balance, excluding any subaccount balances.
In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first
few account name components.
@ -1625,26 +1723,32 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1
.fi
.SS Depth limited balance reports
.PP
With \f[C]\-\-depth\ N\f[], balance shows accounts only to the specified
depth.
This is very useful to show a complex charts of accounts in less detail.
In flat mode, balances from accounts below the depth limit will be shown
as part of a parent account at the depth limit.
With \f[C]\-\-depth\ N\f[] or \f[C]depth:N\f[] or just \f[C]\-N\f[],
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.
.IP
.nf
\f[C]
$\ hledger\ balance\ \-N\ \-\-depth\ 1
$\ hledger\ balance\ \-N\ \-1
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities
\f[]
.fi
.SS Multicolumn balance reports
.PP
With a reporting interval, multiple balance columns will be shown, one
for each report period.
There are three types of multi\-column balance report, showing different
Flat\-mode balance reports, which normally show exclusive balances, show
inclusive balances at the depth limit.
.SS Multicolumn balance report
.PP
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.
.PP
There are three types of multicolumn balance report, showing different
information:
.IP "1." 3
By default: each column shows the sum of postings in that period, ie the
@ -1716,8 +1820,8 @@ Ending\ balances\ (historical)\ in\ 2008/04/01\-2008/12/31:
.fi
.RE
.PP
Multi\-column balance reports display accounts in flat mode by default;
to see the hierarchy, use \f[C]\-\-tree\f[].
Multicolumn balance reports display accounts in flat mode by default; to
see the hierarchy, use \f[C]\-\-tree\f[].
.PP
With a reporting interval (like \f[C]\-\-quarterly\f[] above), the
report start/end dates will be adjusted if necessary so that they
@ -1762,17 +1866,22 @@ Balance\ changes\ in\ 2008:
\f[]
.fi
.PP
The \f[C]\-V/\-\-value\f[] flag currently has a limitation with
multicolumn reports: it uses the market prices on the report end date
for all columns.
(Instead of the prices on each column's end date.)
.SS Budgets
Limitations:
.PP
With \f[C]\-\-budget\f[] and a report interval, all periodic
transactions in your journal with that interval, active during the
requested report period, are interpreted as recurring budget goals for
the specified accounts (and subaccounts), and the report will show the
difference between actual and budgeted balances.
In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market
price on the report end date, for all columns (not the price on each
column's end date).
.PP
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
.SS Budget report
.PP
With \f[C]\-\-budget\f[], 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.
\[en]budget is most often combined with a report interval.
.PP
For example, you can take average monthly expenses in the common expense
categories to construct a minimal monthly budget:
@ -1805,156 +1914,61 @@ categories to construct a minimal monthly budget:
\f[]
.fi
.PP
You can now see a monthly budget performance report:
You can now see a monthly budget report:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-M\ \-\-budget
Balance\ changes\ in\ 2017/11/01\-2017/12/31:
Budget\ performance\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
=======================++=================================================
\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
\ 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\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
======================++=================================================
\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
\ 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\
\f[]
.fi
.PP
By default, only accounts with budget goals during the report period are
shown.
\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well.
Top\-level accounts with no budget goals anywhere below them are grouped
under \f[C]<unbudgeted>\f[].
.PP
You can roll over unspent budgets to next period with
\f[C]\-\-cumulative\f[]:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
Budget\ performance\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
=======================++=================================================
\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
\ 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
\f[]
.fi
.PP
Accounts with no budget goals (not mentioned in the periodic
transactions) will be aggregated under \f[C]<unbudgeted>\f[], unless you
add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted
Balance\ changes\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
======================++=================================================
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
\ 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]\
\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
\ 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
\f[]
.fi
.PP
Note \[en]budget first arrived in hledger in 1.5 and is still pretty
young; join the discussions on mail list and issue tracker to help us
refine it.
Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported
with \f[C]\-\-budget\f[].
.PP
For more examples, see Budgeting and Forecasting.
.SS Custom balance output
.SS Output format
.PP
You can customise the layout of simple (non\-tabular) balance reports
with \f[C]\-\-format\ FMT\f[]:
.IP
.nf
\f[C]
$\ 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
\f[]
.fi
.PP
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:
.PP
\f[C]%[MIN][.MAX](FIELDNAME)\f[]
.IP \[bu] 2
MIN pads with spaces to at least this width (optional)
.IP \[bu] 2
MAX truncates at this width (optional)
.IP \[bu] 2
FIELDNAME must be enclosed in parentheses, and can be one of:
.RS 2
.IP \[bu] 2
\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
depth, or if MIN is specified, MIN * depth spaces.
.IP \[bu] 2
\f[C]account\f[] \- the account's name
.IP \[bu] 2
\f[C]total\f[] \- the account's balance/posted total, right justified
.RE
.PP
Also, FMT can begin with an optional prefix to control how
multi\-commodity amounts are rendered:
.IP \[bu] 2
\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
.IP \[bu] 2
\f[C]%^\f[] \- render on multiple lines, top\-aligned
.IP \[bu] 2
\f[C]%,\f[] \- render on one line, comma\-separated
.PP
There are some quirks.
Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
\f[C]%(account)\f[] has indentation built in.
Experimentation may be needed to get pleasing results.
.PP
Some example formats:
.IP \[bu] 2
\f[C]%(total)\f[] \- the account's total
.IP \[bu] 2
\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
to 20 characters and clipped at 20 characters
.IP \[bu] 2
\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
characters, total padded to 20 characters, with multiple commodities
rendered on one line
.IP \[bu] 2
\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
format for the single\-column balance report
.PP
This command also supports output destination and output format
The balance command supports output destination and output format
selection.
.SS Colour support
.PP
The balance command shows negative amounts in red, if:
.IP \[bu] 2
the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
.IP \[bu] 2
the output is not being redirected or piped anywhere
.SS balancesheet
.PP
This command displays a simple balance sheet, showing historical ending

751
hledger/hledger.info
View File

@ -685,9 +685,9 @@ $ hledger -f t.j bal -N euros -V
Currently, hledger's -V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
Currently, the -V has a limitation with in multicolumn balance
reports: it uses the market prices on the report end date for all
columns. (Instead of the prices on each column's end date.)
Currently, -V has a limitation in multicolumn balance reports: it
uses the market prices on the report end date for all columns. (Instead
of the prices on each column's end date.)

File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS
@ -1150,8 +1150,46 @@ Show accounts and their balances. Aliases: b, bal.
with -budget, show unbudgeted accounts also
The balance command displays accounts and balances. It is hledger's
most featureful and versatile command.
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:
* Menu:
* Classic balance report::
* Customising the classic balance report::
* Colour support::
* Flat mode::
* Depth limited balance reports::
* Multicolumn balance report::
* Budget report::
* Output format::

File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance
4.4.1 Classic balance report
----------------------------
This is the original balance report, as found in Ledger. It usually
looks like this:
$ hledger balance
$-1 assets
@ -1167,11 +1205,6 @@ $ hledger balance
--------------------
0
More precisely, the balance command shows the _change_ to each
account's balance caused by all (matched) postings. In the common case
where you do not filter by date and your journal sets the correct
opening balances, this is the same as the account's ending balance.
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
@ -1179,8 +1212,7 @@ sorted by account code if any, then by account name. Or with
"Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more
compact output. (Not yet supported in tabular reports.) Use
'--no-elide' to prevent this.
compact output. Use '--no-elide' to prevent this.
Account balances are "inclusive" - they include the balances of any
subaccounts.
@ -1189,263 +1221,21 @@ subaccounts.
omitted. Use '-E/--empty' to show them.
A final total is displayed by default; use '-N/--no-total' to
suppress it:
suppress it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
* Menu:
* Flat mode::
* Depth limited balance reports::
* Multicolumn balance reports::
* Budgets::
* Custom balance output::
* Colour support::

File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance
File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance
4.4.1 Flat mode
---------------
4.4.2 Customising the classic balance report
--------------------------------------------
To see a flat list of full account names instead of the default
hierarchical display, use '--flat'. In this mode, accounts (unless
depth-clipped) show their "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

File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance
4.4.2 Depth limited balance reports
-----------------------------------
With '--depth N', balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less detail.
In flat mode, balances from accounts below the depth limit will be shown
as part of a parent account at the depth limit.
$ hledger balance -N --depth 1
$-1 assets
$2 expenses
$-2 income
$1 liabilities

File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance
4.4.3 Multicolumn balance reports
---------------------------------
With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column 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
Multi-column 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
The '-V/--value' flag currently has a limitation with multicolumn
reports: it uses the market prices on the report end date for all
columns. (Instead of the prices on each column's end date.)

File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance
4.4.4 Budgets
-------------
With '--budget' and a report interval, all periodic transactions in your
journal with that interval, active during the requested report period,
are interpreted as recurring budget goals for the specified accounts
(and subaccounts), and the report will show the difference between
actual and budgeted balances.
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 performance report:
$ hledger balance -M --budget
Balance changes in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
=======================++=================================================
<unbudgeted>:expenses || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
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
You can roll over unspent budgets to next period with '--cumulative':
$ hledger balance -M --budget --cumulative
Ending balances (cumulative) in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31
=======================++=================================================
<unbudgeted>:expenses || $20 $120
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
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
Accounts with no budget goals (not mentioned in the periodic
transactions) will be aggregated under '<unbudgeted>', unless you add
the '--show-unbudgeted' flag to display them normally:
$ hledger balance --budget --show-unbudgeted
Balance changes in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
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
Note -budget first arrived in hledger in 1.5 and is still pretty
young; join the discussions on mail list and issue tracker to help us
refine it.
For more examples, see Budgeting and Forecasting.

File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance
4.4.5 Custom balance output
---------------------------
You can customise the layout of simple (non-tabular) balance reports
with '--format FMT':
You can customise the layout of classic balance reports with '--format
FMT':
$ hledger balance --format "%20(account) %12(total)"
assets $-1
@ -1498,13 +1288,10 @@ may be needed to get pleasing results.
* '%20(total) %2(depth_spacer)%-(account)' - the default format for
the single-column balance report
This command also supports output destination and output format
selection.

File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance
File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance
4.4.6 Colour support
4.4.3 Colour support
--------------------
The balance command shows negative amounts in red, if:
@ -1512,6 +1299,241 @@ 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

File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance
4.4.4 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

File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance report, Prev: Flat mode, Up: balance
4.4.5 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.

File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance
4.4.6 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
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
Limitations:
In multicolumn reports the '-V/--value' flag uses the market price on
the report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.

File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance
4.4.7 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:
|| 2017/11 2017/12
======================++=================================================
<unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
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
By default, only accounts with budget goals during the report period
are shown. '--show-unbudgeted' shows unbudgeted accounts as well.
Top-level accounts with no budget goals anywhere below them are grouped
under '<unbudgeted>'.
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:
|| 2017/11/30 2017/12/31
======================++=================================================
<unbudgeted> || $20 $120
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
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
Note, the '-S/--sort-amount' flag is not yet fully supported with
'--budget'.
For more examples, see Budgeting and Forecasting.
4.4.8 Output format
-------------------
The balance command supports output destination and output format
selection.

File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
@ -2441,103 +2463,106 @@ Node: Cost21487
Ref: #cost21595
Node: Market value21713
Ref: #market-value21848
Node: Combining -B and -V23224
Ref: #combining--b-and--v23387
Node: Output destination23534
Ref: #output-destination23696
Node: Output format23979
Ref: #output-format24131
Node: Regular expressions24516
Ref: #regular-expressions24653
Node: QUERIES26014
Ref: #queries26116
Node: COMMANDS30078
Ref: #commands30190
Node: accounts31172
Ref: #accounts31270
Node: activity32516
Ref: #activity32626
Node: add32986
Ref: #add33085
Node: balance35746
Ref: #balance35857
Node: Flat mode39361
Ref: #flat-mode39486
Node: Depth limited balance reports39906
Ref: #depth-limited-balance-reports40107
Node: Multicolumn balance reports40527
Ref: #multicolumn-balance-reports40722
Node: Budgets45608
Ref: #budgets45755
Node: Custom balance output49724
Ref: #custom-balance-output49886
Node: Colour support52052
Ref: #colour-support52184
Node: balancesheet52357
Ref: #balancesheet52493
Node: balancesheetequity54804
Ref: #balancesheetequity54953
Node: cashflow55490
Ref: #cashflow55618
Node: check-dates57741
Ref: #check-dates57868
Node: check-dupes57985
Ref: #check-dupes58109
Node: close58246
Ref: #close58353
Node: help58683
Ref: #help58783
Node: import59857
Ref: #import59971
Node: incomestatement60701
Ref: #incomestatement60835
Node: prices63239
Ref: #prices63354
Node: print63397
Ref: #print63507
Node: print-unique68401
Ref: #print-unique68527
Node: register68595
Ref: #register68722
Node: Custom register output73223
Ref: #custom-register-output73352
Node: register-match74582
Ref: #register-match74716
Node: rewrite74899
Ref: #rewrite75016
Node: stats75085
Ref: #stats75188
Node: tags76058
Ref: #tags76156
Node: test76392
Ref: #test76476
Node: ADD-ON COMMANDS76844
Ref: #add-on-commands76954
Node: Official add-ons78241
Ref: #official-add-ons78381
Node: api78468
Ref: #api78557
Node: ui78609
Ref: #ui78708
Node: web78766
Ref: #web78855
Node: Third party add-ons78901
Ref: #third-party-add-ons79076
Node: diff79211
Ref: #diff79308
Node: iadd79407
Ref: #iadd79521
Node: interest79604
Ref: #interest79725
Node: irr79820
Ref: #irr79918
Node: Experimental add-ons79996
Ref: #experimental-add-ons80148
Node: autosync80428
Ref: #autosync80539
Node: chart80778
Ref: #chart80897
Node: check80968
Ref: #check81070
Node: Combining -B and -V23215
Ref: #combining--b-and--v23378
Node: Output destination23525
Ref: #output-destination23687
Node: Output format23970
Ref: #output-format24122
Node: Regular expressions24507
Ref: #regular-expressions24644
Node: QUERIES26005
Ref: #queries26107
Node: COMMANDS30069
Ref: #commands30181
Node: accounts31163
Ref: #accounts31261
Node: activity32507
Ref: #activity32617
Node: add32977
Ref: #add33076
Node: balance35737
Ref: #balance35848
Node: Classic balance report38931
Ref: #classic-balance-report39104
Node: Customising the classic balance report40433
Ref: #customising-the-classic-balance-report40661
Node: Colour support42735
Ref: #colour-support42902
Node: Flat mode43075
Ref: #flat-mode43223
Node: Depth limited balance reports43636
Ref: #depth-limited-balance-reports43836
Node: Multicolumn balance report44292
Ref: #multicolumn-balance-report44490
Node: Budget report49670
Ref: #budget-report49813
Ref: #output-format-152847
Node: balancesheet52925
Ref: #balancesheet53061
Node: balancesheetequity55372
Ref: #balancesheetequity55521
Node: cashflow56058
Ref: #cashflow56186
Node: check-dates58309
Ref: #check-dates58436
Node: check-dupes58553
Ref: #check-dupes58677
Node: close58814
Ref: #close58921
Node: help59251
Ref: #help59351
Node: import60425
Ref: #import60539
Node: incomestatement61269
Ref: #incomestatement61403
Node: prices63807
Ref: #prices63922
Node: print63965
Ref: #print64075
Node: print-unique68969
Ref: #print-unique69095
Node: register69163
Ref: #register69290
Node: Custom register output73791
Ref: #custom-register-output73920
Node: register-match75150
Ref: #register-match75284
Node: rewrite75467
Ref: #rewrite75584
Node: stats75653
Ref: #stats75756
Node: tags76626
Ref: #tags76724
Node: test76960
Ref: #test77044
Node: ADD-ON COMMANDS77412
Ref: #add-on-commands77522
Node: Official add-ons78809
Ref: #official-add-ons78949
Node: api79036
Ref: #api79125
Node: ui79177
Ref: #ui79276
Node: web79334
Ref: #web79423
Node: Third party add-ons79469
Ref: #third-party-add-ons79644
Node: diff79779
Ref: #diff79876
Node: iadd79975
Ref: #iadd80089
Node: interest80172
Ref: #interest80293
Node: irr80388
Ref: #irr80486
Node: Experimental add-ons80564
Ref: #experimental-add-ons80716
Node: autosync80996
Ref: #autosync81107
Node: chart81346
Ref: #chart81465
Node: check81536
Ref: #check81638

End Tag Table

487
hledger/hledger.txt
View File

@ -651,9 +651,9 @@ OPTIONS
Currently, hledger's -V only uses market prices recorded with P direc-
tives, not transaction prices (unlike Ledger).
Currently, the -V has a limitation with in multicolumn balance reports:
it uses the market prices on the report end date for all columns.
(Instead of the prices on each column's end date.)
Currently, -V has a limitation in multicolumn balance reports: it uses
the market prices on the report end date for all columns. (Instead of
the prices on each column's end date.)
Combining -B and -V
Using -B/-cost and -V/-value together is currently allowed, but the
@ -1052,8 +1052,31 @@ COMMANDS
--show-unbudgeted
with -budget, show unbudgeted accounts also
The balance command displays accounts and balances. It is hledger's
most featureful and versatile command.
The balance command is hledger's most versatile command. Note, despite
the name, it is not always used for showing real-world account bal-
ances; 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 bal-
ance during the entire period of the journal. Balance changes are cal-
culated 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 bal-
ance. For a real-world account, typically you won't have all transac-
tions in the journal; instead you'll have all transactions after a cer-
tain 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
@ -1069,20 +1092,14 @@ COMMANDS
--------------------
0
More precisely, the balance command shows the change to each account's
balance caused by all (matched) postings. In the common case where you
do not filter by date and your journal sets the correct opening bal-
ances, this is the same as the account's ending balance.
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
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.
"Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com-
pact output. (Not yet supported in tabular reports.) Use --no-elide to
prevent this.
balance of their own, are elided into the following line for more com-
pact output. Use --no-elide to prevent this.
Account balances are "inclusive" - they include the balances of any
subaccounts.
@ -1091,229 +1108,16 @@ COMMANDS
omitted. Use -E/--empty to show them.
A final total is displayed by default; use -N/--no-total to suppress
it:
it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
Flat mode
To see a flat list of full account names instead of the default hierar-
chical display, use --flat. In this mode, accounts (unless
depth-clipped) show their "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, balance shows accounts only to the specified depth.
This is very useful to show a complex charts of accounts in less
detail. In flat mode, balances from accounts below the depth limit
will be shown as part of a parent account at the depth limit.
$ hledger balance -N --depth 1
$-1 assets
$2 expenses
$-2 income
$1 liabilities
Multicolumn balance reports
With a reporting interval, multiple balance columns will be shown, one
for each report period. There are three types of multi-column 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
Multi-column 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 peri-
ods 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 oth-
erwise 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
The -V/--value flag currently has a limitation with multicolumn
reports: it uses the market prices on the report end date for all col-
umns. (Instead of the prices on each column's end date.)
Budgets
With --budget and a report interval, all periodic transactions in your
journal with that interval, active during the requested report period,
are interpreted as recurring budget goals for the specified accounts
(and subaccounts), and the report will show the difference between
actual and budgeted balances.
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 performance report:
$ hledger balance -M --budget
Balance changes in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
=======================++=================================================
<unbudgeted>:expenses || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
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
You can roll over unspent budgets to next period with --cumulative:
$ hledger balance -M --budget --cumulative
Ending balances (cumulative) in 2017/11/01-2017/12/31:
|| 2017/11/30 2017/12/31
=======================++=================================================
<unbudgeted>:expenses || $20 $120
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
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
Accounts with no budget goals (not mentioned in the periodic transac-
tions) will be aggregated under <unbudgeted>, unless you add the
--show-unbudgeted flag to display them normally:
$ hledger balance --budget --show-unbudgeted
Balance changes in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
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
Note -budget first arrived in hledger in 1.5 and is still pretty young;
join the discussions on mail list and issue tracker to help us refine
it.
For more examples, see Budgeting and Forecasting.
Custom balance output
You can customise the layout of simple (non-tabular) balance reports
with --format FMT:
Customising the classic balance report
You can customise the layout of classic balance reports with --for-
mat FMT:
$ hledger balance --format "%20(account) %12(total)"
assets $-1
@ -1375,9 +1179,6 @@ COMMANDS
o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report
This command also supports output destination and output format selec-
tion.
Colour support
The balance command shows negative amounts in red, if:
@ -1385,6 +1186,220 @@ COMMANDS
o 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.
Multicolumn balance report
Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent-
ing 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
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 peri-
ods 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 oth-
erwise 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
Limitations:
In multicolumn reports the -V/--value flag uses the market price on the
report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic bal-
ance report, is not yet supported in multicolumn reports.
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:
|| 2017/11 2017/12
======================++=================================================
<unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
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
By default, only accounts with budget goals during the report period
are shown. --show-unbudgeted shows unbudgeted accounts as well.
Top-level accounts with no budget goals anywhere below them are grouped
under <unbudgeted>.
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:
|| 2017/11/30 2017/12/31
======================++=================================================
<unbudgeted> || $20 $120
assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
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
Note, the -S/--sort-amount flag is not yet fully supported with --bud-
get.
For more examples, see Budgeting and Forecasting.
Output format
The balance command supports output destination and output format
selection.
balancesheet
This command displays a simple balance sheet, showing historical ending
balances of asset and liability accounts (ignoring any report begin