mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-19 10:17:35 +03:00
doc: regenerate embedded manuals
This commit is contained in:
parent
541e517221
commit
d7f6ff0e18
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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)
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
Loading…
Reference in New Issue
Block a user