slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-11-18 17:14:06 -08:00
parent 79ca4a767e
commit 69ee21cf16
7 changed files with 369 additions and 230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -160,6 +160,34 @@ $ hledger balance -N -1
Flat-mode balance reports, which normally show exclusive balances, show Flat-mode balance reports, which normally show exclusive balances, show
inclusive balances at the depth limit. inclusive balances at the depth limit.
Percentages
With -% or --percent, balance reports show each account's value
expressed as a percentage of the column's total. This is useful to get
an overview of the relative sizes of account balances. For example to
obtain an overview of expenses:
$ hledger balance expenses -%
100.0 % expenses
50.0 % food
50.0 % supplies
--------------------
100.0 %
Note that --tree does not have an effect on -%. The percentages are
always relative to the total sum of each column, they are never relative
to the parent account.
Since the percentages are relative to the columns sum, it is usually not
useful to calculate percentages if the signs of the amounts are mixed.
Although the results are technically correct, they are most likely
useless. Especially in a balance report that sums up to zero (eg
hledger balance -B) all percentage values will be zero.
This flag does not work if the report contains any mixed commodity
accounts. If there are mixed commodity accounts in the report be sure to
use -V or -B to coerce the report into using a single commodity.
Multicolumn balance report Multicolumn balance report
Multicolumn or tabular balance reports are a very useful hledger Multicolumn or tabular balance reports are a very useful hledger

2
hledger/Hledger/Cli/Commands/Balancesheet.txt
View File

@ -37,7 +37,7 @@ report mode with --change/--cumulative/--historical. Normally
balancesheet shows historical ending balances, which is what you need balancesheet shows historical ending balances, which is what you need
for a balance sheet; note this means it ignores report begin dates (and for a balance sheet; note this means it ignores report begin dates (and
-T/--row-total, since summing end balances generally does not make -T/--row-total, since summing end balances generally does not make
sense). sense). Instead of absolute values percentages can be displayed with -%.
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.

3
hledger/Hledger/Cli/Commands/Cashflow.txt
View File

@ -27,7 +27,8 @@ Total:
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. Normally cashflow shows changes in assets per period, report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report mode though as with multicolumn balance reports you can alter the report mode
with --change/--cumulative/--historical. with --change/--cumulative/--historical. Instead of absolute values
percentages can be displayed with -%.
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.

3
hledger/Hledger/Cli/Commands/Incomestatement.txt
View File

@ -36,7 +36,8 @@ Total:
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical. report mode with --change/--cumulative/--historical. Instead of absolute
values percentages can be displayed with -%.
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.

41
hledger/hledger.1
View File

@ -2083,6 +2083,41 @@ $ hledger balance -N -1
.PP .PP
Flat-mode balance reports, which normally show exclusive balances, show Flat-mode balance reports, which normally show exclusive balances, show
inclusive balances at the depth limit. inclusive balances at the depth limit.
.SS Percentages
.PP
With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each
account\[aq]s value expressed as a percentage of the column\[aq]s total.
This is useful to get an overview of the relative sizes of account
balances.
For example to obtain an overview of expenses:
.IP
.nf
\f[C]
$ hledger balance expenses -%
100.0 % expenses
50.0 % food
50.0 % supplies
--------------------
100.0 %
\f[R]
.fi
.PP
Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].
The percentages are always relative to the total sum of each column,
they are never relative to the parent account.
.PP
Since the percentages are relative to the columns sum, it is usually not
useful to calculate percentages if the signs of the amounts are mixed.
Although the results are technically correct, they are most likely
useless.
Especially in a balance report that sums up to zero (eg
\f[C]hledger balance -B\f[R]) all percentage values will be zero.
.PP
This flag does not work if the report contains any mixed commodity
accounts.
If there are mixed commodity accounts in the report be sure to use
\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single
commodity.
.SS Multicolumn balance report .SS Multicolumn balance report
.PP .PP
Multicolumn or tabular balance reports are a very useful hledger Multicolumn or tabular balance reports are a very useful hledger
@ -2510,6 +2545,8 @@ Normally balancesheet shows historical ending balances, which is what
you need for a balance sheet; note this means it ignores report begin you need for a balance sheet; note this means it ignores report begin
dates (and \f[C]-T/--row-total\f[R], since summing end balances dates (and \f[C]-T/--row-total\f[R], since summing end balances
generally does not make sense). generally does not make sense).
Instead of absolute values percentages can be displayed with
\f[C]-%\f[R].
.PP .PP
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.
@ -2591,6 +2628,8 @@ report period.
Normally cashflow shows changes in assets per period, though as with Normally cashflow shows changes in assets per period, though as with
multicolumn balance reports you can alter the report mode with multicolumn balance reports you can alter the report mode with
\f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R]. \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].
Instead of absolute values percentages can be displayed with
\f[C]-%\f[R].
.PP .PP
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.
@ -2942,6 +2981,8 @@ report period.
Normally incomestatement shows revenues/expenses per period, though as Normally incomestatement shows revenues/expenses per period, though as
with multicolumn balance reports you can alter the report mode with with multicolumn balance reports you can alter the report mode with
\f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R]. \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].
Instead of absolute values percentages can be displayed with
\f[C]-%\f[R].
.PP .PP
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.

