;update manuals

This commit is contained in:
Simon Michael 2020-10-18 16:01:59 -07:00
parent 3fb3c9c19f
commit f0db3fb157
19 changed files with 287 additions and 295 deletions

View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.19.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{September 2020}})m4_dnl
m4_define({{_monthyear_}}, {{October 2020}})m4_dnl

View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_csv" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals"
.TH "hledger_csv" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals"

View File

@ -922,4 +922,4 @@ SEE ALSO
hledger 1.19.99 September 2020 hledger_csv(5)
hledger 1.19.99 October 2020 hledger_csv(5)

View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_journal" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals"
.TH "hledger_journal" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals"
@ -950,6 +950,8 @@ versions).
Directives\[aq] behaviour and interactions can get a little bit complex,
so here is a table summarising the directives and their effects, with
links to more detailed docs.
Note part of this table is hidden when viewed in a web browser - scroll
it sideways to see more.
.PP
.TS
tab(@);
@ -984,8 +986,7 @@ T}@T{
T}@T{
rewrite account names
T}@T{
following inline/included entries until end of current file or end
directive
following entries until end of current file or end directive
T}
T{
\f[C]apply account\f[R]
@ -995,8 +996,7 @@ T}@T{
T}@T{
prepend a common parent to account names
T}@T{
following inline/included entries until end of current file or end
directive
following entries until end of current file or end directive
T}
T{
\f[C]comment\f[R]
@ -1006,8 +1006,7 @@ T}@T{
T}@T{
ignore part of journal
T}@T{
following inline/included entries until end of current file or end
directive
following entries until end of current file or end directive
T}
T{
\f[C]commodity\f[R]
@ -1017,7 +1016,7 @@ T}@T{
T}@T{
declare a commodity and its number notation & display style
T}@T{
number notation: following entries in that commodity in all files;
number notation: following entries in that commodity in all files ;
display style: amounts of that commodity in reports
T}
T{
@ -1057,7 +1056,7 @@ T}@T{
T}@T{
declare a year for yearless dates
T}@T{
following inline/included entries until end of current file
following entries until end of current file
T}
T{
\f[C]=\f[R]

View File

@ -888,7 +888,8 @@ some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex,
so here is a table summarising the directives and their effects, with
links to more detailed docs.
links to more detailed docs. Note part of this table is hidden when
viewed in a web browser - scroll it sideways to see more.
directiveend subdirectivespurpose can affect (as of
directive 2018/06)
@ -896,25 +897,22 @@ directiveend subdirectivespurpose can affect (as of
'account' any document account names, all entries in
text declare account types & all files, before
display order or after
'alias' 'end rewrite account names following
aliases' inline/included
entries until end
of current file
or end directive
'apply 'end prepend a common parent to following
account' apply account names inline/included
account' entries until end
of current file
or end directive
'comment''end ignore part of journal following
comment' inline/included
entries until end
of current file
or end directive
'alias' 'end rewrite account names following entries
aliases' until end of
current file or
end directive
'apply 'end prepend a common parent to following entries
account' apply account names until end of
account' current file or
end directive
'comment''end ignore part of journal following entries
comment' until end of
current file or
end directive
'commodity' 'format'declare a commodity and its number notation:
number notation & display following entries
style in that commodity
in all files;
in all files ;
display style:
amounts of that
commodity in
@ -940,10 +938,9 @@ account' apply account names inline/included
a commodity commodity in
reports, when -V
is used
'Y' declare a year for yearless following
dates inline/included
entries until end
of current file
'Y' declare a year for yearless following entries
dates until end of
current file
'=' declare an auto posting all entries in
rule, adding postings to parent/current/child
other transactions files (but not
@ -1924,64 +1921,64 @@ Node: Balance assignments and prices30866
Ref: #balance-assignments-and-prices31038
Node: Directives31262
Ref: #directives31421
Node: Directives and multiple files37112
Ref: #directives-and-multiple-files37295
Node: Comment blocks37959
Ref: #comment-blocks38142
Node: Including other files38318
Ref: #including-other-files38498
Node: Default year39422
Ref: #default-year39591
Node: Declaring commodities39998
Ref: #declaring-commodities40181
Node: Default commodity41987
Ref: #default-commodity42173
Node: Declaring market prices43062
Ref: #declaring-market-prices43257
Node: Declaring accounts44114
Ref: #declaring-accounts44300
Node: Account comments45225
Ref: #account-comments45388
Node: Account subdirectives45812
Ref: #account-subdirectives46007
Node: Account types46320
Ref: #account-types46504
Node: Account display order49550
Ref: #account-display-order49720
Node: Rewriting accounts50871
Ref: #rewriting-accounts51056
Node: Basic aliases51813
Ref: #basic-aliases51959
Node: Regex aliases52663
Ref: #regex-aliases52835
Node: Combining aliases53554
Ref: #combining-aliases53747
Node: Aliases and multiple files55023
Ref: #aliases-and-multiple-files55232
Node: end aliases55811
Ref: #end-aliases55968
Node: Default parent account56069
Ref: #default-parent-account56237
Node: Periodic transactions57121
Ref: #periodic-transactions57296
Node: Periodic rule syntax59168
Ref: #periodic-rule-syntax59374
Node: Two spaces between period expression and description!60078
Ref: #two-spaces-between-period-expression-and-description60397
Node: Forecasting with periodic transactions61081
Ref: #forecasting-with-periodic-transactions61386
Node: Budgeting with periodic transactions63441
Ref: #budgeting-with-periodic-transactions63680
Node: Auto postings64089
Ref: #auto-postings64229
Node: Auto postings and multiple files66408
Ref: #auto-postings-and-multiple-files66612
Node: Auto postings and dates66821
Ref: #auto-postings-and-dates67095
Node: Auto postings and transaction balancing / inferred amounts / balance assertions67270
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67621
Node: Auto posting tags67963
Ref: #auto-posting-tags68178
Node: Directives and multiple files36919
Ref: #directives-and-multiple-files37102
Node: Comment blocks37766
Ref: #comment-blocks37949
Node: Including other files38125
Ref: #including-other-files38305
Node: Default year39229
Ref: #default-year39398
Node: Declaring commodities39805
Ref: #declaring-commodities39988
Node: Default commodity41794
Ref: #default-commodity41980
Node: Declaring market prices42869
Ref: #declaring-market-prices43064
Node: Declaring accounts43921
Ref: #declaring-accounts44107
Node: Account comments45032
Ref: #account-comments45195
Node: Account subdirectives45619
Ref: #account-subdirectives45814
Node: Account types46127
Ref: #account-types46311
Node: Account display order49357
Ref: #account-display-order49527
Node: Rewriting accounts50678
Ref: #rewriting-accounts50863
Node: Basic aliases51620
Ref: #basic-aliases51766
Node: Regex aliases52470
Ref: #regex-aliases52642
Node: Combining aliases53361
Ref: #combining-aliases53554
Node: Aliases and multiple files54830
Ref: #aliases-and-multiple-files55039
Node: end aliases55618
Ref: #end-aliases55775
Node: Default parent account55876
Ref: #default-parent-account56044
Node: Periodic transactions56928
Ref: #periodic-transactions57103
Node: Periodic rule syntax58975
Ref: #periodic-rule-syntax59181
Node: Two spaces between period expression and description!59885
Ref: #two-spaces-between-period-expression-and-description60204
Node: Forecasting with periodic transactions60888
Ref: #forecasting-with-periodic-transactions61193
Node: Budgeting with periodic transactions63248
Ref: #budgeting-with-periodic-transactions63487
Node: Auto postings63896
Ref: #auto-postings64036
Node: Auto postings and multiple files66215
Ref: #auto-postings-and-multiple-files66419
Node: Auto postings and dates66628
Ref: #auto-postings-and-dates66902
Node: Auto postings and transaction balancing / inferred amounts / balance assertions67077
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67428
Node: Auto posting tags67770
Ref: #auto-posting-tags67985

End Tag Table

View File

@ -682,34 +682,32 @@ FILE FORMAT
Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with
links to more detailed docs.
links to more detailed docs. Note part of this table is hidden when
viewed in a web browser - scroll it sideways to see more.
direc- end di- subdi- purpose can affect (as of
direc- end di- subdi- purpose can affect (as of
tive rective rec- 2018/06)
tives
------------------------------------------------------------------------------------
account any document account names, de- all entries in all
text clare account types & dis- files, before or
account any document account names, de- all entries in all
text clare account types & dis- files, before or
play order after
alias end rewrite account names following in-
aliases line/included en-
tries until end of
current file or end
alias end rewrite account names following entries
aliases until end of cur-
rent file or end
directive
apply end apply prepend a common parent to following in-
account account account names line/included en-
tries until end of
current file or end
apply end apply prepend a common parent to following entries
account account account names until end of cur-
rent file or end
directive
comment end com- ignore part of journal following in-
ment line/included en-
tries until end of
current file or end
comment end com- ignore part of journal following entries
ment until end of cur-
rent file or end
directive
commod- format declare a commodity and its number notation:
ity number notation & display following entries
style in that commodity
in all files; dis-
in all files ; dis-
play style: amounts
of that commodity
in reports
@ -731,32 +729,30 @@ FILE FORMAT
commodity commodity in re-
ports, when -V is
used
Y declare a year for yearless following entries
dates until end of cur-
rent file
Y declare a year for yearless following in-
dates line/included en-
tries until end of
current file
= declare an auto posting all entries in par-
rule, adding postings to ent/current/child
= declare an auto posting all entries in par-
rule, adding postings to ent/current/child
other transactions files (but not sib-
ling files, see
#1212)
And some definitions:
subdi- optional indented directive line immediately following a parent
subdi- optional indented directive line immediately following a parent
rec- directive
tive
number how to interpret numbers when parsing journal entries (the iden-
nota- tity of the decimal separator character). (Currently each com-
nota- tity of the decimal separator character). (Currently each com-
tion modity can have its own notation, even in the same file.)
dis- how to display amounts of a commodity in reports (symbol side
dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places)
style
direc- which entries and (when there are multiple files) which files
direc- which entries and (when there are multiple files) which files
tive are affected by a directive
scope
@ -765,35 +761,35 @@ FILE FORMAT
ports). Some directives have multiple effects.
Directives and multiple files
If you use multiple -f/--file options, or the include directive,
hledger will process multiple input files. But note that directives
If you use multiple -f/--file options, or the include directive,
hledger will process multiple input files. But note that directives
which affect input (see above) typically last only until the end of the
file in which they occur.
This may seem inconvenient, but it's intentional; it makes reports sta-
ble and deterministic, independent of the order of input. Otherwise
you could see different numbers if you happened to write -f options in
a different order, or if you moved includes around while cleaning up
ble and deterministic, independent of the order of input. Otherwise
you could see different numbers if you happened to write -f options in
a different order, or if you moved includes around while cleaning up
your files.
It can be surprising though; for example, it means that alias direc-
It can be surprising though; for example, it means that alias direc-
tives do not affect parent or sibling files (see below).
Comment blocks
A line containing just comment starts a commented region of the file,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include FILEPATH
Only journal files can include, and only journal, timeclock or timedot
Only journal files can include, and only journal, timeclock or timedot
files can be included (not CSV files, currently).
If the file path does not begin with a slash, it is relative to the
If the file path does not begin with a slash, it is relative to the
current file's folder.
A tilde means home directory, eg: include ~/main.journal.
@ -802,17 +798,17 @@ FILE FORMAT
*.journal.
There is limited support for recursive wildcards: **/ (the slash is re-
quired) matches 0 or more subdirectories. It's not super convenient
since you have to avoid include cycles and including directories, but
quired) matches 0 or more subdirectories. It's not super convenient
since you have to avoid include cycles and including directories, but
this can be done, eg: include */**/*.journal.
The path may also be prefixed to force a specific file format, overrid-
ing the file extension (as described in hledger.1 -> Input files): in-
ing the file extension (as described in hledger.1 -> Input files): in-
clude timedot:~/notes/2020*.md.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -834,19 +830,19 @@ FILE FORMAT
Declaring commodities
The commodity directive has several functions:
1. It declares commodities which may be used in the journal. This is
1. It declares commodities which may be used in the journal. This is
currently not enforced, but can serve as documentation.
2. It declares what decimal mark character (period or comma) to expect
when parsing input - useful to disambiguate international number
formats in your data. (Without this, hledger will parse both 1,000
2. It declares what decimal mark character (period or comma) to expect
when parsing input - useful to disambiguate international number
formats in your data. (Without this, hledger will parse both 1,000
and 1.000 as 1).
3. It declares the amount display style to use in output - decimal and
3. It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them
You are likely to run into one of the problems solved by commodity di-
rectives, sooner or later, so it's a good idea to just always use them
to declare your commodities.
A commodity directive is just the word commodity followed by an amount.
@ -859,8 +855,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both
or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both
places.):
; commodity SYMBOL
@ -873,22 +869,22 @@ FILE FORMAT
format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi-
cant. The number must include a decimal mark: either a period or a
cant. The number must include a decimal mark: either a period or a
comma, followed by 0 or more decimal digits.
Note hledger normally uses banker's rounding, so 0.5 displayed with
Note hledger normally uses banker's rounding, so 0.5 displayed with
zero decimal digits is "0". (More at Amount display style.)
Default commodity
The D directive sets a default commodity, to be used for amounts with-
The D directive sets a default commodity, to be used for amounts with-
out a commodity symbol (ie, plain numbers). This commodity will be ap-
plied to all subsequent commodity-less amounts, or until the next D di-
rective. (Note, this is different from Ledger's D.)
For compatibility/historical reasons, D also acts like a commodity di-
For compatibility/historical reasons, D also acts like a commodity di-
rective, setting the commodity's display style (for output) and decimal
mark (for parsing input). As with commodity, the amount must always be
written with a decimal mark (period or comma). If both directives are
written with a decimal mark (period or comma). If both directives are
used, commodity's style takes precedence.
The syntax is D AMOUNT. Eg:
@ -902,9 +898,9 @@ FILE FORMAT
b
Declaring market prices
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@ -915,16 +911,16 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, giving the price in commodity B of one unit of commodity A.
These two market price directives say that one euro was worth 1.35 US
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40
The -V, -X and --value flags use these market prices to show amount
The -V, -X and --value flags use these market prices to show amount
values in another commodity. See Valuation.
Declaring accounts
@ -934,20 +930,20 @@ FILE FORMAT
o They can document your intended chart of accounts, providing a refer-
ence.
o They can store extra information about accounts (account numbers,
o They can store extra information about accounts (account numbers,
notes, etc.)
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
o They control account display order in reports, allowing non-alpha-
o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command, hledger-
o They help with account name completion in the add command, hledger-
iadd, hledger-web, ledger-mode etc.
The simplest form is just the word account followed by a hledger-style
The simplest form is just the word account followed by a hledger-style
account name, eg:
account assets:bank:checking
@ -955,7 +951,7 @@ FILE FORMAT
Account comments
Comments, beginning with a semicolon, can be added:
o on the same line, after two or more spaces (because ; is allowed in
o on the same line, after two or more spaces (because ; is allowed in
account names)
o on the next lines, indented
@ -969,7 +965,7 @@ FILE FORMAT
Same-line comments are not supported by Ledger, or hledger <1.13.
Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just
We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
@ -988,21 +984,21 @@ FILE FORMAT
Asset, Liability, Equity, Revenue, Expense.
These account types are important for controlling which accounts appear
in the balancesheet, balancesheetequity, incomestatement reports (and
in the balancesheet, balancesheetequity, incomestatement reports (and
probably for other things in future).
Additionally, we recognise the Cash type, which is also an Asset, and
which causes accounts to appear in the cashflow report. ("Cash" here
means liquid assets, eg bank balances but typically not investments or
Additionally, we recognise the Cash type, which is also an Asset, and
which causes accounts to appear in the cashflow report. ("Cash" here
means liquid assets, eg bank balances but typically not investments or
receivables.)
Declaring account types
Generally, to make these reports work you should declare your top-level
accounts and their types, using account directives with type: tags.
The tag's value should be one of: Asset, Liability, Equity, Revenue,
Expense, Cash, A, L, E, R, X, C (all case insensitive). The type is
inherited by all subaccounts except where they override it. Here's a
The tag's value should be one of: Asset, Liability, Equity, Revenue,
Expense, Cash, A, L, E, R, X, C (all case insensitive). The type is
inherited by all subaccounts except where they override it. Here's a
complete example:
account assets ; type: Asset
@ -1014,8 +1010,8 @@ FILE FORMAT
account expenses ; type: Expense
Auto-detected account types
If you happen to use common english top-level account names, you may
not need to declare account types, as they will be detected automati-
If you happen to use common english top-level account names, you may
not need to declare account types, as they will be detected automati-
cally using the following rules:
If name matches regular account type is:
@ -1028,7 +1024,7 @@ FILE FORMAT
^(income|revenue)s?(:|$) Revenue
^expenses?(:|$) Expense
If account type is Asset and name does not contain regu- account type
If account type is Asset and name does not contain regu- account type
lar expression: is:
--------------------------------------------------------------------------
(investment|receivable|:A/R|:fixed) Cash
@ -1038,9 +1034,9 @@ FILE FORMAT
Interference from auto-detected account types
If you assign any account type, it's a good idea to assign all of them,
to prevent any confusion from mixing declared and auto-detected types.
Although it's unlikely to happen in real life, here's an example: with
the following journal, balancesheetequity shows "liabilities" in both
to prevent any confusion from mixing declared and auto-detected types.
Although it's unlikely to happen in real life, here's an example: with
the following journal, balancesheetequity shows "liabilities" in both
Liabilities and Equity sections. Declaring another account as type:Li-
ability would fix it:
@ -1052,8 +1048,8 @@ FILE FORMAT
equity -2
Old account type syntax
In some hledger journals you might instead see this old syntax (the
letters ALERX, separated from the account name by two or more spaces);
In some hledger journals you might instead see this old syntax (the
letters ALERX, separated from the account name by two or more spaces);
this is deprecated and may be removed soon:
account assets A
@ -1063,8 +1059,8 @@ FILE FORMAT
account expenses X
Account display order
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal:
@ -1086,20 +1082,20 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means:
o you will sometimes declare parent accounts (eg account other above)
o you will sometimes declare parent accounts (eg account other above)
that you don't intend to post to, just to customize their display or-
der
o sibling accounts stay together (you couldn't display x:y in between
o sibling accounts stay together (you couldn't display x:y in between
a:b and a:c).
Rewriting accounts
@ -1117,14 +1113,14 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or hledger-
do not affect account names being entered via hledger add or hledger-
web.
See also Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -1132,49 +1128,49 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
OLD and NEW are case sensitive full account names. hledger will re-
place any occurrence of the old account name with the new one. Subac-
counts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking
; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
There is also a more powerful variant that uses a regular expression,
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
space.
Combining aliases
You can define as many aliases as you like, using journal directives
You can define as many aliases as you like, using journal directives
and/or command line options.
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases.
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
In such cases it can be important to understand which aliases will be
applied and in which order. For (each account name in) each journal
entry, we apply:
1. alias directives preceding the journal entry, most recently parsed
1. alias directives preceding the journal entry, most recently parsed
first (ie, reading upward from the journal entry, bottom to top)
2. --alias options, in the order they appeared on the command line
2. --alias options, in the order they appeared on the command line
(left to right).
In other words, for (an account name in) a given journal entry:
@ -1185,20 +1181,20 @@ FILE FORMAT
o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order.
In case of trouble, adding --debug=6 to the command line will show
In case of trouble, adding --debug=6 to the command line will show
which aliases are being applied when.
Aliases and multiple files
As explained at Directives and multiple files, alias directives do not
As explained at Directives and multiple files, alias directives do not
affect parent or sibling files. Eg in this command,
hledger -f a.aliases -f b.journal
account aliases defined in a.aliases will not affect b.journal. In-
account aliases defined in a.aliases will not affect b.journal. In-
cluding the aliases doesn't work either:
include a.aliases
@ -1220,14 +1216,14 @@ FILE FORMAT
include c.journal ; also affected
end aliases
You can clear (forget) all currently defined aliases with the end
You can clear (forget) all currently defined aliases with the end
aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
You can specify a parent account which will be prepended to all ac-
counts within a section of the journal. Use the apply account and end
apply account directives like so:
apply account home
@ -1244,7 +1240,7 @@ FILE FORMAT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -1253,50 +1249,50 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
account.
Periodic transactions
Periodic transaction rules describe transactions that recur. They al-
low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal,
and it's easy to try out different forecasts. Secondly, they are also
Periodic transaction rules describe transactions that recur. They al-
low hledger to generate temporary future transactions to help with
forecasting, so you don't have to write out each one in the journal,
and it's easy to try out different forecasts. Secondly, they are also
used to define the budgets shown in budget reports.
Periodic transactions can be a little tricky, so before you use them,
Periodic transactions can be a little tricky, so before you use them,
read this whole section - or at least these tips:
1. Two spaces accidentally added or omitted will cause you trouble -
1. Two spaces accidentally added or omitted will cause you trouble -
read about this below.
2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast
2. For troubleshooting, show the generated transactions with hledger
print --forecast tag:generated or hledger register --forecast
tag:generated.
3. Forecasted transactions will begin only after the last non-fore-
3. Forecasted transactions will begin only after the last non-fore-
casted transaction's date.
4. Forecasted transactions will end 6 months from today, by default.
4. Forecasted transactions will end 6 months from today, by default.
See below for the exact start/end rules.
5. period expressions can be tricky. Their documentation needs im-
5. period expressions can be tricky. Their documentation needs im-
provement, but is worth studying.
6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
6. Some period expressions with a repeating interval must begin on a
natural boundary of that interval. Eg in weekly from DATE, DATE
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
error.
7. Other period expressions with an interval are automatically expanded
to cover a whole number of that interval. (This is done to improve
to cover a whole number of that interval. (This is done to improve
reports, but it also affects periodic transactions. Yes, it's a bit
inconsistent with the above.) Eg: ~ every 10th day of month from
2020/01, which is equivalent to ~ every 10th day of month from
inconsistent with the above.) Eg: ~ every 10th day of month from
2020/01, which is equivalent to ~ every 10th day of month from
2020/01/01, will be adjusted to start on 2019/12/10.
Periodic rule syntax
@ -1308,17 +1304,17 @@ FILE FORMAT
expenses:rent $2000
assets:bank:checking
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg monthly from
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg monthly from
2018/1/1 is valid, but monthly from 2018/1/15 is not.
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
Partial or relative dates (M/D, D, tomorrow, last week) in the period
expression can work (useful or not). They will be relative to today's
date, unless a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
Two spaces between period expression and description!
If the period expression is followed by a transaction description,
If the period expression is followed by a transaction description,
these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example:
@ -1332,67 +1328,67 @@ FILE FORMAT
So,
o Do write two spaces between your period expression and your transac-
o Do write two spaces between your period expression and your transac-
tion description, if any.
o Don't accidentally write two spaces in the middle of your period ex-
o Don't accidentally write two spaces in the middle of your period ex-
pression.
Forecasting with periodic transactions
The --forecast flag activates any periodic transaction rules in the
journal. They will generate temporary recurring transactions, which
are not saved in the journal, but will appear in all reports (eg
The --forecast flag activates any periodic transaction rules in the
journal. They will generate temporary recurring transactions, which
are not saved in the journal, but will appear in all reports (eg
print). This can be useful for estimating balances into the future, or
experimenting with different scenarios. Or, it can be used as a data
experimenting with different scenarios. Or, it can be used as a data
entry aid: describe recurring transactions, and every so often copy the
output of print --forecast into the journal.
These transactions will have an extra tag indicating which periodic
These transactions will have an extra tag indicating which periodic
rule generated them: generated-transaction:~ PERIODICEXPR. And a simi-
lar, hidden tag (beginning with an underscore) which, because it's
never displayed by print, can be used to match transactions generated
lar, hidden tag (beginning with an underscore) which, because it's
never displayed by print, can be used to match transactions generated
"just now": _generated-transaction:~ PERIODICEXPR.
Periodic transactions are generated within some forecast period. By
Periodic transactions are generated within some forecast period. By
default, this
o begins on the later of
o the report start date if specified with -b/-p/date:
o the day after the latest normal (non-periodic) transaction in the
o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
o ends on the report end date if specified with -e/-p/date:, or 6
o ends on the report end date if specified with -e/-p/date:, or 6
months (180 days) from today.
This means that periodic transactions will begin only after the latest
recorded transaction. And a recorded transaction dated in the future
can prevent generation of periodic transactions. (You can avoid that
This means that periodic transactions will begin only after the latest
recorded transaction. And a recorded transaction dated in the future
can prevent generation of periodic transactions. (You can avoid that
by writing the future transaction as a one-time periodic rule instead -
put tilde before the date, eg ~ YYYY-MM-DD ...).
Or, you can set your own arbitrary "forecast period", which can overlap
recorded transactions, and need not be in the future, by providing an
option argument, like --forecast=PERIODEXPR. Note the equals sign is
recorded transactions, and need not be in the future, by providing an
option argument, like --forecast=PERIODEXPR. Note the equals sign is
required, a space won't work. PERIODEXPR is a period expression, which
can specify the start date, end date, or both, like in a date: query.
(See also hledger.1 -> Report start & end date). Some examples:
can specify the start date, end date, or both, like in a date: query.
(See also hledger.1 -> Report start & end date). Some examples:
--forecast=202001-202004, --forecast=jan-, --forecast=2020.
Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
See also: Budgeting and Forecasting.
Auto postings
"Automated postings" or "auto postings" are extra postings which get
added automatically to transactions which match certain queries, de-
"Automated postings" or "auto postings" are extra postings which get
added automatically to transactions which match certain queries, de-
fined by "auto posting rules", when you use the --auto flag.
An auto posting rule looks a bit like a transaction:
@ -1402,27 +1398,27 @@ FILE FORMAT
...
ACCOUNT [AMOUNT]
except the first line is an equals sign (mnemonic: = suggests match-
ing), followed by a query (which matches existing postings), and each
"posting" line describes a posting to be generated, and the posting
except the first line is an equals sign (mnemonic: = suggests match-
ing), followed by a query (which matches existing postings), and each
"posting" line describes a posting to be generated, and the posting
amounts can be:
o a normal amount with a commodity symbol, eg $2. This will be used
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
o a numeric multiplier, eg *2 (a star followed by a number N). The
o a numeric multiplier, eg *2 (a star followed by a number N). The
matched posting's amount (and total price, if any) will be multiplied
by N.
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
Any query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second
Any query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second
query term below:
= expenses:groceries 'expenses:dining out'
@ -1461,24 +1457,24 @@ FILE FORMAT
Auto postings and multiple files
An auto posting rule can affect any transaction in the current file, or
in any parent file or child file. Note, currently it will not affect
in any parent file or child file. Note, currently it will not affect
sibling files (when multiple -f/--file are used - see #1212).
Auto postings and dates
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also
A posting date (or secondary date) in the matched posting, or (taking
precedence) a posting date in the auto posting rule itself, will also
be used in the generated posting.
Auto postings and transaction balancing / inferred amounts / balance asser-
tions
Currently, auto postings are added:
o after missing amounts are inferred, and transactions are checked for
o after missing amounts are inferred, and transactions are checked for
balancedness,
o but before balance assertions are checked.
Note this means that journal entries must be balanced both before and
Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893
for background.
@ -1488,11 +1484,11 @@ FILE FORMAT
o generated-posting:= QUERY - shows this was generated by an auto post-
ing rule, and the query
o _generated-posting:= QUERY - a hidden tag, which does not appear in
o _generated-posting:= QUERY - a hidden tag, which does not appear in
hledger's output. This can be used to match postings generated "just
now", rather than generated in the past and saved to the journal.
Also, any transaction that has been changed by auto posting rules will
Also, any transaction that has been changed by auto posting rules will
have these tags added:
o modified: - this transaction was modified
@ -1503,7 +1499,7 @@ FILE FORMAT
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)
@ -1517,7 +1513,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)
@ -1525,4 +1521,4 @@ SEE ALSO
hledger 1.19.99 September 2020 hledger_journal(5)
hledger 1.19.99 October 2020 hledger_journal(5)

View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals"
.TH "hledger_timeclock" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals"

View File

@ -78,4 +78,4 @@ SEE ALSO
hledger 1.19.99 September 2020 hledger_timeclock(5)
hledger 1.19.99 October 2020 hledger_timeclock(5)

View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "September 2020" "hledger 1.19.99" "hledger User Manuals"
.TH "hledger_timedot" "5" "October 2020" "hledger 1.19.99" "hledger User Manuals"

View File

@ -161,4 +161,4 @@ SEE ALSO
hledger 1.19.99 September 2020 hledger_timedot(5)
hledger 1.19.99 October 2020 hledger_timedot(5)

View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.19.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{September 2020}})m4_dnl
m4_define({{_monthyear_}}, {{October 2020}})m4_dnl

View File

@ -1,5 +1,5 @@
.TH "hledger-ui" "1" "September 2020" "hledger-ui 1.19.99" "hledger User Manuals"
.TH "hledger-ui" "1" "October 2020" "hledger-ui 1.19.99" "hledger User Manuals"

View File

@ -456,4 +456,4 @@ SEE ALSO
hledger-ui 1.19.99 September 2020 hledger-ui(1)
hledger-ui 1.19.99 October 2020 hledger-ui(1)

View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.19.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{September 2020}})m4_dnl
m4_define({{_monthyear_}}, {{October 2020}})m4_dnl

View File

@ -1,5 +1,5 @@
.TH "hledger-web" "1" "September 2020" "hledger-web 1.19.99" "hledger User Manuals"
.TH "hledger-web" "1" "October 2020" "hledger-web 1.19.99" "hledger User Manuals"

View File

@ -546,4 +546,4 @@ SEE ALSO
hledger-web 1.19.99 September 2020 hledger-web(1)
hledger-web 1.19.99 October 2020 hledger-web(1)

View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.19.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{September 2020}})m4_dnl
m4_define({{_monthyear_}}, {{October 2020}})m4_dnl

View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger" "1" "September 2020" "hledger 1.19.99" "hledger User Manuals"
.TH "hledger" "1" "October 2020" "hledger 1.19.99" "hledger User Manuals"

View File

@ -3460,4 +3460,4 @@ SEE ALSO
hledger 1.19.99 September 2020 hledger(1)
hledger 1.19.99 October 2020 hledger(1)