;update manuals
This commit is contained in:
parent
3fb3c9c19f
commit
f0db3fb157
@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
|
|||||||
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
||||||
m4_dnl
|
m4_dnl
|
||||||
m4_dnl Date to show in man pages. Updated by make setdate.
|
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
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
.\"t
|
.\"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"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -922,4 +922,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger 1.19.99 September 2020 hledger_csv(5)
|
hledger 1.19.99 October 2020 hledger_csv(5)
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
.\"t
|
.\"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,
|
Directives\[aq] behaviour and interactions can get a little bit complex,
|
||||||
so here is a table summarising the directives and their effects, with
|
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.
|
||||||
.PP
|
.PP
|
||||||
.TS
|
.TS
|
||||||
tab(@);
|
tab(@);
|
||||||
@ -984,8 +986,7 @@ T}@T{
|
|||||||
T}@T{
|
T}@T{
|
||||||
rewrite account names
|
rewrite account names
|
||||||
T}@T{
|
T}@T{
|
||||||
following inline/included entries until end of current file or end
|
following entries until end of current file or end directive
|
||||||
directive
|
|
||||||
T}
|
T}
|
||||||
T{
|
T{
|
||||||
\f[C]apply account\f[R]
|
\f[C]apply account\f[R]
|
||||||
@ -995,8 +996,7 @@ T}@T{
|
|||||||
T}@T{
|
T}@T{
|
||||||
prepend a common parent to account names
|
prepend a common parent to account names
|
||||||
T}@T{
|
T}@T{
|
||||||
following inline/included entries until end of current file or end
|
following entries until end of current file or end directive
|
||||||
directive
|
|
||||||
T}
|
T}
|
||||||
T{
|
T{
|
||||||
\f[C]comment\f[R]
|
\f[C]comment\f[R]
|
||||||
@ -1006,8 +1006,7 @@ T}@T{
|
|||||||
T}@T{
|
T}@T{
|
||||||
ignore part of journal
|
ignore part of journal
|
||||||
T}@T{
|
T}@T{
|
||||||
following inline/included entries until end of current file or end
|
following entries until end of current file or end directive
|
||||||
directive
|
|
||||||
T}
|
T}
|
||||||
T{
|
T{
|
||||||
\f[C]commodity\f[R]
|
\f[C]commodity\f[R]
|
||||||
@ -1017,7 +1016,7 @@ T}@T{
|
|||||||
T}@T{
|
T}@T{
|
||||||
declare a commodity and its number notation & display style
|
declare a commodity and its number notation & display style
|
||||||
T}@T{
|
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
|
display style: amounts of that commodity in reports
|
||||||
T}
|
T}
|
||||||
T{
|
T{
|
||||||
@ -1057,7 +1056,7 @@ T}@T{
|
|||||||
T}@T{
|
T}@T{
|
||||||
declare a year for yearless dates
|
declare a year for yearless dates
|
||||||
T}@T{
|
T}@T{
|
||||||
following inline/included entries until end of current file
|
following entries until end of current file
|
||||||
T}
|
T}
|
||||||
T{
|
T{
|
||||||
\f[C]=\f[R]
|
\f[C]=\f[R]
|
||||||
|
|||||||
@ -888,7 +888,8 @@ some differences between hledger versions).
|
|||||||
|
|
||||||
Directives' behaviour and interactions can get a little bit complex,
|
Directives' behaviour and interactions can get a little bit complex,
|
||||||
so here is a table summarising the directives and their effects, with
|
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
|
directiveend subdirectivespurpose can affect (as of
|
||||||
directive 2018/06)
|
directive 2018/06)
|
||||||
@ -896,25 +897,22 @@ directiveend subdirectivespurpose can affect (as of
|
|||||||
'account' any document account names, all entries in
|
'account' any document account names, all entries in
|
||||||
text declare account types & all files, before
|
text declare account types & all files, before
|
||||||
display order or after
|
display order or after
|
||||||
'alias' 'end rewrite account names following
|
'alias' 'end rewrite account names following entries
|
||||||
aliases' inline/included
|
aliases' until end of
|
||||||
entries until end
|
current file or
|
||||||
of current file
|
end directive
|
||||||
or end directive
|
'apply 'end prepend a common parent to following entries
|
||||||
'apply 'end prepend a common parent to following
|
account' apply account names until end of
|
||||||
account' apply account names inline/included
|
account' current file or
|
||||||
account' entries until end
|
end directive
|
||||||
of current file
|
'comment''end ignore part of journal following entries
|
||||||
or end directive
|
comment' until end of
|
||||||
'comment''end ignore part of journal following
|
current file or
|
||||||
comment' inline/included
|
end directive
|
||||||
entries until end
|
|
||||||
of current file
|
|
||||||
or end directive
|
|
||||||
'commodity' 'format'declare a commodity and its number notation:
|
'commodity' 'format'declare a commodity and its number notation:
|
||||||
number notation & display following entries
|
number notation & display following entries
|
||||||
style in that commodity
|
style in that commodity
|
||||||
in all files;
|
in all files ;
|
||||||
display style:
|
display style:
|
||||||
amounts of that
|
amounts of that
|
||||||
commodity in
|
commodity in
|
||||||
@ -940,10 +938,9 @@ account' apply account names inline/included
|
|||||||
a commodity commodity in
|
a commodity commodity in
|
||||||
reports, when -V
|
reports, when -V
|
||||||
is used
|
is used
|
||||||
'Y' declare a year for yearless following
|
'Y' declare a year for yearless following entries
|
||||||
dates inline/included
|
dates until end of
|
||||||
entries until end
|
current file
|
||||||
of current file
|
|
||||||
'=' declare an auto posting all entries in
|
'=' declare an auto posting all entries in
|
||||||
rule, adding postings to parent/current/child
|
rule, adding postings to parent/current/child
|
||||||
other transactions files (but not
|
other transactions files (but not
|
||||||
@ -1924,64 +1921,64 @@ Node: Balance assignments and prices30866
|
|||||||
Ref: #balance-assignments-and-prices31038
|
Ref: #balance-assignments-and-prices31038
|
||||||
Node: Directives31262
|
Node: Directives31262
|
||||||
Ref: #directives31421
|
Ref: #directives31421
|
||||||
Node: Directives and multiple files37112
|
Node: Directives and multiple files36919
|
||||||
Ref: #directives-and-multiple-files37295
|
Ref: #directives-and-multiple-files37102
|
||||||
Node: Comment blocks37959
|
Node: Comment blocks37766
|
||||||
Ref: #comment-blocks38142
|
Ref: #comment-blocks37949
|
||||||
Node: Including other files38318
|
Node: Including other files38125
|
||||||
Ref: #including-other-files38498
|
Ref: #including-other-files38305
|
||||||
Node: Default year39422
|
Node: Default year39229
|
||||||
Ref: #default-year39591
|
Ref: #default-year39398
|
||||||
Node: Declaring commodities39998
|
Node: Declaring commodities39805
|
||||||
Ref: #declaring-commodities40181
|
Ref: #declaring-commodities39988
|
||||||
Node: Default commodity41987
|
Node: Default commodity41794
|
||||||
Ref: #default-commodity42173
|
Ref: #default-commodity41980
|
||||||
Node: Declaring market prices43062
|
Node: Declaring market prices42869
|
||||||
Ref: #declaring-market-prices43257
|
Ref: #declaring-market-prices43064
|
||||||
Node: Declaring accounts44114
|
Node: Declaring accounts43921
|
||||||
Ref: #declaring-accounts44300
|
Ref: #declaring-accounts44107
|
||||||
Node: Account comments45225
|
Node: Account comments45032
|
||||||
Ref: #account-comments45388
|
Ref: #account-comments45195
|
||||||
Node: Account subdirectives45812
|
Node: Account subdirectives45619
|
||||||
Ref: #account-subdirectives46007
|
Ref: #account-subdirectives45814
|
||||||
Node: Account types46320
|
Node: Account types46127
|
||||||
Ref: #account-types46504
|
Ref: #account-types46311
|
||||||
Node: Account display order49550
|
Node: Account display order49357
|
||||||
Ref: #account-display-order49720
|
Ref: #account-display-order49527
|
||||||
Node: Rewriting accounts50871
|
Node: Rewriting accounts50678
|
||||||
Ref: #rewriting-accounts51056
|
Ref: #rewriting-accounts50863
|
||||||
Node: Basic aliases51813
|
Node: Basic aliases51620
|
||||||
Ref: #basic-aliases51959
|
Ref: #basic-aliases51766
|
||||||
Node: Regex aliases52663
|
Node: Regex aliases52470
|
||||||
Ref: #regex-aliases52835
|
Ref: #regex-aliases52642
|
||||||
Node: Combining aliases53554
|
Node: Combining aliases53361
|
||||||
Ref: #combining-aliases53747
|
Ref: #combining-aliases53554
|
||||||
Node: Aliases and multiple files55023
|
Node: Aliases and multiple files54830
|
||||||
Ref: #aliases-and-multiple-files55232
|
Ref: #aliases-and-multiple-files55039
|
||||||
Node: end aliases55811
|
Node: end aliases55618
|
||||||
Ref: #end-aliases55968
|
Ref: #end-aliases55775
|
||||||
Node: Default parent account56069
|
Node: Default parent account55876
|
||||||
Ref: #default-parent-account56237
|
Ref: #default-parent-account56044
|
||||||
Node: Periodic transactions57121
|
Node: Periodic transactions56928
|
||||||
Ref: #periodic-transactions57296
|
Ref: #periodic-transactions57103
|
||||||
Node: Periodic rule syntax59168
|
Node: Periodic rule syntax58975
|
||||||
Ref: #periodic-rule-syntax59374
|
Ref: #periodic-rule-syntax59181
|
||||||
Node: Two spaces between period expression and description!60078
|
Node: Two spaces between period expression and description!59885
|
||||||
Ref: #two-spaces-between-period-expression-and-description60397
|
Ref: #two-spaces-between-period-expression-and-description60204
|
||||||
Node: Forecasting with periodic transactions61081
|
Node: Forecasting with periodic transactions60888
|
||||||
Ref: #forecasting-with-periodic-transactions61386
|
Ref: #forecasting-with-periodic-transactions61193
|
||||||
Node: Budgeting with periodic transactions63441
|
Node: Budgeting with periodic transactions63248
|
||||||
Ref: #budgeting-with-periodic-transactions63680
|
Ref: #budgeting-with-periodic-transactions63487
|
||||||
Node: Auto postings64089
|
Node: Auto postings63896
|
||||||
Ref: #auto-postings64229
|
Ref: #auto-postings64036
|
||||||
Node: Auto postings and multiple files66408
|
Node: Auto postings and multiple files66215
|
||||||
Ref: #auto-postings-and-multiple-files66612
|
Ref: #auto-postings-and-multiple-files66419
|
||||||
Node: Auto postings and dates66821
|
Node: Auto postings and dates66628
|
||||||
Ref: #auto-postings-and-dates67095
|
Ref: #auto-postings-and-dates66902
|
||||||
Node: Auto postings and transaction balancing / inferred amounts / balance assertions67270
|
Node: Auto postings and transaction balancing / inferred amounts / balance assertions67077
|
||||||
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67621
|
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67428
|
||||||
Node: Auto posting tags67963
|
Node: Auto posting tags67770
|
||||||
Ref: #auto-posting-tags68178
|
Ref: #auto-posting-tags67985
|
||||||
|
|
||||||
End Tag Table
|
End Tag Table
|
||||||
|
|
||||||
|
|||||||
@ -682,34 +682,32 @@ FILE FORMAT
|
|||||||
|
|
||||||
Directives' behaviour and interactions can get a little bit complex, so
|
Directives' behaviour and interactions can get a little bit complex, so
|
||||||
here is a table summarising the directives and their effects, with
|
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)
|
tive rective rec- 2018/06)
|
||||||
tives
|
tives
|
||||||
------------------------------------------------------------------------------------
|
------------------------------------------------------------------------------------
|
||||||
account any document account names, de- all entries in all
|
account any document account names, de- all entries in all
|
||||||
text clare account types & dis- files, before or
|
text clare account types & dis- files, before or
|
||||||
play order after
|
play order after
|
||||||
alias end rewrite account names following in-
|
alias end rewrite account names following entries
|
||||||
aliases line/included en-
|
aliases until end of cur-
|
||||||
tries until end of
|
rent file or end
|
||||||
current file or end
|
|
||||||
directive
|
directive
|
||||||
apply end apply prepend a common parent to following in-
|
apply end apply prepend a common parent to following entries
|
||||||
account account account names line/included en-
|
account account account names until end of cur-
|
||||||
tries until end of
|
rent file or end
|
||||||
current file or end
|
|
||||||
directive
|
directive
|
||||||
comment end com- ignore part of journal following in-
|
comment end com- ignore part of journal following entries
|
||||||
ment line/included en-
|
ment until end of cur-
|
||||||
tries until end of
|
rent file or end
|
||||||
current file or end
|
|
||||||
directive
|
directive
|
||||||
commod- format declare a commodity and its number notation:
|
commod- format declare a commodity and its number notation:
|
||||||
ity number notation & display following entries
|
ity number notation & display following entries
|
||||||
style in that commodity
|
style in that commodity
|
||||||
in all files; dis-
|
in all files ; dis-
|
||||||
play style: amounts
|
play style: amounts
|
||||||
of that commodity
|
of that commodity
|
||||||
in reports
|
in reports
|
||||||
@ -731,32 +729,30 @@ FILE FORMAT
|
|||||||
commodity commodity in re-
|
commodity commodity in re-
|
||||||
ports, when -V is
|
ports, when -V is
|
||||||
used
|
used
|
||||||
|
Y declare a year for yearless following entries
|
||||||
|
dates until end of cur-
|
||||||
|
rent file
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
= declare an auto posting all entries in par-
|
||||||
Y declare a year for yearless following in-
|
rule, adding postings to ent/current/child
|
||||||
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
|
|
||||||
other transactions files (but not sib-
|
other transactions files (but not sib-
|
||||||
ling files, see
|
ling files, see
|
||||||
#1212)
|
#1212)
|
||||||
|
|
||||||
And some definitions:
|
And some definitions:
|
||||||
|
|
||||||
subdi- optional indented directive line immediately following a parent
|
subdi- optional indented directive line immediately following a parent
|
||||||
rec- directive
|
rec- directive
|
||||||
tive
|
tive
|
||||||
number how to interpret numbers when parsing journal entries (the iden-
|
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.)
|
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)
|
play and spacing, digit groups, decimal separator, decimal places)
|
||||||
style
|
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
|
tive are affected by a directive
|
||||||
scope
|
scope
|
||||||
|
|
||||||
@ -765,35 +761,35 @@ FILE FORMAT
|
|||||||
ports). Some directives have multiple effects.
|
ports). Some directives have multiple effects.
|
||||||
|
|
||||||
Directives and multiple files
|
Directives and multiple files
|
||||||
If you use multiple -f/--file options, or the include directive,
|
If you use multiple -f/--file options, or the include directive,
|
||||||
hledger will process multiple input files. But note that directives
|
hledger will process multiple input files. But note that directives
|
||||||
which affect input (see above) typically last only until the end of the
|
which affect input (see above) typically last only until the end of the
|
||||||
file in which they occur.
|
file in which they occur.
|
||||||
|
|
||||||
This may seem inconvenient, but it's intentional; it makes reports sta-
|
This may seem inconvenient, but it's intentional; it makes reports sta-
|
||||||
ble and deterministic, independent of the order of input. Otherwise
|
ble and deterministic, independent of the order of input. Otherwise
|
||||||
you could see different numbers if you happened to write -f options in
|
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
|
a different order, or if you moved includes around while cleaning up
|
||||||
your files.
|
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).
|
tives do not affect parent or sibling files (see below).
|
||||||
|
|
||||||
Comment blocks
|
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)
|
and a line containing just end comment (or the end of the current file)
|
||||||
ends it. See also comments.
|
ends it. See also comments.
|
||||||
|
|
||||||
Including other files
|
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:
|
directive, like this:
|
||||||
|
|
||||||
include FILEPATH
|
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).
|
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.
|
current file's folder.
|
||||||
|
|
||||||
A tilde means home directory, eg: include ~/main.journal.
|
A tilde means home directory, eg: include ~/main.journal.
|
||||||
@ -802,17 +798,17 @@ FILE FORMAT
|
|||||||
*.journal.
|
*.journal.
|
||||||
|
|
||||||
There is limited support for recursive wildcards: **/ (the slash is re-
|
There is limited support for recursive wildcards: **/ (the slash is re-
|
||||||
quired) matches 0 or more subdirectories. It's not super convenient
|
quired) matches 0 or more subdirectories. It's not super convenient
|
||||||
since you have to avoid include cycles and including directories, but
|
since you have to avoid include cycles and including directories, but
|
||||||
this can be done, eg: include */**/*.journal.
|
this can be done, eg: include */**/*.journal.
|
||||||
|
|
||||||
The path may also be prefixed to force a specific file format, overrid-
|
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.
|
clude timedot:~/notes/2020*.md.
|
||||||
|
|
||||||
Default year
|
Default year
|
||||||
You can set a default year to be used for subsequent dates which don't
|
You can set a default year to be used for subsequent dates which don't
|
||||||
specify a year. This is a line beginning with Y followed by the year.
|
specify a year. This is a line beginning with Y followed by the year.
|
||||||
Eg:
|
Eg:
|
||||||
|
|
||||||
Y2009 ; set default year to 2009
|
Y2009 ; set default year to 2009
|
||||||
@ -834,19 +830,19 @@ FILE FORMAT
|
|||||||
Declaring commodities
|
Declaring commodities
|
||||||
The commodity directive has several functions:
|
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.
|
currently not enforced, but can serve as documentation.
|
||||||
|
|
||||||
2. It declares what decimal mark character (period or comma) to expect
|
2. It declares what decimal mark character (period or comma) to expect
|
||||||
when parsing input - useful to disambiguate international number
|
when parsing input - useful to disambiguate international number
|
||||||
formats in your data. (Without this, hledger will parse both 1,000
|
formats in your data. (Without this, hledger will parse both 1,000
|
||||||
and 1.000 as 1).
|
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.
|
digit group marks, number of decimal places, symbol placement etc.
|
||||||
|
|
||||||
You are likely to run into one of the problems solved by commodity di-
|
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
|
rectives, sooner or later, so it's a good idea to just always use them
|
||||||
to declare your commodities.
|
to declare your commodities.
|
||||||
|
|
||||||
A commodity directive is just the word commodity followed by an amount.
|
A commodity directive is just the word commodity followed by an amount.
|
||||||
@ -859,8 +855,8 @@ FILE FORMAT
|
|||||||
; separating thousands with comma.
|
; separating thousands with comma.
|
||||||
commodity 1,000.0000 AAAA
|
commodity 1,000.0000 AAAA
|
||||||
|
|
||||||
or on multiple lines, using the "format" subdirective. (In this case
|
or on multiple lines, using the "format" subdirective. (In this case
|
||||||
the commodity symbol appears twice and should be the same in both
|
the commodity symbol appears twice and should be the same in both
|
||||||
places.):
|
places.):
|
||||||
|
|
||||||
; commodity SYMBOL
|
; commodity SYMBOL
|
||||||
@ -873,22 +869,22 @@ FILE FORMAT
|
|||||||
format INR 1,00,00,000.00
|
format INR 1,00,00,000.00
|
||||||
|
|
||||||
The quantity of the amount does not matter; only the format is signifi-
|
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.
|
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.)
|
zero decimal digits is "0". (More at Amount display style.)
|
||||||
|
|
||||||
Default commodity
|
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-
|
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-
|
plied to all subsequent commodity-less amounts, or until the next D di-
|
||||||
rective. (Note, this is different from Ledger's D.)
|
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
|
rective, setting the commodity's display style (for output) and decimal
|
||||||
mark (for parsing input). As with commodity, the amount must always be
|
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.
|
used, commodity's style takes precedence.
|
||||||
|
|
||||||
The syntax is D AMOUNT. Eg:
|
The syntax is D AMOUNT. Eg:
|
||||||
@ -902,9 +898,9 @@ FILE FORMAT
|
|||||||
b
|
b
|
||||||
|
|
||||||
Declaring market prices
|
Declaring market prices
|
||||||
The P directive declares a market price, which is an exchange rate be-
|
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
|
tween two commodities on a certain date. (In Ledger, they are called
|
||||||
"historical prices".) These are often obtained from a stock exchange,
|
"historical prices".) These are often obtained from a stock exchange,
|
||||||
cryptocurrency exchange, or the foreign exchange market.
|
cryptocurrency exchange, or the foreign exchange market.
|
||||||
|
|
||||||
Here is the format:
|
Here is the format:
|
||||||
@ -915,16 +911,16 @@ FILE FORMAT
|
|||||||
|
|
||||||
o COMMODITYA is the symbol of the commodity being priced
|
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.
|
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:
|
dollars during 2009, and $1.40 from 2010 onward:
|
||||||
|
|
||||||
P 2009/1/1 EUR $1.35
|
P 2009/1/1 EUR $1.35
|
||||||
P 2010/1/1 EUR $1.40
|
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.
|
values in another commodity. See Valuation.
|
||||||
|
|
||||||
Declaring accounts
|
Declaring accounts
|
||||||
@ -934,20 +930,20 @@ FILE FORMAT
|
|||||||
o They can document your intended chart of accounts, providing a refer-
|
o They can document your intended chart of accounts, providing a refer-
|
||||||
ence.
|
ence.
|
||||||
|
|
||||||
o They can store extra information about accounts (account numbers,
|
o They can store extra information about accounts (account numbers,
|
||||||
notes, etc.)
|
notes, etc.)
|
||||||
|
|
||||||
o They can help hledger know your accounts' types (asset, liability,
|
o They can help hledger know your accounts' types (asset, liability,
|
||||||
equity, revenue, expense), useful for reports like balancesheet and
|
equity, revenue, expense), useful for reports like balancesheet and
|
||||||
incomestatement.
|
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).
|
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.
|
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 name, eg:
|
||||||
|
|
||||||
account assets:bank:checking
|
account assets:bank:checking
|
||||||
@ -955,7 +951,7 @@ FILE FORMAT
|
|||||||
Account comments
|
Account comments
|
||||||
Comments, beginning with a semicolon, can be added:
|
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)
|
account names)
|
||||||
|
|
||||||
o on the next lines, indented
|
o on the next lines, indented
|
||||||
@ -969,7 +965,7 @@ FILE FORMAT
|
|||||||
Same-line comments are not supported by Ledger, or hledger <1.13.
|
Same-line comments are not supported by Ledger, or hledger <1.13.
|
||||||
|
|
||||||
Account subdirectives
|
Account subdirectives
|
||||||
We also allow (and ignore) Ledger-style indented subdirectives, just
|
We also allow (and ignore) Ledger-style indented subdirectives, just
|
||||||
for compatibility.:
|
for compatibility.:
|
||||||
|
|
||||||
account assets:bank:checking
|
account assets:bank:checking
|
||||||
@ -988,21 +984,21 @@ FILE FORMAT
|
|||||||
Asset, Liability, Equity, Revenue, Expense.
|
Asset, Liability, Equity, Revenue, Expense.
|
||||||
|
|
||||||
These account types are important for controlling which accounts appear
|
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).
|
probably for other things in future).
|
||||||
|
|
||||||
Additionally, we recognise the Cash type, which is also an Asset, and
|
Additionally, we recognise the Cash type, which is also an Asset, and
|
||||||
which causes accounts to appear in the cashflow report. ("Cash" here
|
which causes accounts to appear in the cashflow report. ("Cash" here
|
||||||
means liquid assets, eg bank balances but typically not investments or
|
means liquid assets, eg bank balances but typically not investments or
|
||||||
receivables.)
|
receivables.)
|
||||||
|
|
||||||
Declaring account types
|
Declaring account types
|
||||||
Generally, to make these reports work you should declare your top-level
|
Generally, to make these reports work you should declare your top-level
|
||||||
accounts and their types, using account directives with type: tags.
|
accounts and their types, using account directives with type: tags.
|
||||||
|
|
||||||
The tag's value should be one of: Asset, Liability, Equity, Revenue,
|
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
|
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
|
inherited by all subaccounts except where they override it. Here's a
|
||||||
complete example:
|
complete example:
|
||||||
|
|
||||||
account assets ; type: Asset
|
account assets ; type: Asset
|
||||||
@ -1014,8 +1010,8 @@ FILE FORMAT
|
|||||||
account expenses ; type: Expense
|
account expenses ; type: Expense
|
||||||
|
|
||||||
Auto-detected account types
|
Auto-detected account types
|
||||||
If you happen to use common english top-level account names, you may
|
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-
|
not need to declare account types, as they will be detected automati-
|
||||||
cally using the following rules:
|
cally using the following rules:
|
||||||
|
|
||||||
If name matches regular account type is:
|
If name matches regular account type is:
|
||||||
@ -1028,7 +1024,7 @@ FILE FORMAT
|
|||||||
^(income|revenue)s?(:|$) Revenue
|
^(income|revenue)s?(:|$) Revenue
|
||||||
^expenses?(:|$) Expense
|
^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:
|
lar expression: is:
|
||||||
--------------------------------------------------------------------------
|
--------------------------------------------------------------------------
|
||||||
(investment|receivable|:A/R|:fixed) Cash
|
(investment|receivable|:A/R|:fixed) Cash
|
||||||
@ -1038,9 +1034,9 @@ FILE FORMAT
|
|||||||
|
|
||||||
Interference from auto-detected account types
|
Interference from auto-detected account types
|
||||||
If you assign any account type, it's a good idea to assign all of them,
|
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.
|
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
|
Although it's unlikely to happen in real life, here's an example: with
|
||||||
the following journal, balancesheetequity shows "liabilities" in both
|
the following journal, balancesheetequity shows "liabilities" in both
|
||||||
Liabilities and Equity sections. Declaring another account as type:Li-
|
Liabilities and Equity sections. Declaring another account as type:Li-
|
||||||
ability would fix it:
|
ability would fix it:
|
||||||
|
|
||||||
@ -1052,8 +1048,8 @@ FILE FORMAT
|
|||||||
equity -2
|
equity -2
|
||||||
|
|
||||||
Old account type syntax
|
Old account type syntax
|
||||||
In some hledger journals you might instead see this old syntax (the
|
In some hledger journals you might instead see this old syntax (the
|
||||||
letters ALERX, separated from the account name by two or more spaces);
|
letters ALERX, separated from the account name by two or more spaces);
|
||||||
this is deprecated and may be removed soon:
|
this is deprecated and may be removed soon:
|
||||||
|
|
||||||
account assets A
|
account assets A
|
||||||
@ -1063,8 +1059,8 @@ FILE FORMAT
|
|||||||
account expenses X
|
account expenses X
|
||||||
|
|
||||||
Account display order
|
Account display order
|
||||||
Account directives also set the order in which accounts are displayed,
|
Account directives also set the order in which accounts are displayed,
|
||||||
eg in reports, the hledger-ui accounts screen, and the hledger-web
|
eg in reports, the hledger-ui accounts screen, and the hledger-web
|
||||||
sidebar. By default accounts are listed in alphabetical order. But if
|
sidebar. By default accounts are listed in alphabetical order. But if
|
||||||
you have these account directives in the journal:
|
you have these account directives in the journal:
|
||||||
|
|
||||||
@ -1086,20 +1082,20 @@ FILE FORMAT
|
|||||||
|
|
||||||
Undeclared accounts, if any, are displayed last, in alphabetical order.
|
Undeclared accounts, if any, are displayed last, in alphabetical order.
|
||||||
|
|
||||||
Note that sorting is done at each level of the account tree (within
|
Note that sorting is done at each level of the account tree (within
|
||||||
each group of sibling accounts under the same parent). And currently,
|
each group of sibling accounts under the same parent). And currently,
|
||||||
this directive:
|
this directive:
|
||||||
|
|
||||||
account other:zoo
|
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:
|
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-
|
that you don't intend to post to, just to customize their display or-
|
||||||
der
|
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).
|
a:b and a:c).
|
||||||
|
|
||||||
Rewriting accounts
|
Rewriting accounts
|
||||||
@ -1117,14 +1113,14 @@ FILE FORMAT
|
|||||||
o customising reports
|
o customising reports
|
||||||
|
|
||||||
Account aliases also rewrite account names in account directives. They
|
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.
|
web.
|
||||||
|
|
||||||
See also Rewrite account names.
|
See also Rewrite account names.
|
||||||
|
|
||||||
Basic aliases
|
Basic aliases
|
||||||
To set an account alias, use the alias directive in your journal file.
|
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
|
This affects all subsequent journal entries in the current file or its
|
||||||
included files. The spaces around the = are optional:
|
included files. The spaces around the = are optional:
|
||||||
|
|
||||||
alias OLD = NEW
|
alias OLD = NEW
|
||||||
@ -1132,49 +1128,49 @@ FILE FORMAT
|
|||||||
Or, you can use the --alias 'OLD=NEW' option on the command line. This
|
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.
|
affects all entries. It's useful for trying out aliases interactively.
|
||||||
|
|
||||||
OLD and NEW are case sensitive full account names. hledger will re-
|
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-
|
place any occurrence of the old account name with the new one. Subac-
|
||||||
counts are also affected. Eg:
|
counts are also affected. Eg:
|
||||||
|
|
||||||
alias checking = assets:bank:wells fargo:checking
|
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"
|
; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
|
||||||
|
|
||||||
Regex aliases
|
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:
|
indicated by the forward slashes:
|
||||||
|
|
||||||
alias /REGEX/ = REPLACEMENT
|
alias /REGEX/ = REPLACEMENT
|
||||||
|
|
||||||
or --alias '/REGEX/=REPLACEMENT'.
|
or --alias '/REGEX/=REPLACEMENT'.
|
||||||
|
|
||||||
REGEX is a case-insensitive regular expression. Anywhere it matches
|
REGEX is a case-insensitive regular expression. Anywhere it matches
|
||||||
inside an account name, the matched part will be replaced by REPLACE-
|
inside an account name, the matched part will be replaced by REPLACE-
|
||||||
MENT. If REGEX contains parenthesised match groups, these can be ref-
|
MENT. If REGEX contains parenthesised match groups, these can be ref-
|
||||||
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
|
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
|
||||||
|
|
||||||
alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
|
alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
|
||||||
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
|
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
|
||||||
|
|
||||||
Also note that REPLACEMENT continues to the end of line (or on command
|
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-
|
line, to end of option argument), so it can contain trailing white-
|
||||||
space.
|
space.
|
||||||
|
|
||||||
Combining aliases
|
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.
|
and/or command line options.
|
||||||
|
|
||||||
Recursive aliases - where an account name is rewritten by one alias,
|
Recursive aliases - where an account name is rewritten by one alias,
|
||||||
then by another alias, and so on - are allowed. Each alias sees the
|
then by another alias, and so on - are allowed. Each alias sees the
|
||||||
effect of previously applied aliases.
|
effect of previously applied aliases.
|
||||||
|
|
||||||
In such cases it can be important to understand which aliases will be
|
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
|
applied and in which order. For (each account name in) each journal
|
||||||
entry, we apply:
|
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)
|
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).
|
(left to right).
|
||||||
|
|
||||||
In other words, for (an account name in) a given journal entry:
|
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.
|
o aliases defined after/below the entry do not affect it.
|
||||||
|
|
||||||
This gives nearby aliases precedence over distant ones, and helps pro-
|
This gives nearby aliases precedence over distant ones, and helps pro-
|
||||||
vide semantic stability - aliases will keep working the same way inde-
|
vide semantic stability - aliases will keep working the same way inde-
|
||||||
pendent of which files are being read and in which order.
|
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.
|
which aliases are being applied when.
|
||||||
|
|
||||||
Aliases and multiple files
|
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,
|
affect parent or sibling files. Eg in this command,
|
||||||
|
|
||||||
hledger -f a.aliases -f b.journal
|
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:
|
cluding the aliases doesn't work either:
|
||||||
|
|
||||||
include a.aliases
|
include a.aliases
|
||||||
@ -1220,14 +1216,14 @@ FILE FORMAT
|
|||||||
include c.journal ; also affected
|
include c.journal ; also affected
|
||||||
|
|
||||||
end aliases
|
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:
|
aliases directive:
|
||||||
|
|
||||||
end aliases
|
end aliases
|
||||||
|
|
||||||
Default parent account
|
Default parent account
|
||||||
You can specify a parent account which will be prepended to all ac-
|
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
|
counts within a section of the journal. Use the apply account and end
|
||||||
apply account directives like so:
|
apply account directives like so:
|
||||||
|
|
||||||
apply account home
|
apply account home
|
||||||
@ -1244,7 +1240,7 @@ FILE FORMAT
|
|||||||
home:food $10
|
home:food $10
|
||||||
home:cash $-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:
|
file. Included files are also affected, eg:
|
||||||
|
|
||||||
apply account business
|
apply account business
|
||||||
@ -1253,50 +1249,50 @@ FILE FORMAT
|
|||||||
apply account personal
|
apply account personal
|
||||||
include personal.journal
|
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.
|
ported.
|
||||||
|
|
||||||
A default parent account also affects account directives. It does not
|
A default parent account also affects account directives. It does not
|
||||||
affect account names being entered via hledger add or hledger-web. If
|
affect account names being entered via hledger add or hledger-web. If
|
||||||
account aliases are present, they are applied after the default parent
|
account aliases are present, they are applied after the default parent
|
||||||
account.
|
account.
|
||||||
|
|
||||||
Periodic transactions
|
Periodic transactions
|
||||||
Periodic transaction rules describe transactions that recur. They al-
|
Periodic transaction rules describe transactions that recur. They al-
|
||||||
low hledger to generate temporary future transactions to help with
|
low hledger to generate temporary future transactions to help with
|
||||||
forecasting, so you don't have to write out each one in the journal,
|
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
|
and it's easy to try out different forecasts. Secondly, they are also
|
||||||
used to define the budgets shown in budget reports.
|
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:
|
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.
|
read about this below.
|
||||||
|
|
||||||
2. For troubleshooting, show the generated transactions with hledger
|
2. For troubleshooting, show the generated transactions with hledger
|
||||||
print --forecast tag:generated or hledger register --forecast
|
print --forecast tag:generated or hledger register --forecast
|
||||||
tag:generated.
|
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.
|
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.
|
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.
|
provement, but is worth studying.
|
||||||
|
|
||||||
6. Some period expressions with a repeating interval must begin on a
|
6. Some period expressions with a repeating interval must begin on a
|
||||||
natural boundary of that interval. Eg in weekly from DATE, DATE
|
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
|
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
|
||||||
error.
|
error.
|
||||||
|
|
||||||
7. Other period expressions with an interval are automatically expanded
|
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
|
reports, but it also affects periodic transactions. Yes, it's a bit
|
||||||
inconsistent with the above.) Eg: ~ 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, which is equivalent to ~ every 10th day of month from
|
||||||
2020/01/01, will be adjusted to start on 2019/12/10.
|
2020/01/01, will be adjusted to start on 2019/12/10.
|
||||||
|
|
||||||
Periodic rule syntax
|
Periodic rule syntax
|
||||||
@ -1308,17 +1304,17 @@ FILE FORMAT
|
|||||||
expenses:rent $2000
|
expenses:rent $2000
|
||||||
assets:bank:checking
|
assets:bank:checking
|
||||||
|
|
||||||
There is an additional constraint on the period expression: the start
|
There is an additional constraint on the period expression: the start
|
||||||
date must fall on a natural boundary of the interval. Eg monthly from
|
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.
|
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
|
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
|
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
|
date, unless a Y default year directive is in effect, in which case
|
||||||
they will be relative to Y/1/1.
|
they will be relative to Y/1/1.
|
||||||
|
|
||||||
Two spaces between period expression and description!
|
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
|
these must be separated by two or more spaces. This helps hledger know
|
||||||
where the period expression ends, so that descriptions can not acciden-
|
where the period expression ends, so that descriptions can not acciden-
|
||||||
tally alter their meaning, as in this example:
|
tally alter their meaning, as in this example:
|
||||||
@ -1332,67 +1328,67 @@ FILE FORMAT
|
|||||||
|
|
||||||
So,
|
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.
|
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.
|
pression.
|
||||||
|
|
||||||
Forecasting with periodic transactions
|
Forecasting with periodic transactions
|
||||||
The --forecast flag activates any periodic transaction rules in the
|
The --forecast flag activates any periodic transaction rules in the
|
||||||
journal. They will generate temporary recurring transactions, which
|
journal. They will generate temporary recurring transactions, which
|
||||||
are not saved in the journal, but will appear in all reports (eg
|
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
|
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
|
entry aid: describe recurring transactions, and every so often copy the
|
||||||
output of print --forecast into the journal.
|
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-
|
rule generated them: generated-transaction:~ PERIODICEXPR. And a simi-
|
||||||
lar, hidden tag (beginning with an underscore) which, because it's
|
lar, hidden tag (beginning with an underscore) which, because it's
|
||||||
never displayed by print, can be used to match transactions generated
|
never displayed by print, can be used to match transactions generated
|
||||||
"just now": _generated-transaction:~ PERIODICEXPR.
|
"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
|
default, this
|
||||||
|
|
||||||
o begins on the later of
|
o begins on the later of
|
||||||
|
|
||||||
o the report start date if specified with -b/-p/date:
|
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.
|
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.
|
months (180 days) from today.
|
||||||
|
|
||||||
This means that periodic transactions will begin only after the latest
|
This means that periodic transactions will begin only after the latest
|
||||||
recorded transaction. And a recorded transaction dated in the future
|
recorded transaction. And a recorded transaction dated in the future
|
||||||
can prevent generation of periodic transactions. (You can avoid that
|
can prevent generation of periodic transactions. (You can avoid that
|
||||||
by writing the future transaction as a one-time periodic rule instead -
|
by writing the future transaction as a one-time periodic rule instead -
|
||||||
put tilde before the date, eg ~ YYYY-MM-DD ...).
|
put tilde before the date, eg ~ YYYY-MM-DD ...).
|
||||||
|
|
||||||
Or, you can set your own arbitrary "forecast period", which can overlap
|
Or, you can set your own arbitrary "forecast period", which can overlap
|
||||||
recorded transactions, and need not be in the future, by providing an
|
recorded transactions, and need not be in the future, by providing an
|
||||||
option argument, like --forecast=PERIODEXPR. Note the equals sign is
|
option argument, like --forecast=PERIODEXPR. Note the equals sign is
|
||||||
required, a space won't work. PERIODEXPR is a period expression, which
|
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.
|
can specify the start date, end date, or both, like in a date: query.
|
||||||
(See also hledger.1 -> Report start & end date). Some examples:
|
(See also hledger.1 -> Report start & end date). Some examples:
|
||||||
--forecast=202001-202004, --forecast=jan-, --forecast=2020.
|
--forecast=202001-202004, --forecast=jan-, --forecast=2020.
|
||||||
|
|
||||||
Budgeting with periodic transactions
|
Budgeting with periodic transactions
|
||||||
With the --budget flag, currently supported by the balance command,
|
With the --budget flag, currently supported by the balance command,
|
||||||
each periodic transaction rule declares recurring budget goals for the
|
each periodic transaction rule declares recurring budget goals for the
|
||||||
specified accounts. Eg the first example above declares a goal of
|
specified accounts. Eg the first example above declares a goal of
|
||||||
spending $2000 on rent (and also, a goal of depositing $2000 into
|
spending $2000 on rent (and also, a goal of depositing $2000 into
|
||||||
checking) every month. Goals and actual performance can then be com-
|
checking) every month. Goals and actual performance can then be com-
|
||||||
pared in budget reports.
|
pared in budget reports.
|
||||||
|
|
||||||
See also: Budgeting and Forecasting.
|
See also: Budgeting and Forecasting.
|
||||||
|
|
||||||
Auto postings
|
Auto postings
|
||||||
"Automated postings" or "auto postings" are extra postings which get
|
"Automated postings" or "auto postings" are extra postings which get
|
||||||
added automatically to transactions which match certain queries, de-
|
added automatically to transactions which match certain queries, de-
|
||||||
fined by "auto posting rules", when you use the --auto flag.
|
fined by "auto posting rules", when you use the --auto flag.
|
||||||
|
|
||||||
An auto posting rule looks a bit like a transaction:
|
An auto posting rule looks a bit like a transaction:
|
||||||
@ -1402,27 +1398,27 @@ FILE FORMAT
|
|||||||
...
|
...
|
||||||
ACCOUNT [AMOUNT]
|
ACCOUNT [AMOUNT]
|
||||||
|
|
||||||
except the first line is an equals sign (mnemonic: = suggests match-
|
except the first line is an equals sign (mnemonic: = suggests match-
|
||||||
ing), followed by a query (which matches existing postings), and each
|
ing), followed by a query (which matches existing postings), and each
|
||||||
"posting" line describes a posting to be generated, and the posting
|
"posting" line describes a posting to be generated, and the posting
|
||||||
amounts can be:
|
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.
|
as-is.
|
||||||
|
|
||||||
o a number, eg 2. The commodity symbol (if any) from the matched post-
|
o a number, eg 2. The commodity symbol (if any) from the matched post-
|
||||||
ing will be added to this.
|
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
|
matched posting's amount (and total price, if any) will be multiplied
|
||||||
by N.
|
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
|
symbol S). The matched posting's amount will be multiplied by N, and
|
||||||
its commodity symbol will be replaced with S.
|
its commodity symbol will be replaced with S.
|
||||||
|
|
||||||
Any query term containing spaces must be enclosed in single or double
|
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
|
quotes, as on the command line. Eg, note the quotes around the second
|
||||||
query term below:
|
query term below:
|
||||||
|
|
||||||
= expenses:groceries 'expenses:dining out'
|
= expenses:groceries 'expenses:dining out'
|
||||||
@ -1461,24 +1457,24 @@ FILE FORMAT
|
|||||||
|
|
||||||
Auto postings and multiple files
|
Auto postings and multiple files
|
||||||
An auto posting rule can affect any transaction in the current file, or
|
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).
|
sibling files (when multiple -f/--file are used - see #1212).
|
||||||
|
|
||||||
Auto postings and dates
|
Auto postings and dates
|
||||||
A posting date (or secondary date) in the matched posting, or (taking
|
A posting date (or secondary date) in the matched posting, or (taking
|
||||||
precedence) a posting date in the auto posting rule itself, will also
|
precedence) a posting date in the auto posting rule itself, will also
|
||||||
be used in the generated posting.
|
be used in the generated posting.
|
||||||
|
|
||||||
Auto postings and transaction balancing / inferred amounts / balance asser-
|
Auto postings and transaction balancing / inferred amounts / balance asser-
|
||||||
tions
|
tions
|
||||||
Currently, auto postings are added:
|
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,
|
balancedness,
|
||||||
|
|
||||||
o but before balance assertions are checked.
|
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
|
after auto postings are added. This changed in hledger 1.12+; see #893
|
||||||
for background.
|
for background.
|
||||||
|
|
||||||
@ -1488,11 +1484,11 @@ FILE FORMAT
|
|||||||
o generated-posting:= QUERY - shows this was generated by an auto post-
|
o generated-posting:= QUERY - shows this was generated by an auto post-
|
||||||
ing rule, and the query
|
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
|
hledger's output. This can be used to match postings generated "just
|
||||||
now", rather than generated in the past and saved to the journal.
|
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:
|
have these tags added:
|
||||||
|
|
||||||
o modified: - this transaction was modified
|
o modified: - this transaction was modified
|
||||||
@ -1503,7 +1499,7 @@ FILE FORMAT
|
|||||||
|
|
||||||
|
|
||||||
REPORTING BUGS
|
REPORTING BUGS
|
||||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||||
or hledger mail list)
|
or hledger mail list)
|
||||||
|
|
||||||
|
|
||||||
@ -1517,7 +1513,7 @@ COPYRIGHT
|
|||||||
|
|
||||||
|
|
||||||
SEE ALSO
|
SEE ALSO
|
||||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||||
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
|
||||||
dot(5), ledger(1)
|
dot(5), ledger(1)
|
||||||
|
|
||||||
@ -1525,4 +1521,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger 1.19.99 September 2020 hledger_journal(5)
|
hledger 1.19.99 October 2020 hledger_journal(5)
|
||||||
|
|||||||
@ -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"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -78,4 +78,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger 1.19.99 September 2020 hledger_timeclock(5)
|
hledger 1.19.99 October 2020 hledger_timeclock(5)
|
||||||
|
|||||||
@ -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"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -161,4 +161,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger 1.19.99 September 2020 hledger_timedot(5)
|
hledger 1.19.99 October 2020 hledger_timedot(5)
|
||||||
|
|||||||
@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
|
|||||||
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
||||||
m4_dnl
|
m4_dnl
|
||||||
m4_dnl Date to show in man pages. Updated by make setdate.
|
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
|
||||||
|
|||||||
@ -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"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -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)
|
||||||
|
|||||||
@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
|
|||||||
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
||||||
m4_dnl
|
m4_dnl
|
||||||
m4_dnl Date to show in man pages. Updated by make setdate.
|
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
|
||||||
|
|||||||
@ -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"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -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)
|
||||||
|
|||||||
@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
|
|||||||
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
m4_define({{_version_}}, {{1.19.99}})m4_dnl
|
||||||
m4_dnl
|
m4_dnl
|
||||||
m4_dnl Date to show in man pages. Updated by make setdate.
|
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
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
.\"t
|
.\"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"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
@ -3460,4 +3460,4 @@ SEE ALSO
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
hledger 1.19.99 September 2020 hledger(1)
|
hledger 1.19.99 October 2020 hledger(1)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user