260
hledger/hledger.info
View File

@ -1498,6 +1498,7 @@ is used to ensure this (more below).
* Colour support:: * Colour support::
* Flat mode:: * Flat mode::
* Depth limited balance reports:: * Depth limited balance reports::
* Percentages::
* Multicolumn balance report:: * Multicolumn balance report::
* Budget report:: * Budget report::
* Output format:: * Output format::
@ -1639,7 +1640,7 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 supplies $1 supplies
 
File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance report, Prev: Flat mode, Up: balance File: hledger.info, Node: Depth limited balance reports, Next: Percentages, Prev: Flat mode, Up: balance
4.4.5 Depth limited balance reports 4.4.5 Depth limited balance reports
----------------------------------- -----------------------------------
@ -1658,9 +1659,41 @@ $ hledger balance -N -1
show inclusive balances at the depth limit. show inclusive balances at the depth limit.
 
File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance File: hledger.info, Node: Percentages, Next: Multicolumn balance report, Prev: Depth limited balance reports, Up: balance
4.4.6 Multicolumn balance report 4.4.6 Percentages
-----------------
With '-%' or '--percent', balance reports show each account's value
expressed as a percentage of the column's total. This is useful to get
an overview of the relative sizes of account balances. For example to
obtain an overview of expenses:
$ hledger balance expenses -%
100.0 % expenses
50.0 % food
50.0 % supplies
--------------------
100.0 %
Note that '--tree' does not have an effect on '-%'. The percentages
are always relative to the total sum of each column, they are never
relative to the parent account.
Since the percentages are relative to the columns sum, it is usually
not useful to calculate percentages if the signs of the amounts are
mixed. Although the results are technically correct, they are most
likely useless. Especially in a balance report that sums up to zero (eg
'hledger balance -B') all percentage values will be zero.
This flag does not work if the report contains any mixed commodity
accounts. If there are mixed commodity accounts in the report be sure
to use '-V' or '-B' to coerce the report into using a single commodity.

File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Percentages, Up: balance
4.4.7 Multicolumn balance report
-------------------------------- --------------------------------
Multicolumn or tabular balance reports are a very useful hledger Multicolumn or tabular balance reports are a very useful hledger
@ -1777,7 +1810,7 @@ balance report, is not yet supported in multicolumn reports.
 
File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance
4.4.7 Budget report 4.4.8 Budget report
------------------- -------------------
With '--budget', extra columns are displayed showing budget goals for With '--budget', extra columns are displayed showing budget goals for
@ -1900,7 +1933,7 @@ Budget performance in 2017/11/01-2017/12/31:
 
