slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages 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. See comments.
.SS commodity directive .SS commodity directive
.PP .PP
The \f[C]commodity\f[] directive predefines commodities (currently this The \f[C]commodity\f[] directive declares commodities which may be used
is just informational), and also it may define the display format for in the journal (though currently we do not enforce this).
amounts in this commodity (overriding the automatically inferred
format).
.PP
It may be written on a single line, like this: It may be written on a single line, like this:
.IP .IP
.nf .nf
@ -1095,6 +1092,15 @@ commodity\ INR
\ \ format\ INR\ 9,99,99,999.00 \ \ format\ INR\ 9,99,99,999.00
\f[] \f[]
.fi .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 .SS Default commodity
.PP .PP
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity (and display format), to be
@ -1114,6 +1120,9 @@ D\ $1,000.00
\ \ b \ \ b
\f[] \f[]
.fi .fi
.PP
As with the \f[C]commodity\f[] directive, the amount must always be
written with a decimal point.
.SS Default year .SS Default year
.PP .PP
You can set a default year to be used for subsequent dates which don't 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 1.14.5 commodity directive
-------------------------- --------------------------
The 'commodity' directive predefines commodities (currently this is just The 'commodity' directive declares commodities which may be used in the
informational), and also it may define the display format for amounts in journal (though currently we do not enforce this). It may be written on
this commodity (overriding the automatically inferred format). a single line, like this:
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -1023,6 +1021,14 @@ places:
commodity INR commodity INR
format INR 9,99,99,999.00 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 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 a 5 ; <- commodity-less amount, becomes $1
b 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 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 Ref: #multi-line-comments35358
Node: commodity directive35486 Node: commodity directive35486
Ref: #commodity-directive35670 Ref: #commodity-directive35670
Node: Default commodity36542 Node: Default commodity36897
Ref: #default-commodity36715 Ref: #default-commodity37070
Node: Default year37252 Node: Default year37702
Ref: #default-year37417 Ref: #default-year37867
Node: Including other files37840 Node: Including other files38290
Ref: #including-other-files37997 Ref: #including-other-files38447
Node: Periodic transactions38394 Node: Periodic transactions38844
Ref: #periodic-transactions38560 Ref: #periodic-transactions39010
Node: Automated postings39549 Node: Automated postings39999
Ref: #automated-postings39712 Ref: #automated-postings40162
Node: EDITOR SUPPORT40840 Node: EDITOR SUPPORT41290
Ref: #editor-support40965 Ref: #editor-support41415
 
