update embedded manuals

This commit is contained in:
Simon Michael 2017-12-14 18:20:07 -08:00
parent edc50759a0
commit cd5c74625e
16 changed files with 1291 additions and 703 deletions

View File

@ -1,4 +1,4 @@
This is hledger-api.info, produced by makeinfo version 6.0 from stdin.
This is hledger-api.info, produced by makeinfo version 6.5 from stdin.

File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir)

View File

@ -1,4 +1,4 @@
This is hledger_csv.info, produced by makeinfo version 6.0 from stdin.
This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.

File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)

View File

@ -274,7 +274,7 @@ Here's one suggestion:
.PP
.TS
tab(@);
lw(10.5n) lw(59.5n).
lw(9.9n) lw(60.1n).
T{
status
T}@T{
@ -1103,6 +1103,68 @@ Glob patterns (\f[C]*\f[]) are not currently supported.
.PP
The \f[C]include\f[] directive can only be used in journal files.
It can include journal, timeclock or timedot files, but not CSV files.
.SH Periodic transactions
.PP
A periodic transaction starts with a tilde `~' in place of a date
followed by a period expression:
.IP
.nf
\f[C]
~\ weekly
\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck
\ \ income:acme\ inc
\f[]
.fi
.PP
Periodic transactions are used for budgeting and forecasting only, they
have no effect without the \f[C]\-\-forecast\f[] or \f[C]\-\-budget\f[]
option specified.
For examples and details, see Budgeting and Forecasting.
.SH Automated posting rules
.PP
Autopated posting rule starts with an equal sign `=' in place of a date,
followed by a query:
.IP
.nf
\f[C]
=\ expenses:gifts
\ \ \ \ budget:gifts\ \ *\-1
\ \ \ \ assets:budget\ \ *1
\f[]
.fi
.PP
When \f[C]\-\-auto\f[] option is specified on the command line,
automated posting rule will add its postings to all transactions that
match the query.
.PP
If amount in the automated posting rule includes commodity name, new
posting will be made in the given commodity, otherwise commodity of the
matched transaction will be used.
.PP
When amount in the automated posting rule begins with the '*', amount
will be treated as a multiplier that is applied to the amount of the
first posting in the matched transaction.
.PP
In example above, every transaction in \f[C]expenses:gifts\f[] account
will have two additional postings added to it: amount of the original
gift will be debited from \f[C]budget:gifts\f[] and credited into
\f[C]assets:budget\f[]:
.IP
.nf
\f[C]
;\ Original\ transaction
2017\-12\-14
\ \ expenses:gifts\ \ $20
\ \ assets
;\ With\ automated\ postings\ applied
2017/12/14
\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
\ \ \ \ assets
\ \ \ \ budget:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20
\ \ \ \ assets:budget\ \ \ \ \ \ \ \ \ \ \ \ \ \ $20
\f[]
.fi
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with
@ -1116,7 +1178,7 @@ files:
.PP
.TS
tab(@);
lw(16.5n) lw(51.5n).
lw(16.5n) lw(53.5n).
T{
Emacs
T}@T{

View File

@ -1,4 +1,4 @@
This is hledger_journal.info, produced by makeinfo version 6.0 from
This is hledger_journal.info, produced by makeinfo version 6.5 from
stdin.

@ -57,10 +57,12 @@ assisted by the helper modes for emacs or vim.
* Menu:
* FILE FORMAT::
* Periodic transactions::
* Automated posting rules::
* EDITOR SUPPORT::

File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top
File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top
1 FILE FORMAT
*************
@ -270,13 +272,13 @@ toggle transaction status with C-c C-e, or posting status with C-c C-c.
What "uncleared", "pending", and "cleared" actually mean is up to
you. Here's one suggestion:
status meaning
status meaning
--------------------------------------------------------------------------
uncleared recorded but not yet reconciled; needs review
pending tentatively reconciled (if needed, eg during a big
reconciliation)
cleared complete, reconciled as far as possible, and considered
correct
uncleared recorded but not yet reconciled; needs review
pending tentatively reconciled (if needed, eg during a big
reconciliation)
cleared complete, reconciled as far as possible, and considered
correct
With this scheme, you would use '-PC' to see the current balance at
your bank, '-U' to see things which will probably hit your bank soon
@ -1054,9 +1056,67 @@ current file. Glob patterns ('*') are not currently supported.
include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
File: hledger_journal.info, Node: Periodic transactions, Next: Automated posting rules, Prev: FILE FORMAT, Up: Top
2 EDITOR SUPPORT
2 Periodic transactions
***********************
A periodic transaction starts with a tilde '~' in place of a date
followed by a period expression:
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
Periodic transactions are used for budgeting and forecasting only,
they have no effect without the '--forecast' or '--budget' option
specified. For examples and details, see Budgeting and Forecasting.

File: hledger_journal.info, Node: Automated posting rules, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top
3 Automated posting rules
*************************
Autopated posting rule starts with an equal sign '=' in place of a date,
followed by a query:
= expenses:gifts
budget:gifts *-1
assets:budget *1
When '--auto' option is specified on the command line, automated
posting rule will add its postings to all transactions that match the
query.
If amount in the automated posting rule includes commodity name, new
posting will be made in the given commodity, otherwise commodity of the
matched transaction will be used.
When amount in the automated posting rule begins with the '*', amount
will be treated as a multiplier that is applied to the amount of the
first posting in the matched transaction.
In example above, every transaction in 'expenses:gifts' account will
have two additional postings added to it: amount of the original gift
will be debited from 'budget:gifts' and credited into 'assets:budget':
; Original transaction
2017-12-14
expenses:gifts $20
assets
; With automated postings applied
2017/12/14
expenses:gifts $20
assets
budget:gifts $-20
assets:budget $20

File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated posting rules, Up: Top
4 EDITOR SUPPORT
****************
Add-on modes exist for various text editors, to make working with
@ -1078,85 +1138,89 @@ Code

Tag Table:
Node: Top76
Node: FILE FORMAT2370
Ref: #file-format2494
Node: Transactions2717
Ref: #transactions2838
Node: Postings3522
Ref: #postings3649
Node: Dates4644
Ref: #dates4759
Node: Simple dates4824
Ref: #simple-dates4950
Node: Secondary dates5316
Ref: #secondary-dates5470
Node: Posting dates7033
Ref: #posting-dates7162
Node: Status8536
Ref: #status8656
Node: Description10370
Ref: #description10508
Node: Payee and note10827
Ref: #payee-and-note10941
Node: Account names11183
Ref: #account-names11326
Node: Amounts11813
Ref: #amounts11949
Node: Virtual Postings14540
Ref: #virtual-postings14699
Node: Balance Assertions15919
Ref: #balance-assertions16094
Node: Assertions and ordering16990
Ref: #assertions-and-ordering17176
Node: Assertions and included files17876
Ref: #assertions-and-included-files18117
Node: Assertions and multiple -f options18450
Ref: #assertions-and-multiple--f-options18704
Node: Assertions and commodities18836
Ref: #assertions-and-commodities19071
Node: Assertions and subaccounts19767
Ref: #assertions-and-subaccounts19999
Node: Assertions and virtual postings20520
Ref: #assertions-and-virtual-postings20727
Node: Balance Assignments20869
Ref: #balance-assignments21038
Node: Prices22157
Ref: #prices22290
Node: Transaction prices22341
Ref: #transaction-prices22486
Node: Market prices24642
Ref: #market-prices24777
Node: Comments25737
Ref: #comments25859
Node: Tags27101
Ref: #tags27219
Node: Directives28621
Ref: #directives28734
Node: Account aliases28927
Ref: #account-aliases29071
Node: Basic aliases29675
Ref: #basic-aliases29818
Node: Regex aliases30508
Ref: #regex-aliases30676
Node: Multiple aliases31394
Ref: #multiple-aliases31566
Node: end aliases32064
Ref: #end-aliases32204
Node: account directive32305
Ref: #account-directive32485
Node: apply account directive32781
Ref: #apply-account-directive32977
Node: Multi-line comments33636
Ref: #multi-line-comments33826
Node: commodity directive33954
Ref: #commodity-directive34138
Node: Default commodity35010
Ref: #default-commodity35183
Node: Default year35720
Ref: #default-year35885
Node: Including other files36308
Ref: #including-other-files36465
Node: EDITOR SUPPORT36862
Ref: #editor-support36980
Node: FILE FORMAT2424
Ref: #file-format2555
Node: Transactions2778
Ref: #transactions2899
Node: Postings3583
Ref: #postings3710
Node: Dates4705
Ref: #dates4820
Node: Simple dates4885
Ref: #simple-dates5011
Node: Secondary dates5377
Ref: #secondary-dates5531
Node: Posting dates7094
Ref: #posting-dates7223
Node: Status8597
Ref: #status8717
Node: Description10425
Ref: #description10563
Node: Payee and note10882
Ref: #payee-and-note10996
Node: Account names11238
Ref: #account-names11381
Node: Amounts11868
Ref: #amounts12004
Node: Virtual Postings14595
Ref: #virtual-postings14754
Node: Balance Assertions15974
Ref: #balance-assertions16149
Node: Assertions and ordering17045
Ref: #assertions-and-ordering17231
Node: Assertions and included files17931
Ref: #assertions-and-included-files18172
Node: Assertions and multiple -f options18505
Ref: #assertions-and-multiple--f-options18759
Node: Assertions and commodities18891
Ref: #assertions-and-commodities19126
Node: Assertions and subaccounts19822
Ref: #assertions-and-subaccounts20054
Node: Assertions and virtual postings20575
Ref: #assertions-and-virtual-postings20782
Node: Balance Assignments20924
Ref: #balance-assignments21093
Node: Prices22213
Ref: #prices22346
Node: Transaction prices22397
Ref: #transaction-prices22542
Node: Market prices24698
Ref: #market-prices24833
Node: Comments25793
Ref: #comments25915
Node: Tags27157
Ref: #tags27275
Node: Directives28677
Ref: #directives28790
Node: Account aliases28983
Ref: #account-aliases29127
Node: Basic aliases29731
Ref: #basic-aliases29874
Node: Regex aliases30564
Ref: #regex-aliases30732
Node: Multiple aliases31450
Ref: #multiple-aliases31622
Node: end aliases32120
Ref: #end-aliases32260
Node: account directive32361
Ref: #account-directive32541
Node: apply account directive32837
Ref: #apply-account-directive33033
Node: Multi-line comments33692
Ref: #multi-line-comments33882
Node: commodity directive34010
Ref: #commodity-directive34194
Node: Default commodity35066
Ref: #default-commodity35239
Node: Default year35776
Ref: #default-year35941
Node: Including other files36364
Ref: #including-other-files36521
Node: Periodic transactions36918
Ref: #periodic-transactions37089
Node: Automated posting rules37464
Ref: #automated-posting-rules37642
Node: EDITOR SUPPORT38751
Ref: #editor-support38881

End Tag Table

View File

@ -211,10 +211,10 @@ FILE FORMAT
status meaning
--------------------------------------------------------------------------
uncleared recorded but not yet reconciled; needs review
pending tentatively reconciled (if needed, eg during a big recon-
ciliation)
cleared complete, reconciled as far as possible, and considered
correct
pending tentatively reconciled (if needed, eg during a big reconcil-
iation)
cleared complete, reconciled as far as possible, and considered cor-
rect
With this scheme, you would use -PC to see the current balance at your
bank, -U to see things which will probably hit your bank soon (like
@ -811,32 +811,79 @@ FILE FORMAT
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Periodic transactions
A periodic transaction starts with a tilde `~' in place of a date fol-
lowed by a period expression:
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
Periodic transactions are used for budgeting and forecasting only, they
have no effect without the --forecast or --budget option specified.
For examples and details, see Budgeting and Forecasting.
Automated posting rules
Autopated posting rule starts with an equal sign `=' in place of a
date, followed by a query:
= expenses:gifts
budget:gifts *-1
assets:budget *1
When --auto option is specified on the command line, automated posting
rule will add its postings to all transactions that match the query.
If amount in the automated posting rule includes commodity name, new
posting will be made in the given commodity, otherwise commodity of the
matched transaction will be used.
When amount in the automated posting rule begins with the '*', amount
will be treated as a multiplier that is applied to the amount of the
first posting in the matched transaction.
In example above, every transaction in expenses:gifts account will have
two additional postings added to it: amount of the original gift will
be debited from budget:gifts and credited into assets:budget:
; Original transaction
2017-12-14
expenses:gifts $20
assets
; With automated postings applied
2017/12/14
expenses:gifts $20
assets
budget:gifts $-20
assets:budget $20
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger
These were written with Ledger in mind, but also work with hledger
files:
Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html
Vim https://github.com/ledger/ledger/wiki/Get-
ting-started
Vim https://github.com/ledger/ledger/wiki/Getting-started
Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub-
lime-Text
Textmate https://github.com/ledger/ledger/wiki/Using-Text-
Mate-2
Text Wrangler https://github.com/ledger/ledger/wiki/Edit-
ing-Ledger-files-with-TextWrangler
Visual Studio https://marketplace.visualstudio.com/items?item-
Code Name=mark-hansen.hledger-vscode
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)
@ -850,7 +897,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -1,4 +1,4 @@
This is hledger_timeclock.info, produced by makeinfo version 6.0 from
This is hledger_timeclock.info, produced by makeinfo version 6.5 from
stdin.


View File

@ -1,4 +1,4 @@
This is hledger_timedot.info, produced by makeinfo version 6.0 from
This is hledger_timedot.info, produced by makeinfo version 6.5 from
stdin.


View File

@ -136,8 +136,8 @@ multiperiod/multicolumn report by year
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
.RS
.RE
.TP
@ -187,6 +187,21 @@ convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
.TP
.B \f[C]\-\-forecast\f[]
generate forecast transactions from [periodic
transaction]((journal.html#periodic\-transactions) rules.
Each periodic transaction rule will generate forecast transactions,
beginning the day after the last recorded journal transaction, and
ending 6 months from today, or at the specified report end date.
.RS
.RE
.TP
.B \f[C]\-\-auto\f[]
apply automated posting rules to modify transactions where applicable
(can combine with \[en]forecast).
.RS
.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.

View File

@ -1,4 +1,4 @@
This is hledger-ui.info, produced by makeinfo version 6.0 from stdin.
This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.

File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
@ -100,7 +100,7 @@ the data.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
using period expressions syntax (overrides the flags above)
'--date2'
match the secondary date instead (see command help for other
@ -131,6 +131,17 @@ the data.
convert amounts to their market value on the report end date (using
the most recent applicable market price, if any)
'--forecast'
generate forecast transactions from [periodic
transaction]((journal.html#periodic-transactions) rules. Each
periodic transaction rule will generate forecast transactions,
beginning the day after the last recorded journal transaction, and
ending 6 months from today, or at the specified report end date.
'--auto'
apply automated posting rules to modify transactions where
applicable (can combine with -forecast).
When a reporting option appears more than once in the command line,
the last one takes precedence.
@ -371,17 +382,17 @@ Tag Table:
Node: Top71
Node: OPTIONS821
Ref: #options918
Node: KEYS3855
Ref: #keys3950
Node: SCREENS6909
Ref: #screens6994
Node: Accounts screen7084
Ref: #accounts-screen7212
Node: Register screen9442
Ref: #register-screen9597
Node: Transaction screen11671
Ref: #transaction-screen11829
Node: Error screen12699
Ref: #error-screen12821
Node: KEYS4350
Ref: #keys4445
Node: SCREENS7404
Ref: #screens7489
Node: Accounts screen7579
Ref: #accounts-screen7707
Node: Register screen9937
Ref: #register-screen10092
Node: Transaction screen12166
Ref: #transaction-screen12324
Node: Error screen13194
Ref: #error-screen13316

End Tag Table

View File

@ -96,7 +96,7 @@ OPTIONS
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
using period expressions syntax (overrides the flags above)
--date2
match the secondary date instead (see command help for other
@ -128,6 +128,16 @@ OPTIONS
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
--forecast
generate forecast transactions from [periodic transac-
tion]((journal.html#periodic-transactions) rules. Each periodic
transaction rule will generate forecast transactions, beginning
the day after the last recorded journal transaction, and ending
6 months from today, or at the specified report end date.
--auto apply automated posting rules to modify transactions where
applicable (can combine with -forecast).
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -145,64 +155,64 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this,
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
KEYS
? shows a help dialog listing all keys. (Some of these also appear in
? shows a help dialog listing all keys. (Some of these also appear in
the quick help at the bottom of each screen.) Press ? again (or ESCAPE,
or LEFT) to close it. The following keys work on most screens:
The cursor keys navigate: right (or enter) goes deeper, left returns to
the previous screen, up/down/page up/page down/home/end move up and
down through lists. Vi-style (h/j/k/l) and Emacs-style
the previous screen, up/down/page up/page down/home/end move up and
down through lists. Vi-style (h/j/k/l) and Emacs-style
(CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip:
movement speed is limited by your keyboard repeat rate, to move faster
you may want to adjust it. (If you're on a mac, the Karabiner app is
movement speed is limited by your keyboard repeat rate, to move faster
you may want to adjust it. (If you're on a mac, the Karabiner app is
one way to do that.)
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
shift-down/up steps downward and upward through these standard report
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
shift-down/up steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then,
shift-left/right moves to the previous/next period. t sets the report
period to today. With the --watch option, when viewing a "current"
period (the current day, week, month, quarter, or year), the period
will move automatically to track the current date. To set a non-stan-
shift-left/right moves to the previous/next period. t sets the report
period to today. With the --watch option, when viewing a "current"
period (the current day, week, month, quarter, or year), the period
will move automatically to track the current date. To set a non-stan-
dard period, you can use / and a date: query.
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
it, or ESCAPEto cancel. There are also keys for quickly adjusting some
common filters like account depth and transaction status (see below).
common filters like account depth and transaction status (see below).
BACKSPACE or DELETE removes all filters, showing all transactions.
ESCAPE removes all filters and jumps back to the top screen. Or, it
ESCAPE removes all filters and jumps back to the top screen. Or, it
cancels a minibuffer edit or help dialog in progress.
CTRL-l redraws the screen and centers the selection if possible (selec-
tions near the top won't be centered, since we don't scroll above the
tions near the top won't be centered, since we don't scroll above the
top).
g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable
g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable
pause.)
I toggles balance assertion checking. Disabling balance assertions
I toggles balance assertion checking. Disabling balance assertions
temporarily can be useful for troubleshooting.
a runs command-line hledger's add command, and reloads the updated
a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a
curses-style interface. This key will be available if hledger-iadd is
A is like a, but runs the hledger-iadd tool, which provides a
curses-style interface. This key will be available if hledger-iadd is
installed in $PATH.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac-
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac-
sclient -a "" -nw) on the journal file. With some editors (emacs, vi),
the cursor will be positioned at the current transaction when invoked
from the register and transaction screens, and at the error location
the cursor will be positioned at the current transaction when invoked
from the register and transaction screens, and at the error location
(if possible) when invoked from the error screen.
q quits the application.
@ -211,44 +221,44 @@ KEYS
SCREENS
Accounts screen
This is normally the first screen displayed. It lists accounts and
their balances, like hledger's balance command. By default, it shows
all accounts and their latest ending balances (including the balances
of subaccounts). if you specify a query on the command line, it shows
This is normally the first screen displayed. It lists accounts and
their balances, like hledger's balance command. By default, it shows
all accounts and their latest ending balances (including the balances
of subaccounts). if you specify a query on the command line, it shows
just the matched accounts and the balances from matched transactions.
Account names are normally indented to show the hierarchy (tree mode).
Account names are normally indented to show the hierarchy (tree mode).
To see less detail, set a depth limit by pressing a number key, 1 to 9.
0 shows even less detail, collapsing all accounts to a single total. -
and + (or =) decrease and increase the depth limit. To remove the
depth limit, set it higher than the maximum account depth, or press
and + (or =) decrease and increase the depth limit. To remove the
depth limit, set it higher than the maximum account depth, or press
ESCAPE.
F toggles flat mode, in which accounts are shown as a flat list, with
their full names. In this mode, account balances exclude subaccounts,
except for accounts at the depth limit (as with hledger's balance com-
F toggles flat mode, in which accounts are shown as a flat list, with
their full names. In this mode, account balances exclude subaccounts,
except for accounts at the depth limit (as with hledger's balance com-
mand).
H toggles between showing historical balances or period balances. His-
torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions
torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions
before the report start date, so they show the change in balance during
the report period. They are more useful eg when viewing a time log.
U toggles filtering by unmarked status, including or excluding unmarked
postings in the balances. Similarly, P toggles pending postings, and C
toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are
toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are
included; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line
Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line
hledger).
Press right or enter to view an account's transactions register.
@ -257,65 +267,65 @@ SCREENS
This screen shows the transactions affecting a particular account, like
a check register. Each line represents one transaction and shows:
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
by real postings.)
o the overall change to the current account's balance; positive for an
o the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow.
o the running historical total or period total for the current account,
after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while
after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while
the period total is not. If the historical total is not disturbed by
a filter query, it will be the running historical balance you would
a filter query, it will be the running historical balance you would
see on a bank register for the current account.
If the accounts screen was in tree mode, the register screen will
If the accounts screen was in tree mode, the register screen will
include transactions from both the current account and its subaccounts.
If the accounts screen was in flat mode, and a non-depth-clipped
account was selected, the register screen will exclude transactions
If the accounts screen was in flat mode, and a non-depth-clipped
account was selected, the register screen will exclude transactions
from subaccounts. In other words, the register always shows the trans-
actions responsible for the period balance shown on the accounts
actions responsible for the period balance shown on the accounts
screen. As on the accounts screen, this can be toggled with F.
U toggles filtering by unmarked status, showing or hiding unmarked
U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is
removed.)q
R toggles real mode, in which virtual postings are ignored.
Z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com-
Z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com-
mand-line hledger).
Press right (or enter) to view the selected transaction in detail.
Transaction screen
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour-
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour-
nal(5)).
The transaction's date(s) and any cleared flag, transaction code,
description, comments, along with all of its account postings are
shown. Simple transactions have two postings, but there can be more
The transaction's date(s) and any cleared flag, transaction code,
description, comments, along with all of its account postings are
shown. Simple transactions have two postings, but there can be more
(or in certain cases, fewer).
up and down will step through all transactions listed in the previous
account register screen. In the title bar, the numbers in parentheses
show your position within that account register. They will vary
up and down will step through all transactions listed in the previous
account register screen. In the title bar, the numbers in parentheses
show your position within that account register. They will vary
depending on which account register you came from (remember most trans-
actions appear in multiple account registers). The #N number preceding
them is the transaction's position within the complete unfiltered jour-
nal, which is a more stable id (at least until the next reload).
Error screen
This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g
This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g
again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)
@ -323,17 +333,17 @@ ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede options with -- when invoked from hledger is awk-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-ui can't read from stdin).
@ -341,13 +351,13 @@ BUGS
-V affects only the accounts screen.
When you press g, the current and all previous screens are regenerated,
which may cause a noticeable pause with large files. Also there is no
which may cause a noticeable pause with large files. Also there is no
visual indication that this is in progress.
--watch is not yet fully robust. It works well for normal usage, but
many file changes in a short time (eg saving the file thousands of
times with an editor macro) can cause problems at least on OSX. Symp-
toms include: unresponsive UI, periodic resetting of the cursor posi-
--watch is not yet fully robust. It works well for normal usage, but
many file changes in a short time (eg saving the file thousands of
times with an editor macro) can cause problems at least on OSX. Symp-
toms include: unresponsive UI, periodic resetting of the cursor posi-
tion, momentary display of parse errors, high CPU usage eventually sub-
siding, and possibly a small but persistent build-up of CPU usage until
the program is restarted.
@ -355,7 +365,7 @@ 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)
@ -369,7 +379,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -191,8 +191,8 @@ multiperiod/multicolumn report by year
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
.RS
.RE
.TP
@ -242,6 +242,21 @@ convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
.TP
.B \f[C]\-\-forecast\f[]
generate forecast transactions from [periodic
transaction]((journal.html#periodic\-transactions) rules.
Each periodic transaction rule will generate forecast transactions,
beginning the day after the last recorded journal transaction, and
ending 6 months from today, or at the specified report end date.
.RS
.RE
.TP
.B \f[C]\-\-auto\f[]
apply automated posting rules to modify transactions where applicable
(can combine with \[en]forecast).
.RS
.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.

View File

@ -1,4 +1,4 @@
This is hledger-web.info, produced by makeinfo version 6.0 from stdin.
This is hledger-web.info, produced by makeinfo version 6.5 from stdin.

File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
@ -145,7 +145,7 @@ options as shown above.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
using period expressions syntax (overrides the flags above)
'--date2'
match the secondary date instead (see command help for other
@ -176,6 +176,17 @@ options as shown above.
convert amounts to their market value on the report end date (using
the most recent applicable market price, if any)
'--forecast'
generate forecast transactions from [periodic
transaction]((journal.html#periodic-transactions) rules. Each
periodic transaction rule will generate forecast transactions,
beginning the day after the last recorded journal transaction, and
ending 6 months from today, or at the specified report end date.
'--auto'
apply automated posting rules to modify transactions where
applicable (can combine with -forecast).
When a reporting option appears more than once in the command line,
the last one takes precedence.

View File

@ -141,7 +141,7 @@ OPTIONS
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
using period expressions syntax (overrides the flags above)
--date2
match the secondary date instead (see command help for other
@ -173,6 +173,16 @@ OPTIONS
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
--forecast
generate forecast transactions from [periodic transac-
tion]((journal.html#periodic-transactions) rules. Each periodic
transaction rule will generate forecast transactions, beginning
the day after the last recorded journal transaction, and ending
6 months from today, or at the specified report end date.
--auto apply automated posting rules to modify transactions where
applicable (can combine with -forecast).
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -190,22 +200,22 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this,
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede options with -- when invoked from hledger is awk-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-web can't read from stdin).
@ -219,7 +229,7 @@ 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)
@ -233,7 +243,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

View File

@ -246,8 +246,8 @@ multiperiod/multicolumn report by year
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
.RS
.RE
.TP
@ -297,6 +297,21 @@ convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
.TP
.B \f[C]\-\-forecast\f[]
generate forecast transactions from [periodic
transaction]((journal.html#periodic\-transactions) rules.
Each periodic transaction rule will generate forecast transactions,
beginning the day after the last recorded journal transaction, and
ending 6 months from today, or at the specified report end date.
.RS
.RE
.TP
.B \f[C]\-\-auto\f[]
apply automated posting rules to modify transactions where applicable
(can combine with \[en]forecast).
.RS
.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -407,7 +422,7 @@ turn:
.PP
.TS
tab(@);
lw(10.7n) lw(33.2n) lw(26.1n).
lw(10.3n) lw(33.5n) lw(26.2n).
T{
Reader:
T}@T{
@ -1433,6 +1448,19 @@ Sort by amount (total row amount, or by average if that is displayed),
instead of account name (in flat mode)
.RS
.RE
.TP
.B \f[C]\-\-budget\f[]
Treat periodic transaction as definition of a budget.
Compare real balances to budget balances and show percentage of budget
consumed.
.RS
.RE
.TP
.B \f[C]\-\-show\-unbudgeted\f[]
When \[en]budget is used, display accounts that do not have budget
defined
.RS
.RE
.PP
The balance command displays accounts and balances.
It is hledger's most featureful and versatile command.
@ -1641,6 +1669,108 @@ Balance\ changes\ in\ 2008:
#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
\f[]
.fi
.SS Budgets
.PP
The \f[C]\-\-budget\f[] flag will treat all [periodic
transaction]((journal.html#periodic\-transactions) in your journal as
definition of the budget and allow you to compare real balances versus
budgeted amounts.
.PP
For example, you can take average monthly expenses in the common expense
categories to construct a minimal monthly budget:
.IP
.nf
\f[C]
;;\ 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
\f[]
.fi
.PP
You can now compare real balances with budget:
.IP
.nf
\f[C]
$\ hledge\ 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\
\f[]
.fi
.PP
You can roll over unspent budgets to next period with
\f[C]\-\-cumulative\f[]:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 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
Adding \f[C]\-\-show\-unbudgeted\f[] will allow you to see all the
accounts for which budgets:
.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]\
\ 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\
\f[]
.fi
.PP
For more examples and details, see Budgeting and Forecasting.
.SS Custom balance output
.PP
In simple (non\-multi\-column) balance reports, you can customise the

View File

@ -1,4 +1,4 @@
This is hledger.info, produced by makeinfo version 6.0 from stdin.
This is hledger.info, produced by makeinfo version 6.5 from stdin.

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
@ -201,7 +201,7 @@ by most hledger commands, run 'hledger -h'.
'-p --period=PERIODEXP'
set start date, end date, and/or reporting interval all at once
(overrides the flags above)
using period expressions syntax (overrides the flags above)
'--date2'
match the secondary date instead (see command help for other
@ -232,6 +232,17 @@ by most hledger commands, run 'hledger -h'.
convert amounts to their market value on the report end date (using
the most recent applicable market price, if any)
'--forecast'
generate forecast transactions from [periodic
transaction]((journal.html#periodic-transactions) rules. Each
periodic transaction rule will generate forecast transactions,
beginning the day after the last recorded journal transaction, and
ending 6 months from today, or at the specified report end date.
'--auto'
apply automated posting rules to modify transactions where
applicable (can combine with -forecast).
When a reporting option appears more than once in the command line,
the last one takes precedence.
@ -339,15 +350,15 @@ be one of several other formats, listed below. hledger detects the
format automatically based on the file extension, or if that is not
recognised, by trying each built-in "reader" in turn:
Reader: Reads: Used for file extensions:
---------------------------------------------------------------------------
'journal' hledger's journal format, also '.journal' '.j'
some Ledger journals '.hledger' '.ledger'
'timeclock' timeclock files (precise time '.timeclock'
Reader: Reads: Used for file extensions:
----------------------------------------------------------------------------
'journal' hledger's journal format, also '.journal' '.j'
some Ledger journals '.hledger' '.ledger'
'timeclock' timeclock files (precise time '.timeclock'
logging)
'timedot' timedot files (approximate time '.timedot'
'timedot' timedot files (approximate time '.timedot'
logging)
'csv' comma-separated values (data '.csv'
'csv' comma-separated values (data '.csv'
interchange)
If needed (eg to ensure correct error messages when a file has the
@ -1082,6 +1093,14 @@ Show accounts and their balances. Aliases: b, bal.
Sort by amount (total row amount, or by average if that is
displayed), instead of account name (in flat mode)
'--budget'
Treat periodic transaction as definition of a budget. Compare real
balances to budget balances and show percentage of budget consumed.
'--show-unbudgeted'
When -budget is used, display accounts that do not have budget
defined
The balance command displays accounts and balances. It is hledger's
most featureful and versatile command.
@ -1131,6 +1150,7 @@ $ hledger balance -p 2008/6 expenses --no-total
* Flat mode::
* Depth limited balance reports::
* Multicolumn balance reports::
* Budgets::
* Custom balance output::
* Colour support::
* Output destination::
@ -1170,7 +1190,7 @@ $ hledger balance -N --depth 1
$1 liabilities

File: hledger.info, Node: Multicolumn balance reports, Next: Custom balance output, Prev: Depth limited balance reports, Up: balance
File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance
4.4.3 Multicolumn balance reports
---------------------------------
@ -1270,9 +1290,99 @@ Balance changes in 2008:
# Average is rounded to the dollar here since all journal amounts are

File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Multicolumn balance reports, Up: balance
File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance
4.4.4 Custom balance output
4.4.4 Budgets
-------------
The '--budget' flag will treat all [periodic
transaction]((journal.html#periodic-transactions) in your journal as
definition of the budget and allow you to compare real balances versus
budgeted amounts.
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 compare real balances with budget:
$ hledge 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
Adding '--show-unbudgeted' will allow you to see all the accounts for
which budgets:
$ 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
For more examples and details, see Budgeting and Forecasting.

File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance
4.4.5 Custom balance output
---------------------------
In simple (non-multi-column) balance reports, you can customise the
@ -1332,7 +1442,7 @@ may be needed to get pleasing results.

File: hledger.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance
4.4.5 Colour support
4.4.6 Colour support
--------------------
The balance command shows negative amounts in red, if:
@ -1343,7 +1453,7 @@ The balance command shows negative amounts in red, if:

File: hledger.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance
4.4.6 Output destination
4.4.7 Output destination
------------------------
The balance, print, register and stats commands can write their output
@ -1356,7 +1466,7 @@ $ hledger balance -o FILE # write to FILE

File: hledger.info, Node: CSV output, Prev: Output destination, Up: balance
4.4.7 CSV output
4.4.8 CSV output
----------------
The balance, print and register commands can write their output as CSV.
@ -2264,129 +2374,131 @@ Node: OPTIONS3628
Ref: #options3730
Node: General options4046
Ref: #general-options4171
Node: Command options6490
Ref: #command-options6641
Node: Command arguments7039
Ref: #command-arguments7193
Node: Argument files7314
Ref: #argument-files7465
Node: Special characters7731
Ref: #special-characters7884
Node: Input files9303
Ref: #input-files9439
Node: Smart dates11402
Ref: #smart-dates11543
Node: Report start & end date12522
Ref: #report-start-end-date12692
Node: Report intervals13757
Ref: #report-intervals13920
Node: Period expressions14321
Ref: #period-expressions14478
Node: For example16523
Ref: #for-example16666
Node: Depth limiting18590
Ref: #depth-limiting18727
Node: Pivoting19069
Ref: #pivoting19187
Node: Cost20863
Ref: #cost20971
Node: Market value21089
Ref: #market-value21224
Node: Regular expressions22524
Ref: #regular-expressions22660
Node: QUERIES24021
Ref: #queries24123
Node: COMMANDS28090
Ref: #commands28202
Node: accounts29185
Ref: #accounts29283
Node: activity30276
Ref: #activity30386
Node: add30745
Ref: #add30844
Node: balance33502
Ref: #balance33613
Node: Flat mode36770
Ref: #flat-mode36895
Node: Depth limited balance reports37315
Ref: #depth-limited-balance-reports37516
Node: Multicolumn balance reports37936
Ref: #multicolumn-balance-reports38145
Node: Custom balance output42793
Ref: #custom-balance-output42975
Node: Colour support45068
Ref: #colour-support45227
Node: Output destination45400
Ref: #output-destination45556
Node: CSV output45826
Ref: #csv-output45943
Node: balancesheet46340
Ref: #balancesheet46476
Node: balancesheetequity48444
Ref: #balancesheetequity48593
Node: cashflow49382
Ref: #cashflow49510
Node: check-dates51422
Ref: #check-dates51549
Node: check-dupes51666
Ref: #check-dupes51791
Node: equity51928
Ref: #equity52038
Node: help52201
Ref: #help52302
Node: import53376
Ref: #import53490
Node: incomestatement54220
Ref: #incomestatement54354
Node: prices56307
Ref: #prices56422
Node: print56465
Ref: #print56575
Node: print-unique61421
Ref: #print-unique61547
Node: register61615
Ref: #register61742
Node: Custom register output66243
Ref: #custom-register-output66372
Node: register-match67669
Ref: #register-match67803
Node: rewrite67986
Ref: #rewrite68103
Node: stats68172
Ref: #stats68275
Node: tags69156
Ref: #tags69254
Node: test69490
Ref: #test69574
Node: ADD-ON COMMANDS69942
Ref: #add-on-commands70052
Node: Official add-ons71339
Ref: #official-add-ons71479
Node: api71566
Ref: #api71655
Node: ui71707
Ref: #ui71806
Node: web71864
Ref: #web71953
Node: Third party add-ons71999
Ref: #third-party-add-ons72174
Node: diff72309
Ref: #diff72406
Node: iadd72505
Ref: #iadd72619
Node: interest72702
Ref: #interest72823
Node: irr72918
Ref: #irr73016
Node: Experimental add-ons73094
Ref: #experimental-add-ons73246
Node: autosync73537
Ref: #autosync73649
Node: budget73888
Ref: #budget74010
Node: chart74076
Ref: #chart74193
Node: check74264
Ref: #check74366
Node: Command options6985
Ref: #command-options7136
Node: Command arguments7534
Ref: #command-arguments7688
Node: Argument files7809
Ref: #argument-files7960
Node: Special characters8226
Ref: #special-characters8379
Node: Input files9798
Ref: #input-files9934
Node: Smart dates11904
Ref: #smart-dates12045
Node: Report start & end date13024
Ref: #report-start-end-date13194
Node: Report intervals14259
Ref: #report-intervals14422
Node: Period expressions14823
Ref: #period-expressions14980
Node: For example17025
Ref: #for-example17168
Node: Depth limiting19092
Ref: #depth-limiting19229
Node: Pivoting19571
Ref: #pivoting19689
Node: Cost21365
Ref: #cost21473
Node: Market value21591
Ref: #market-value21726
Node: Regular expressions23026
Ref: #regular-expressions23162
Node: QUERIES24523
Ref: #queries24625
Node: COMMANDS28592
Ref: #commands28704
Node: accounts29687
Ref: #accounts29785
Node: activity30778
Ref: #activity30888
Node: add31248
Ref: #add31347
Node: balance34008
Ref: #balance34119
Node: Flat mode37548
Ref: #flat-mode37673
Node: Depth limited balance reports38093
Ref: #depth-limited-balance-reports38294
Node: Multicolumn balance reports38714
Ref: #multicolumn-balance-reports38909
Node: Budgets43598
Ref: #budgets43745
Node: Custom balance output47361
Ref: #custom-balance-output47523
Node: Colour support49616
Ref: #colour-support49775
Node: Output destination49948
Ref: #output-destination50104
Node: CSV output50374
Ref: #csv-output50491
Node: balancesheet50888
Ref: #balancesheet51024
Node: balancesheetequity52992
Ref: #balancesheetequity53141
Node: cashflow53930
Ref: #cashflow54058
Node: check-dates55970
Ref: #check-dates56097
Node: check-dupes56214
Ref: #check-dupes56339
Node: equity56476
Ref: #equity56586
Node: help56749
Ref: #help56850
Node: import57924
Ref: #import58038
Node: incomestatement58768
Ref: #incomestatement58902
Node: prices60855
Ref: #prices60970
Node: print61013
Ref: #print61123
Node: print-unique65969
Ref: #print-unique66095
Node: register66163
Ref: #register66290
Node: Custom register output70791
Ref: #custom-register-output70920
Node: register-match72217
Ref: #register-match72351
Node: rewrite72534
Ref: #rewrite72651
Node: stats72720
Ref: #stats72823
Node: tags73705
Ref: #tags73803
Node: test74039
Ref: #test74123
Node: ADD-ON COMMANDS74491
Ref: #add-on-commands74601
Node: Official add-ons75888
Ref: #official-add-ons76028
Node: api76115
Ref: #api76204
Node: ui76256
Ref: #ui76355
Node: web76413
Ref: #web76502
Node: Third party add-ons76548
Ref: #third-party-add-ons76723
Node: diff76858
Ref: #diff76955
Node: iadd77054
Ref: #iadd77168
Node: interest77251
Ref: #interest77372
Node: irr77467
Ref: #irr77565
Node: Experimental add-ons77643
Ref: #experimental-add-ons77795
Node: autosync78086
Ref: #autosync78198
Node: budget78437
Ref: #budget78559
Node: chart78625
Ref: #chart78742
Node: check78813
Ref: #check78915

End Tag Table

File diff suppressed because it is too large Load Diff