File: hledger.info, Node: Nested budgets, Up: Budget report File: hledger.info, Node: Nested budgets, Up: Budget report
4.4.7.1 Nested budgets 4.4.8.1 Nested budgets
...................... ......................
You can add budgets to any account in your account hierarchy. If you You can add budgets to any account in your account hierarchy. If you
@ -1985,7 +2018,7 @@ Budget performance in 2019/01:
----------------------------------------++------------------------------- ----------------------------------------++-------------------------------
|| 0 [ 0] || 0 [ 0]
4.4.8 Output format 4.4.9 Output format
------------------- -------------------
The balance command supports output destination and output format The balance command supports output destination and output format
@ -2034,7 +2067,8 @@ the report mode with '--change'/'--cumulative'/'--historical'. Normally
balancesheet shows historical ending balances, which is what you need balancesheet shows historical ending balances, which is what you need
for a balance sheet; note this means it ignores report begin dates (and for a balance sheet; note this means it ignores report begin dates (and
'-T/--row-total', since summing end balances generally does not make '-T/--row-total', since summing end balances generally does not make
sense). sense). Instead of absolute values percentages can be displayed with
'-%'.
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.
@ -2108,7 +2142,8 @@ Total:
With a reporting interval, multiple columns will be shown, one for With a reporting interval, multiple columns will be shown, one for
each report period. Normally cashflow shows changes in assets per each report period. Normally cashflow shows changes in assets per
period, though as with multicolumn balance reports you can alter the period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'. report mode with '--change'/'--cumulative'/'--historical'. Instead of
absolute values percentages can be displayed with '-%'.
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.
@ -2428,7 +2463,8 @@ Total:
With a reporting interval, multiple columns will be shown, one for With a reporting interval, multiple columns will be shown, one for
each report period. Normally incomestatement shows revenues/expenses each report period. Normally incomestatement shows revenues/expenses
per period, though as with multicolumn balance reports you can alter the per period, though as with multicolumn balance reports you can alter the
report mode with '--change'/'--cumulative'/'--historical'. report mode with '--change'/'--cumulative'/'--historical'. Instead of
absolute values percentages can be displayed with '-%'.
This command also supports output destination and output format This command also supports output destination and output format
selection. selection.
@ -3222,107 +3258,109 @@ Node: add46317
Ref: #add46416 Ref: #add46416
Node: balance49161 Node: balance49161
Ref: #balance49272 Ref: #balance49272
Node: Classic balance report50714 Node: Classic balance report50730
Ref: #classic-balance-report50887 Ref: #classic-balance-report50903
Node: Customising the classic balance report52256 Node: Customising the classic balance report52272
Ref: #customising-the-classic-balance-report52484 Ref: #customising-the-classic-balance-report52500
Node: Colour support54560 Node: Colour support54576
Ref: #colour-support54727 Ref: #colour-support54743
Node: Flat mode54900 Node: Flat mode54916
Ref: #flat-mode55048 Ref: #flat-mode55064
Node: Depth limited balance reports55461 Node: Depth limited balance reports55477
Ref: #depth-limited-balance-reports55661 Ref: #depth-limited-balance-reports55662
Node: Multicolumn balance report56117 Node: Percentages56118
Ref: #multicolumn-balance-report56315 Ref: #percentages56284
Node: Budget report61629 Node: Multicolumn balance report57421
Ref: #budget-report61772 Ref: #multicolumn-balance-report57601
Node: Nested budgets66974 Node: Budget report62915
Ref: #nested-budgets67086 Ref: #budget-report63058
Ref: #output-format-170566 Node: Nested budgets68260
Node: balancesheet70644 Ref: #nested-budgets68372
Ref: #balancesheet70780 Ref: #output-format-171852
Node: balancesheetequity72095 Node: balancesheet71930
Ref: #balancesheetequity72244 Ref: #balancesheet72066
Node: cashflow72805 Node: balancesheetequity73449
Ref: #cashflow72933 Ref: #balancesheetequity73598
Node: check-dates73961 Node: cashflow74159
Ref: #check-dates74088 Ref: #cashflow74287
Node: check-dupes74367 Node: check-dates75383
Ref: #check-dupes74491 Ref: #check-dates75510
Node: close74784 Node: check-dupes75789
Ref: #close74898 Ref: #check-dupes75913
Node: commodities78485 Node: close76206
Ref: #commodities78612 Ref: #close76320
Node: descriptions78694 Node: commodities79907
Ref: #descriptions78822 Ref: #commodities80034
Node: diff79003 Node: descriptions80116
Ref: #diff79109 Ref: #descriptions80244
Node: files80156 Node: diff80425
Ref: #files80256 Ref: #diff80531
Node: help80403 Node: files81578
Ref: #help80503 Ref: #files81678
Node: import81584 Node: help81825
Ref: #import81698 Ref: #help81925
Node: Importing balance assignments82591 Node: import83006
Ref: #importing-balance-assignments82739 Ref: #import83120
Node: incomestatement83388 Node: Importing balance assignments84013
Ref: #incomestatement83521 Ref: #importing-balance-assignments84161
Node: notes84857 Node: incomestatement84810
Ref: #notes84970 Ref: #incomestatement84943
Node: payees85096 Node: notes86347
Ref: #payees85202 Ref: #notes86460
Node: prices85360 Node: payees86586
Ref: #prices85466 Ref: #payees86692
Node: print85807 Node: prices86850
Ref: #print85917 Ref: #prices86956
Node: print-unique90410 Node: print87297
Ref: #print-unique90536 Ref: #print87407
Node: register90821 Node: print-unique91900
Ref: #register90948 Ref: #print-unique92026
Node: Custom register output95120 Node: register92311
Ref: #custom-register-output95249 Ref: #register92438
Node: register-match96511 Node: Custom register output96610
Ref: #register-match96645 Ref: #custom-register-output96739
Node: rewrite96996 Node: register-match98001
Ref: #rewrite97111 Ref: #register-match98135
Node: Re-write rules in a file98966 Node: rewrite98486
Ref: #re-write-rules-in-a-file99100 Ref: #rewrite98601
Node: Diff output format100310 Node: Re-write rules in a file100456
Ref: #diff-output-format100479 Ref: #re-write-rules-in-a-file100590
Node: rewrite vs print --auto101571 Node: Diff output format101800
Ref: #rewrite-vs.-print---auto101750 Ref: #diff-output-format101969
Node: roi102306 Node: rewrite vs print --auto103061
Ref: #roi102404 Ref: #rewrite-vs.-print---auto103240
Node: stats103416 Node: roi103796
Ref: #stats103515 Ref: #roi103894
Node: tags104303 Node: stats104906
Ref: #tags104401 Ref: #stats105005
Node: test104695 Node: tags105793
Ref: #test104779 Ref: #tags105891
Node: ADD-ON COMMANDS105540 Node: test106185
Ref: #add-on-commands105650 Ref: #test106269
Node: Official add-ons106938 Node: ADD-ON COMMANDS107030
Ref: #official-add-ons107078 Ref: #add-on-commands107140
Node: ui107158 Node: Official add-ons108428
Ref: #ui107245 Ref: #official-add-ons108568
Node: web107299 Node: ui108648
Ref: #web107388 Ref: #ui108735
Node: Third party add-ons107434 Node: web108789
Ref: #third-party-add-ons107609 Ref: #web108878
Ref: #diff-1107768 Node: Third party add-ons108924
Node: iadd107867 Ref: #third-party-add-ons109099
Ref: #iadd107977 Ref: #diff-1109258
Node: interest108059 Node: iadd109357
Ref: #interest108180 Ref: #iadd109467
Node: irr108275 Node: interest109549
Ref: #irr108373 Ref: #interest109670
Node: Experimental add-ons108504 Node: irr109765
Ref: #experimental-add-ons108656 Ref: #irr109863
Node: autosync108904 Node: Experimental add-ons109994
Ref: #autosync109015 Ref: #experimental-add-ons110146
Node: chart109254 Node: autosync110394
Ref: #chart109373 Ref: #autosync110505
Node: check109444 Node: chart110744
Ref: #check109546 Ref: #chart110863
Node: check110934
Ref: #check111036
 