End Tag Table 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. containing just end comment ends it. See comments.
commodity directive commodity directive
The commodity directive predefines commodities (currently this is just The commodity directive declares commodities which may be used in the
informational), and also it may define the display format for amounts journal (though currently we do not enforce this). It may be written
in this commodity (overriding the automatically inferred format). on a single line, like this:
It may be written on a single line, like this:
; commodity EXAMPLEAMOUNT ; commodity EXAMPLEAMOUNT
@ -796,6 +794,14 @@ FILE FORMAT
commodity INR commodity INR
format INR 9,99,99,999.00 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 Default commodity
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note used for amounts without a commodity symbol (ie, plain numbers). (Note
@ -811,9 +817,12 @@ FILE FORMAT
a 5 ; <- commodity-less amount, becomes $1 a 5 ; <- commodity-less amount, becomes $1
b b
As with the commodity directive, the amount must always be written with
a decimal point.
Default year Default year
You can set a default year to be used for subsequent dates which don't 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. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -833,58 +842,58 @@ FILE FORMAT
assets assets
Including other files 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 directive, like this:
include path/to/file.journal 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. 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. include journal, timeclock or timedot files, but not CSV files.
Periodic transactions Periodic transactions
Periodic transactions are a kind of rule with a dual purpose: they can Periodic transactions are a kind of rule with a dual purpose: they can
specify recurring future transactions (with --forecast), or budget specify recurring future transactions (with --forecast), or budget
goals (with --budget). They look a bit like a transaction, except the goals (with --budget). They look a bit like a transaction, except the
first line is a tilde (~) followed by a period expression: first line is a tilde (~) followed by a period expression:
~ weekly ~ weekly
assets:bank:checking $400 ; paycheck assets:bank:checking $400 ; paycheck
income:acme inc income:acme inc
With --forecast, each periodic transaction rule generates recurring With --forecast, each periodic transaction rule generates recurring
"forecast" transactions at the specified interval, beginning the day "forecast" transactions at the specified interval, beginning the day
after the latest recorded journal transaction (or today, if there are after the latest recorded journal transaction (or today, if there are
no transactions) and ending 6 months from today (or at the report end no transactions) and ending 6 months from today (or at the report end
date, if specified). 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 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. $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. ing.
Automated postings Automated postings
Automated postings are postings added automatically by rule to certain Automated postings are postings added automatically by rule to certain
transactions (with --auto). An automated posting rule looks like a transactions (with --auto). An automated posting rule looks like a
transaction where the first line is an equal sign (=) followed by a transaction where the first line is an equal sign (=) followed by a
query: query:
= expenses:gifts = expenses:gifts
budget:gifts *-1 budget:gifts *-1
assets:budget *1 assets:budget *1
The posting amounts can be of the form *N, which means "the amount of 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 matched transaction's first posting, multiplied by N". They can
also be ordinary fixed amounts. Fixed amounts with no commodity symbol 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. 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: transaction involving the expenses:gifts account:
= expenses:gifts = expenses:gifts
@ -900,18 +909,18 @@ Automated postings
(budget:gifts) $-20 (budget:gifts) $-20
assets assets
Automated postings would not be distinguishable from equivalent post- Automated postings would not be distinguishable from equivalent post-
ings written by hand. In particular, they would affect [amount infer- ings written by hand. In particular, they would affect [amount infer-
ence|#postings] and [balance assertion|#balance-assertions] checks in ence|#postings] and [balance assertion|#balance-assertions] checks in
the usual way. the usual way.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. 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: files:
@ -930,7 +939,7 @@ EDITOR SUPPORT
REPORTING BUGS 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) or hledger mail list)
@ -944,7 +953,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) 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 Currently, hledger's \-V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger). directives, not transaction prices (unlike Ledger).
.PP .PP
Currently, the \-V has a limitation with in multicolumn balance reports: Currently, \-V has a limitation in multicolumn balance reports: it uses
it uses the market prices on the report end date for all columns. the market prices on the report end date for all columns.
(Instead of the prices on each column's end date.) (Instead of the prices on each column's end date.)
.SS Combining \-B and \-V .SS Combining \-B and \-V
.PP .PP
@ -1550,8 +1550,35 @@ with \[en]budget, show unbudgeted accounts also
.RS .RS
.RE .RE
.PP .PP
The balance command displays accounts and balances. The balance command is hledger's most versatile command.
It is hledger's most featureful and 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 .IP
.nf .nf
\f[C] \f[C]
@ -1571,12 +1598,6 @@ $\ hledger\ balance
\f[] \f[]
.fi .fi
.PP .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 By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. indented below their parent.
At each level of the tree, accounts are sorted by account code if any, 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 \[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more and no balance of their own, are elided into the following line for more
compact output. compact output.
(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to Use \f[C]\-\-no\-elide\f[] to prevent this.
prevent this.
.PP .PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts. any subaccounts.
@ -1597,7 +1617,7 @@ omitted.
Use \f[C]\-E/\-\-empty\f[] to show them. Use \f[C]\-E/\-\-empty\f[] to show them.
.PP .PP
A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to
suppress it: suppress it, eg:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1607,11 +1627,89 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
\f[] \f[]
.fi .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 .SS Flat mode
.PP .PP
To see a flat list of full account names instead of the default To see a flat list instead of the default hierarchical display, use
hierarchical display, use \f[C]\-\-flat\f[]. \f[C]\-\-flat\f[].
In this mode, accounts (unless depth\-clipped) show their In this mode, accounts (unless depth\-clipped) show their full names and
\[lq]exclusive\[rq] balance, excluding any subaccount balances. \[lq]exclusive\[rq] balance, excluding any subaccount balances.
In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first
few account name components. few account name components.
@ -1625,26 +1723,32 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1
.fi .fi
.SS Depth limited balance reports .SS Depth limited balance reports
.PP .PP
With \f[C]\-\-depth\ N\f[], balance shows accounts only to the specified With \f[C]\-\-depth\ N\f[] or \f[C]depth:N\f[] or just \f[C]\-N\f[],
depth. balance reports show accounts only to the specified numeric depth.
This is very useful to show a complex charts of accounts in less detail. This is very useful to summarise a complex set of accounts and get an
In flat mode, balances from accounts below the depth limit will be shown overview.
as part of a parent account at the depth limit.
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ balance\ \-N\ \-\-depth\ 1 $\ hledger\ balance\ \-N\ \-1
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities
\f[] \f[]
.fi .fi
.SS Multicolumn balance reports
.PP .PP
With a reporting interval, multiple balance columns will be shown, one Flat\-mode balance reports, which normally show exclusive balances, show
for each report period. inclusive balances at the depth limit.
There are three types of multi\-column balance report, showing different .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: information:
.IP "1." 3 .IP "1." 3
By default: each column shows the sum of postings in that period, ie the 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 .fi
.RE .RE
.PP .PP
Multi\-column balance reports display accounts in flat mode by default; Multicolumn balance reports display accounts in flat mode by default; to
to see the hierarchy, use \f[C]\-\-tree\f[]. see the hierarchy, use \f[C]\-\-tree\f[].
.PP .PP
With a reporting interval (like \f[C]\-\-quarterly\f[] above), the With a reporting interval (like \f[C]\-\-quarterly\f[] above), the
report start/end dates will be adjusted if necessary so that they report start/end dates will be adjusted if necessary so that they
@ -1762,17 +1866,22 @@ Balance\ changes\ in\ 2008:
\f[] \f[]
.fi .fi
.PP .PP
The \f[C]\-V/\-\-value\f[] flag currently has a limitation with Limitations:
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
.PP .PP
With \f[C]\-\-budget\f[] and a report interval, all periodic In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market
transactions in your journal with that interval, active during the price on the report end date, for all columns (not the price on each
requested report period, are interpreted as recurring budget goals for column's end date).
the specified accounts (and subaccounts), and the report will show the .PP
difference between actual and budgeted balances. 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 .PP
For example, you can take average monthly expenses in the common expense For example, you can take average monthly expenses in the common expense
categories to construct a minimal monthly budget: categories to construct a minimal monthly budget:
@ -1805,156 +1914,61 @@ categories to construct a minimal monthly budget:
\f[] \f[]
.fi .fi
.PP .PP
You can now see a monthly budget performance report: You can now see a monthly budget report:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ balance\ \-M\ \-\-budget $\ 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\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
=======================++================================================= ======================++=================================================
\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ \ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ \ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ \ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ \ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ \ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ \ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
\f[] \f[]
.fi .fi
.PP .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 You can roll over unspent budgets to next period with
\f[C]\-\-cumulative\f[]: \f[C]\-\-cumulative\f[]:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative $\ 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\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 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\
======================++================================================= ======================++=================================================
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ \ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ \ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ \ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ \ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ \ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
\f[] \f[]
.fi .fi
.PP .PP
Note \[en]budget first arrived in hledger in 1.5 and is still pretty Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported
young; join the discussions on mail list and issue tracker to help us with \f[C]\-\-budget\f[].
refine it.
.PP .PP
For more examples, see Budgeting and Forecasting. For more examples, see Budgeting and Forecasting.
.SS Custom balance output .SS Output format
.PP .PP
You can customise the layout of simple (non\-tabular) balance reports The balance command supports output destination and output format
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
selection. 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 .SS balancesheet
.PP .PP
This command displays a simple balance sheet, showing historical ending 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 Currently, hledger's -V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger). directives, not transaction prices (unlike Ledger).
Currently, the -V has a limitation with in multicolumn balance Currently, -V has a limitation in multicolumn balance reports: it
reports: it uses the market prices on the report end date for all uses the market prices on the report end date for all columns. (Instead
columns. (Instead of the prices on each column's end date.) 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 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 with -budget, show unbudgeted accounts also
The balance command displays accounts and balances. It is hledger's The balance command is hledger's most versatile command. Note,
most featureful and versatile command. 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 $ hledger balance
$-1 assets $-1 assets
@ -1167,11 +1205,6 @@ $ hledger balance
-------------------- --------------------
0 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 By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with 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 "Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more no balance of their own, are elided into the following line for more
compact output. (Not yet supported in tabular reports.) Use compact output. Use '--no-elide' to prevent this.
'--no-elide' to prevent this.
Account balances are "inclusive" - they include the balances of any Account balances are "inclusive" - they include the balances of any
subaccounts. subaccounts.
@ -1189,263 +1221,21 @@ subaccounts.
omitted. Use '-E/--empty' to show them. omitted. Use '-E/--empty' to show them.
A final total is displayed by default; use '-N/--no-total' to 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 $ hledger balance -p 2008/6 expenses --no-total
$2 expenses $2 expenses
$1 food $1 food
$1 supplies $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 You can customise the layout of classic balance reports with '--format
hierarchical display, use '--flat'. In this mode, accounts (unless FMT':
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':
$ hledger balance --format "%20(account) %12(total)" $ hledger balance --format "%20(account) %12(total)"
assets $-1 assets $-1
@ -1498,13 +1288,10 @@ may be needed to get pleasing results.
* '%20(total) %2(depth_spacer)%-(account)' - the default format for * '%20(total) %2(depth_spacer)%-(account)' - the default format for
the single-column balance report 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: 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 'TERM' environment variable is not set to 'dumb'
* the output is not being redirected or piped anywhere * 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 File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
@ -2441,103 +2463,106 @@ Node: Cost21487
Ref: #cost21595 Ref: #cost21595
Node: Market value21713 Node: Market value21713
Ref: #market-value21848 Ref: #market-value21848
Node: Combining -B and -V23224 Node: Combining -B and -V23215
Ref: #combining--b-and--v23387 Ref: #combining--b-and--v23378
Node: Output destination23534 Node: Output destination23525
Ref: #output-destination23696 Ref: #output-destination23687
Node: Output format23979 Node: Output format23970
Ref: #output-format24131 Ref: #output-format24122
Node: Regular expressions24516 Node: Regular expressions24507
Ref: #regular-expressions24653 Ref: #regular-expressions24644
Node: QUERIES26014 Node: QUERIES26005
Ref: #queries26116 Ref: #queries26107
Node: COMMANDS30078 Node: COMMANDS30069
Ref: #commands30190 Ref: #commands30181
Node: accounts31172 Node: accounts31163
Ref: #accounts31270 Ref: #accounts31261
Node: activity32516 Node: activity32507
Ref: #activity32626 Ref: #activity32617
Node: add32986 Node: add32977
Ref: #add33085 Ref: #add33076
Node: balance35746 Node: balance35737
Ref: #balance35857 Ref: #balance35848
Node: Flat mode39361 Node: Classic balance report38931
Ref: #flat-mode39486 Ref: #classic-balance-report39104
Node: Depth limited balance reports39906 Node: Customising the classic balance report40433
Ref: #depth-limited-balance-reports40107 Ref: #customising-the-classic-balance-report40661
Node: Multicolumn balance reports40527 Node: Colour support42735
Ref: #multicolumn-balance-reports40722 Ref: #colour-support42902
Node: Budgets45608 Node: Flat mode43075
Ref: #budgets45755 Ref: #flat-mode43223
Node: Custom balance output49724 Node: Depth limited balance reports43636
Ref: #custom-balance-output49886 Ref: #depth-limited-balance-reports43836
Node: Colour support52052 Node: Multicolumn balance report44292
Ref: #colour-support52184 Ref: #multicolumn-balance-report44490
Node: balancesheet52357 Node: Budget report49670
Ref: #balancesheet52493 Ref: #budget-report49813
Node: balancesheetequity54804 Ref: #output-format-152847
Ref: #balancesheetequity54953 Node: balancesheet52925
Node: cashflow55490 Ref: #balancesheet53061
Ref: #cashflow55618 Node: balancesheetequity55372
Node: check-dates57741 Ref: #balancesheetequity55521
Ref: #check-dates57868 Node: cashflow56058
Node: check-dupes57985 Ref: #cashflow56186
Ref: #check-dupes58109 Node: check-dates58309
Node: close58246 Ref: #check-dates58436
Ref: #close58353 Node: check-dupes58553
Node: help58683 Ref: #check-dupes58677
Ref: #help58783 Node: close58814
Node: import59857 Ref: #close58921
Ref: #import59971 Node: help59251
Node: incomestatement60701 Ref: #help59351
Ref: #incomestatement60835 Node: import60425
Node: prices63239 Ref: #import60539
Ref: #prices63354 Node: incomestatement61269
Node: print63397 Ref: #incomestatement61403
Ref: #print63507 Node: prices63807
Node: print-unique68401 Ref: #prices63922
Ref: #print-unique68527 Node: print63965
Node: register68595 Ref: #print64075
Ref: #register68722 Node: print-unique68969
Node: Custom register output73223 Ref: #print-unique69095
Ref: #custom-register-output73352 Node: register69163
Node: register-match74582 Ref: #register69290
Ref: #register-match74716 Node: Custom register output73791
Node: rewrite74899 Ref: #custom-register-output73920
Ref: #rewrite75016 Node: register-match75150
Node: stats75085 Ref: #register-match75284
Ref: #stats75188 Node: rewrite75467
Node: tags76058 Ref: #rewrite75584
Ref: #tags76156 Node: stats75653
Node: test76392 Ref: #stats75756
Ref: #test76476 Node: tags76626
Node: ADD-ON COMMANDS76844 Ref: #tags76724
Ref: #add-on-commands76954 Node: test76960
Node: Official add-ons78241 Ref: #test77044
Ref: #official-add-ons78381 Node: ADD-ON COMMANDS77412
Node: api78468 Ref: #add-on-commands77522
Ref: #api78557 Node: Official add-ons78809
Node: ui78609 Ref: #official-add-ons78949
Ref: #ui78708 Node: api79036
Node: web78766 Ref: #api79125
Ref: #web78855 Node: ui79177
Node: Third party add-ons78901 Ref: #ui79276
Ref: #third-party-add-ons79076 Node: web79334
Node: diff79211 Ref: #web79423
Ref: #diff79308 Node: Third party add-ons79469
Node: iadd79407 Ref: #third-party-add-ons79644
Ref: #iadd79521 Node: diff79779
Node: interest79604 Ref: #diff79876
Ref: #interest79725 Node: iadd79975
Node: irr79820 Ref: #iadd80089
Ref: #irr79918 Node: interest80172
Node: Experimental add-ons79996 Ref: #interest80293
Ref: #experimental-add-ons80148 Node: irr80388
Node: autosync80428 Ref: #irr80486
Ref: #autosync80539 Node: Experimental add-ons80564
Node: chart80778 Ref: #experimental-add-ons80716
Ref: #chart80897 Node: autosync80996
Node: check80968 Ref: #autosync81107
Ref: #check81070 Node: chart81346
Ref: #chart81465
Node: check81536
Ref: #check81638
 
End Tag Table 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- Currently, hledger's -V only uses market prices recorded with P direc-
tives, not transaction prices (unlike Ledger). tives, not transaction prices (unlike Ledger).
Currently, the -V has a limitation with in multicolumn balance reports: Currently, -V has a limitation in multicolumn balance reports: it uses
it uses the market prices on the report end date for all columns. the market prices on the report end date for all columns. (Instead of
(Instead of the prices on each column's end date.) the prices on each column's end date.)
Combining -B and -V Combining -B and -V
Using -B/-cost and -V/-value together is currently allowed, but the Using -B/-cost and -V/-value together is currently allowed, but the
@ -1052,8 +1052,31 @@ COMMANDS
--show-unbudgeted --show-unbudgeted
with -budget, show unbudgeted accounts also with -budget, show unbudgeted accounts also
The balance command displays accounts and balances. It is hledger's The balance command is hledger's most versatile command. Note, despite
most featureful and versatile command. 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 $ hledger balance
$-1 assets $-1 assets
@ -1069,20 +1092,14 @@ COMMANDS
-------------------- --------------------
0 0
More precisely, the balance command shows the change to each account's By default, accounts are displayed hierarchically, with subaccounts
balance caused by all (matched) postings. In the common case where you indented below their parent. At each level of the tree, accounts are
do not filter by date and your journal sets the correct opening bal- sorted by account code if any, then by account name. Or with
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
-S/--sort-amount, by their balance amount. -S/--sort-amount, by their balance amount.
"Boring" accounts, which contain a single interesting subaccount and no "Boring" accounts, which contain a single interesting subaccount and no
balance of their own, are elided into the following line for more com- 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 pact output. Use --no-elide to prevent this.
prevent this.
Account balances are "inclusive" - they include the balances of any Account balances are "inclusive" - they include the balances of any
subaccounts. subaccounts.
@ -1091,229 +1108,16 @@ COMMANDS
omitted. Use -E/--empty to show them. omitted. Use -E/--empty to show them.
A final total is displayed by default; use -N/--no-total to suppress A final total is displayed by default; use -N/--no-total to suppress
it: it, eg:
$ hledger balance -p 2008/6 expenses --no-total $ hledger balance -p 2008/6 expenses --no-total
$2 expenses $2 expenses
$1 food $1 food
$1 supplies $1 supplies
Flat mode Customising the classic balance report
To see a flat list of full account names instead of the default hierar- You can customise the layout of classic balance reports with --for-
chical display, use --flat. In this mode, accounts (unless mat FMT:
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:
$ hledger balance --format "%20(account) %12(total)" $ hledger balance --format "%20(account) %12(total)"
assets $-1 assets $-1
@ -1375,9 +1179,6 @@ COMMANDS
o %20(total) %2(depth_spacer)%-(account) - the default format for the o %20(total) %2(depth_spacer)%-(account) - the default format for the
single-column balance report single-column balance report
This command also supports output destination and output format selec-
tion.
Colour support Colour support
The balance command shows negative amounts in red, if: The balance command shows negative amounts in red, if:
@ -1385,6 +1186,220 @@ COMMANDS
o the output is not being redirected or piped anywhere 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 balancesheet
This command displays a simple balance sheet, showing historical ending This command displays a simple balance sheet, showing historical ending
balances of asset and liability accounts (ignoring any report begin balances of asset and liability accounts (ignoring any report begin