End Tag Table End Tag Table

262
hledger/hledger.txt
View File

@ -1454,18 +1454,45 @@ COMMANDS
Flat-mode balance reports, which normally show exclusive balances, show Flat-mode balance reports, which normally show exclusive balances, show
inclusive balances at the depth limit. inclusive balances at the depth limit.
Percentages
With -% or --percent, balance reports show each account's value ex-
pressed as a percentage of the column's total. This is useful to get
an overview of the relative sizes of account balances. For example to
obtain an overview of expenses:
$ hledger balance expenses -%
100.0 % expenses
50.0 % food
50.0 % supplies
--------------------
100.0 %
Note that --tree does not have an effect on -%. The percentages are
always relative to the total sum of each column, they are never rela-
tive to the parent account.
Since the percentages are relative to the columns sum, it is usually
not useful to calculate percentages if the signs of the amounts are
mixed. Although the results are technically correct, they are most
likely useless. Especially in a balance report that sums up to zero
(eg hledger balance -B) all percentage values will be zero.
This flag does not work if the report contains any mixed commodity ac-
counts. If there are mixed commodity accounts in the report be sure to
use -V or -B to coerce the report into using a single commodity.
Multicolumn balance report Multicolumn balance report
Multicolumn or tabular balance reports are a very useful hledger fea- Multicolumn or tabular balance reports are a very useful hledger fea-
ture, and usually the preferred style. They share many of the above ture, and usually the preferred style. They share many of the above
features, but they show the report as a table, with columns represent- features, but they show the report as a table, with columns represent-
ing time periods. This mode is activated by providing a reporting in- ing time periods. This mode is activated by providing a reporting in-
terval. terval.
There are three types of multicolumn balance report, showing different There are three types of multicolumn balance report, showing different
information: information:
1. By default: each column shows the sum of postings in that period, ie 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 the account's change of balance in that period. This is useful eg
for a monthly income statement: for a monthly income statement:
$ hledger balance --quarterly income expenses -E $ hledger balance --quarterly income expenses -E
@ -1481,7 +1508,7 @@ COMMANDS
|| $-1 $1 0 0 || $-1 $1 0 0
2. With --cumulative: each column shows the ending balance for that pe- 2. With --cumulative: each column shows the ending balance for that pe-
riod, accumulating the changes across periods, starting from 0 at riod, accumulating the changes across periods, starting from 0 at
the report start date: the report start date:
$ hledger balance --quarterly income expenses -E --cumulative $ hledger balance --quarterly income expenses -E --cumulative
@ -1497,8 +1524,8 @@ COMMANDS
|| $-1 0 0 0 || $-1 0 0 0
3. With --historical/-H: each column shows the actual historical ending 3. With --historical/-H: each column shows the actual historical ending
balance for that period, accumulating the changes across periods, balance for that period, accumulating the changes across periods,
starting from the actual balance at the report start date. This is 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 useful eg for a multi-period balance sheet, and when you are showing
only the data after a certain start date: only the data after a certain start date:
@ -1517,26 +1544,26 @@ COMMANDS
Note that --cumulative or --historical/-H disable --row-total/-T, since Note that --cumulative or --historical/-H disable --row-total/-T, since
summing end balances generally does not make sense. summing end balances generally does not make sense.
Multicolumn balance reports display accounts in flat mode by default; Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree. to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report With a reporting interval (like --quarterly above), the report
start/end dates will be adjusted if necessary so that they encompass 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- the displayed report periods. This is so that the first and last peri-
ods will be "full" and comparable to the others. ods will be "full" and comparable to the others.
The -E/--empty flag does two things in multicolumn balance reports: The -E/--empty flag does two things in multicolumn balance reports:
first, the report will show all columns within the specified report pe- first, the report will show all columns within the specified report pe-
riod (without -E, leading and trailing columns with all zeroes are not riod (without -E, leading and trailing columns with all zeroes are not
shown). Second, all accounts which existed at the report start date shown). Second, all accounts which existed at the report start date
will be considered, not just the ones with activity during the report will be considered, not just the ones with activity during the report
period (use -E to include low-activity accounts which would otherwise period (use -E to include low-activity accounts which would otherwise
would be omitted). would be omitted).
The -T/--row-total flag adds an additional column showing the total for The -T/--row-total flag adds an additional column showing the total for
each row. each row.
The -A/--average flag adds a column showing the average value in each The -A/--average flag adds a column showing the average value in each
row. row.
Here's an example of all three: Here's an example of all three:
@ -1560,20 +1587,20 @@ COMMANDS
Limitations: Limitations:
In multicolumn reports the -V/--value flag uses the market price on the 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 report end date, for all columns (not the price on each column's end
date). date).
Eliding of boring parent accounts in tree mode, as in the classic bal- Eliding of boring parent accounts in tree mode, as in the classic bal-
ance report, is not yet supported in multicolumn reports. ance report, is not yet supported in multicolumn reports.
Budget report Budget report
With --budget, extra columns are displayed showing budget goals for With --budget, extra columns are displayed showing budget goals for
each account and period, if any. Budget goals are defined by periodic each account and period, if any. Budget goals are defined by periodic
transactions. This is very useful for comparing planned and actual in- transactions. This is very useful for comparing planned and actual in-
come, expenses, time usage, etc. --budget is most often combined with come, expenses, time usage, etc. --budget is most often combined with
a report interval. a report interval.
For example, you can take average monthly expenses in the common ex- For example, you can take average monthly expenses in the common ex-
pense categories to construct a minimal monthly budget: pense categories to construct a minimal monthly budget:
;; Budget ;; Budget
@ -1620,25 +1647,25 @@ COMMANDS
Note this is different from a normal balance report in several ways: Note this is different from a normal balance report in several ways:
o Only accounts with budget goals during the report period are shown, o Only accounts with budget goals during the report period are shown,
by default. by default.
o In each column, in square brackets after the actual amount, budgeted o In each column, in square brackets after the actual amount, budgeted
amounts are shown, along with the percentage of budget used. amounts are shown, along with the percentage of budget used.
o All parent accounts are always shown, even in flat mode. Eg assets, o All parent accounts are always shown, even in flat mode. Eg assets,
assets:bank, and expenses above. assets:bank, and expenses above.
o Amounts always include all subaccounts, budgeted or unbudgeted, even o Amounts always include all subaccounts, budgeted or unbudgeted, even
in flat mode. in flat mode.
This means that the numbers displayed will not always add up! Eg above, This means that the numbers displayed will not always add up! Eg above,
the expenses actual amount includes the gifts and supplies transac- the expenses actual amount includes the gifts and supplies transac-
tions, but the expenses:gifts and expenses:supplies accounts are not tions, but the expenses:gifts and expenses:supplies accounts are not
shown, as they have no budget amounts declared. shown, as they have no budget amounts declared.
This can be confusing. When you need to make things clearer, use the This can be confusing. When you need to make things clearer, use the
-E/--empty flag, which will reveal all accounts including unbudgeted -E/--empty flag, which will reveal all accounts including unbudgeted
ones, giving the full picture. Eg: ones, giving the full picture. Eg:
$ hledger balance -M --budget --empty $ hledger balance -M --budget --empty
@ -1680,12 +1707,12 @@ COMMANDS
For more examples, see Budgeting and Forecasting. For more examples, see Budgeting and Forecasting.
Nested budgets Nested budgets
You can add budgets to any account in your account hierarchy. If you You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud- have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their get(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave. parent, much like account balances behave.
In the most simple case this means that once you add a budget to any In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well. account, all its parents would have budget as well.
To illustrate this, consider the following budget: To illustrate this, consider the following budget:
@ -1695,13 +1722,13 @@ COMMANDS
expenses:personal:electronics $100.00 expenses:personal:electronics $100.00
liabilities liabilities
With this, monthly budget for electronics is defined to be $100 and With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicity budget for personal expenses is an additional $1000, which implicity
means that budget for both expenses:personal and expenses is $1100. means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both to- Transactions in expenses:personal:electronics will be counted both to-
wards its $100 budget and $1100 of expenses:personal , and transactions wards its $100 budget and $1100 of expenses:personal , and transactions
in any other subaccount of expenses:personal would be counted towards in any other subaccount of expenses:personal would be counted towards
only towards the budget of expenses:personal. only towards the budget of expenses:personal.
For example, let's consider these transactions: For example, let's consider these transactions:
@ -1727,9 +1754,9 @@ COMMANDS
expenses:personal $30.00 expenses:personal $30.00
liabilities liabilities
As you can see, we have transactions in expenses:personal:electron- As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac- these accounts are without explicitly defined budget, these transac-
tions would be counted towards budgets of expenses:personal:electronics tions would be counted towards budgets of expenses:personal:electronics
and expenses:personal accordingly: and expenses:personal accordingly:
@ -1745,7 +1772,7 @@ COMMANDS
-------------------------------++------------------------------- -------------------------------++-------------------------------
|| 0 [ 0] || 0 [ 0]
And with --empty, we can get a better picture of budget allocation and And with --empty, we can get a better picture of budget allocation and
consumption: consumption:
$ hledger balance --budget -M --empty $ hledger balance --budget -M --empty
@ -1763,17 +1790,17 @@ COMMANDS
|| 0 [ 0] || 0 [ 0]
Output format Output format
The balance command supports output destination and output format se- The balance command supports output destination and output format se-
lection. lection.
balancesheet balancesheet
balancesheet, bs balancesheet, bs
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
date). It assumes that these accounts are under a top-level asset or date). It assumes that these accounts are under a top-level asset or
liability account (case insensitive, plural forms also allowed). liability account (case insensitive, plural forms also allowed).
Note this report shows all account balances with normal positive sign Note this report shows all account balances with normal positive sign
(like conventional financial statements, unlike balance/print/register) (like conventional financial statements, unlike balance/print/register)
(experimental). (experimental).
@ -1799,12 +1826,13 @@ COMMANDS
0 0
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. As with multicolumn balance reports, you can alter the report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal- report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates (and a balance sheet; note this means it ignores report begin dates (and
-T/--row-total, since summing end balances generally does not make -T/--row-total, since summing end balances generally does not make
sense). sense). Instead of absolute values percentages can be displayed with
-%.
This command also supports output destination and output format selec- This command also supports output destination and output format selec-
tion. tion.
@ -1868,79 +1896,80 @@ COMMANDS
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. Normally cashflow shows changes in assets per period, report period. Normally cashflow shows changes in assets per period,
though as with multicolumn balance reports you can alter the report though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical. mode with --change/--cumulative/--historical. Instead of absolute val-
ues percentages can be displayed with -%.
This command also supports output destination and output format selec- This command also supports output destination and output format selec-
tion. tion.
check-dates check-dates
check-dates check-dates
Check that transactions are sorted by increasing date. With --date2, Check that transactions are sorted by increasing date. With --date2,
checks secondary dates instead. With --strict, dates must also be checks secondary dates instead. With --strict, dates must also be
unique. With a query, only matched transactions' dates are checked. unique. With a query, only matched transactions' dates are checked.
Reads the default journal file, or another specified with -f. Reads the default journal file, or another specified with -f.
check-dupes check-dupes
check-dupes check-dupes
Reports account names having the same leaf but different prefixes. In Reports account names having the same leaf but different prefixes. In
other words, two or more leaves that are categorized differently. other words, two or more leaves that are categorized differently.
Reads the default journal file, or another specified as an argument. Reads the default journal file, or another specified as an argument.
An example: http://stefanorodighiero.net/software/hledger-dupes.html An example: http://stefanorodighiero.net/software/hledger-dupes.html
close close
close, equity close, equity
Prints a "closing balances" transaction and an "opening balances" Prints a "closing balances" transaction and an "opening balances"
transaction that bring account balances to and from zero, respectively. transaction that bring account balances to and from zero, respectively.
Useful for bringing asset/liability balances forward into a new journal Useful for bringing asset/liability balances forward into a new journal
file, or for closing out revenues/expenses to retained earnings at the file, or for closing out revenues/expenses to retained earnings at the
end of a period. end of a period.
The closing transaction transfers balances to "equity:closing bal- The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open- ances". The opening transaction transfers balances from "equity:open-
ing balances". You can choose to print just one of the transactions by ing balances". You can choose to print just one of the transactions by
using the --opening or --closing flag. using the --opening or --closing flag.
If you split your journal files by time (eg yearly), you will typically If you split your journal files by time (eg yearly), you will typically
run this command at the end of the year, and save the closing transac- run this command at the end of the year, and save the closing transac-
tion as last entry of the old file, and the opening transaction as the tion as last entry of the old file, and the opening transaction as the
first entry of the new file. This makes the files self contained, so first entry of the new file. This makes the files self contained, so
that correct balances are reported no matter which of them are loaded. that correct balances are reported no matter which of them are loaded.
Ie, if you load just one file, the balances are initialised correctly; Ie, if you load just one file, the balances are initialised correctly;
or if you load several files, the redundant closing/opening transac- or if you load several files, the redundant closing/opening transac-
tions cancel each other out. (They will show up in print or register tions cancel each other out. (They will show up in print or register
reports; you can exclude them with a query like not:desc:'(open- reports; you can exclude them with a query like not:desc:'(open-
ing|closing) balances'.) ing|closing) balances'.)
If you're running a business, you might also use this command to "close If you're running a business, you might also use this command to "close
the books" at the end of an accounting period, transferring income the books" at the end of an accounting period, transferring income
statement account balances to retained earnings. (You may want to statement account balances to retained earnings. (You may want to
change the equity account name to something like "equity:retained earn- change the equity account name to something like "equity:retained earn-
ings".) ings".)
By default, the closing transaction is dated yesterday, the balances By default, the closing transaction is dated yesterday, the balances
are calculated as of end of yesterday, and the opening transaction is are calculated as of end of yesterday, and the opening transaction is
dated today. To close on some other date, use: hledger close -e OPEN- dated today. To close on some other date, use: hledger close -e OPEN-
INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
You can also use -p or date:PERIOD (any starting date is ignored). You can also use -p or date:PERIOD (any starting date is ignored).
Both transactions will include balance assertions for the closed/re- Both transactions will include balance assertions for the closed/re-
opened accounts. You probably shouldn't use status or realness filters opened accounts. You probably shouldn't use status or realness filters
(like -C or -R or status:) with this command, or the generated balance (like -C or -R or status:) with this command, or the generated balance
assertions will depend on these flags. Likewise, if you run this com- assertions will depend on these flags. Likewise, if you run this com-
mand with --auto, the balance assertions will probably always require mand with --auto, the balance assertions will probably always require
--auto. --auto.
When account balances have cost information (transaction prices), the When account balances have cost information (transaction prices), the
closing/opening transactions will preserve it, so that eg balance -B closing/opening transactions will preserve it, so that eg balance -B
reports will not be affected. reports will not be affected.
Examples: Examples:
Carrying asset/liability balances into a new file for 2019, all from Carrying asset/liability balances into a new file for 2019, all from
command line: command line:
Warning: we use >> here to append; be careful not to type a single > Warning: we use >> here to append; be careful not to type a single >
which would wipe your journal! which would wipe your journal!
$ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
@ -1989,18 +2018,18 @@ COMMANDS
diff diff
diff diff
Compares a particular account's transactions in two input files. It Compares a particular account's transactions in two input files. It
shows any transactions to this account which are in one file but not in shows any transactions to this account which are in one file but not in
the other. the other.
More precisely, for each posting affecting this account in either file, More precisely, for each posting affecting this account in either file,
it looks for a corresponding posting in the other file which posts the it looks for a corresponding posting in the other file which posts the
same amount to the same account (ignoring date, description, etc.) same amount to the same account (ignoring date, description, etc.)
Since postings not transactions are compared, this also works when mul- Since postings not transactions are compared, this also works when mul-
tiple bank transactions have been combined into a single journal entry. tiple bank transactions have been combined into a single journal entry.
This is useful eg if you have downloaded an account's transactions from This is useful eg if you have downloaded an account's transactions from
your bank (eg as CSV data). When hledger and your bank disagree about your bank (eg as CSV data). When hledger and your bank disagree about
the account balance, you can compare the bank data with your journal to the account balance, you can compare the bank data with your journal to
find out the cause. find out the cause.
@ -2018,20 +2047,20 @@ COMMANDS
files files
files files
List all files included in the journal. With a REGEX argument, only List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown. file names matching the regular expression (case sensitive) are shown.
help help
help help
Show any of the hledger manuals. Show any of the hledger manuals.
The help command displays any of the main hledger manuals, in one of The help command displays any of the main hledger manuals, in one of
several ways. Run it with no argument to list the manuals, or provide several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one. a full or partial manual name to select one.
hledger manuals are available in several formats. hledger help will hledger manuals are available in several formats. hledger help will
use the first of these display methods that it finds: info, man, use the first of these display methods that it finds: info, man,
$PAGER, less, stdout (or when non-interactive, just stdout). You can $PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags. force a particular viewer with the --info, --man, --pager, --cat flags.
Examples: Examples:
@ -2058,9 +2087,9 @@ COMMANDS
import import
import import
Read new transactions added to each FILE since last run, and add them Read new transactions added to each FILE since last run, and add them
to the main journal file. Or with --dry-run, just print the transac- to the main journal file. Or with --dry-run, just print the transac-
tions that would be added. Or with --catchup, just mark all of the tions that would be added. Or with --catchup, just mark all of the
FILEs' transactions as imported, without actually importing any. FILEs' transactions as imported, without actually importing any.
The input files are specified as arguments - no need to write -f before The input files are specified as arguments - no need to write -f before
@ -2071,36 +2100,36 @@ COMMANDS
ing transactions are always added to the input files in increasing date ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files. order, and by saving .latest.FILE state files.
The --dry-run output is in journal format, so you can filter it, eg to The --dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions: see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
Importing balance assignments Importing balance assignments
Entries added by import will have their posting amounts made explicit Entries added by import will have their posting amounts made explicit
(like hledger print -x). This means that any balance assignments in (like hledger print -x). This means that any balance assignments in
imported files must be evaluated; but, imported files don't get to see imported files must be evaluated; but, imported files don't get to see
the main file's account balances. As a result, importing entries with the main file's account balances. As a result, importing entries with
balance assignments (eg from an institution that provides only balances balance assignments (eg from an institution that provides only balances
and not posting amounts) will probably generate incorrect posting and not posting amounts) will probably generate incorrect posting
amounts. To avoid this problem, use print instead of import: amounts. To avoid this problem, use print instead of import:
$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
(If you think import should leave amounts implicit like print does, (If you think import should leave amounts implicit like print does,
please test it and send a pull request.) please test it and send a pull request.)
incomestatement incomestatement
incomestatement, is incomestatement, is
This command displays a simple income statement, showing revenues and This command displays a simple income statement, showing revenues and
expenses during a period. It assumes that these accounts are under a expenses during a period. It assumes that these accounts are under a
top-level revenue or income or expense account (case insensitive, plu- top-level revenue or income or expense account (case insensitive, plu-
ral forms also allowed). Note this report shows all account balances ral forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements, un- with normal positive sign (like conventional financial statements, un-
like balance/print/register) (experimental). like balance/print/register) (experimental).
This command displays a simple income statement. It currently assumes This command displays a simple income statement. It currently assumes
that you have top-level accounts named income (or revenue) and expense that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.) (plural forms also allowed.)
$ hledger incomestatement $ hledger incomestatement
@ -2125,9 +2154,10 @@ COMMANDS
0 0
With a reporting interval, multiple columns will be shown, one for each With a reporting interval, multiple columns will be shown, one for each
report period. Normally incomestatement shows revenues/expenses per report period. Normally incomestatement shows revenues/expenses per
period, though as with multicolumn balance reports you can alter the period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical. report mode with --change/--cumulative/--historical. Instead of abso-
lute values percentages can be displayed with -%.
This command also supports output destination and output format selec- This command also supports output destination and output format selec-
tion. tion.