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

;doc: regen manuals

Browse Source 
I think all the non-content changes are due to newer
doc tools and harmless, including this one hopefully:

    -.B \f[C]--watch\f[R]
    +\f[B]\f[CB]--watch\f[B]\f[R]

[ci skip]
This commit is contained in:
Simon Michael 2020-01-05 07:04:00 -08:00
parent 6b70eadf30
commit f91076cc6a
19 changed files with 1486 additions and 1173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
hledger-lib/hledger_csv.5
View File

@ -472,6 +472,9 @@ Fields you don\[aq]t care about can be left unnamed.
Currently there must be least two items (there must be at least one
comma).
.PP
Note, always use comma in the fields list, even if your CSV uses another
separator character.
.PP
Here are the standard hledger field/pseudo-field names.
For more about the transaction parts they refer to, see the manual for
hledger\[aq]s journal format.
@ -508,6 +511,7 @@ If the CSV has the currency symbol in a separate field, you can use
.PP
\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting
amount is left empty, a balance assignment).
You may need to adjust this with the \f[C]balance-type\f[R] rule.
.PP
Finally, \f[C]commentN\f[R] sets a comment on the Nth posting.
Comments can also contain tags, as usual.
@ -733,7 +737,52 @@ account2 expenses:misc
include categorisation.rules
\f[R]
.fi
.SS \f[C]balance-type\f[R]
.PP
Balance assertions generated by assigning to balanceN are of the simple
\f[C]=\f[R] type by default, which is a single-commodity,
subaccount-excluding assertion.
You may find the subaccount-including variants more useful, eg if you
have created some virtual subaccounts of checking to help with
budgeting.
You can select a different type of assertion with the
\f[C]balance-type\f[R] rule:
.IP
.nf
\f[C]
# balance assertions will consider all commodities and all subaccounts
balance-type ==*
\f[R]
.fi
.PP
Here are the balance assertion types for quick reference:
.IP
.nf
\f[C]
= single commodity, exclude subaccounts
=* single commodity, include subaccounts
== multi commodity, exclude subaccounts
==* multi commodity, include subaccounts
\f[R]
.fi
.SH TIPS
.SS Rapid feedback
.PP
It\[aq]s a good idea to get rapid feedback while
creating/troubleshooting CSV rules.
Here\[aq]s a good way, using entr from http://eradman.com/entrproject :
.IP
.nf
\f[C]
$ ls foo.csv* | entr bash -c \[aq]echo ----; hledger -f foo.csv print desc:SOMEDESC\[aq]
\f[R]
.fi
.PP
A desc: query (eg) is used to select just one, or a few, transactions of
interest.
\[dq]bash -c\[dq] is used to run multiple commands, so we can echo a
separator each time the command re-runs, making it easier to read the
output.
.SS Valid CSV
.PP
hledger accepts CSV conforming to RFC 4180.
@ -744,17 +793,27 @@ they must be double quotes (not single quotes)
spaces outside the quotes are not allowed
.SS Other separator characters
.PP
With the \f[C]--separator \[aq]CHAR\[aq]\f[R] option (experimental),
hledger will expect the separator to be CHAR instead of a comma.
Ie it will read other \[dq]Character Separated Values\[dq] formats, such
as TSV (Tab Separated Values).
Note: on the command line, use a real tab character in quotes, not Eg:
You can use the \f[C]--separator \[aq]CHAR\[aq]\f[R] command line option
(experimental) to read other kinds of character-separated data.
Eg to read SSV (Semicolon Separated Values), use:
.IP
.nf
\f[C]
$ hledger -f foo.tsv --separator \[aq];\[aq] print
\f[R]
.fi
.PP
Note the semicolon is quoted because it\[aq]s a special shell character.
.PP
To read TSV (Tab Separated Values), use:
.IP
.nf
\f[C]
$ hledger -f foo.tsv --separator \[aq] \[aq] print
\f[R]
.fi
.PP
Note, that\[aq]s a real tab character in quotes, not \f[C]\[rs]t\f[R].
.SS Reading multiple CSV files
.PP
If you use multiple \f[C]-f\f[R] options to read multiple CSV files at

179
hledger-lib/hledger_csv.info
View File

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

File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir)
@ -376,6 +376,7 @@ Blank lines and lines beginning with '#' or ';' are ignored.
* date-format::
* newest-first::
* include::
* balance-type::

File: hledger_csv.info, Node: skip, Next: fields, Up: CSV RULES
@ -421,6 +422,9 @@ fields date, description, , amount, , , somefield, anotherfield
can be left unnamed. Currently there must be least two items (there
must be at least one comma).
Note, always use comma in the fields list, even if your CSV uses
another separator character.
Here are the standard hledger field/pseudo-field names. For more
about the transaction parts they refer to, see the manual for hledger's
journal format.
@ -466,7 +470,8 @@ indicating an unbalanced posting.)
affects ALL postings.
'balanceN' sets a balance assertion amount (or if the posting amount
is left empty, a balance assignment).
is left empty, a balance assignment). You may need to adjust this with
the 'balance-type' rule.
Finally, 'commentN' sets a comment on the Nth posting. Comments can
also contain tags, as usual.
@ -625,7 +630,7 @@ oldest first or newest first. But if all of the following are true:
newest-first

File: hledger_csv.info, Node: include, Prev: newest-first, Up: CSV RULES
File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES
2.8 'include'
=============
@ -647,6 +652,29 @@ account2 expenses:misc
## common rules
include categorisation.rules

File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV RULES
2.9 'balance-type'
==================
Balance assertions generated by assigning to balanceN are of the simple
'=' type by default, which is a single-commodity, subaccount-excluding
assertion. You may find the subaccount-including variants more useful,
eg if you have created some virtual subaccounts of checking to help with
budgeting. You can select a different type of assertion with the
'balance-type' rule:
# balance assertions will consider all commodities and all subaccounts
balance-type ==*
Here are the balance assertion types for quick reference:
= single commodity, exclude subaccounts
=* single commodity, include subaccounts
== multi commodity, exclude subaccounts
==* multi commodity, include subaccounts

File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top
@ -655,6 +683,7 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top
* Menu:
* Rapid feedback::
* Valid CSV::
* Other separator characters::
* Reading multiple CSV files::
@ -666,9 +695,26 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top
* How CSV rules are evaluated::

File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Up: TIPS
File: hledger_csv.info, Node: Rapid feedback, Next: Valid CSV, Up: TIPS
3.1 Valid CSV
3.1 Rapid feedback
==================
It's a good idea to get rapid feedback while creating/troubleshooting
CSV rules. Here's a good way, using entr from
http://eradman.com/entrproject :
$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
A desc: query (eg) is used to select just one, or a few, transactions
of interest. "bash -c" is used to run multiple commands, so we can echo
a separator each time the command re-runs, making it easier to read the
output.

File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Prev: Rapid feedback, Up: TIPS
3.2 Valid CSV
=============
hledger accepts CSV conforming to RFC 4180. When CSV values are
@ -680,21 +726,27 @@ enclosed in quotes, note:

File: hledger_csv.info, Node: Other separator characters, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS
3.2 Other separator characters
3.3 Other separator characters
==============================
With the '--separator 'CHAR'' option (experimental), hledger will expect
the separator to be CHAR instead of a comma. Ie it will read other
"Character Separated Values" formats, such as TSV (Tab Separated
Values). Note: on the command line, use a real tab character in quotes,
not
You can use the '--separator 'CHAR'' command line option (experimental)
to read other kinds of character-separated data. Eg to read SSV
(Semicolon Separated Values), use:
$ hledger -f foo.tsv --separator ';' print
Note the semicolon is quoted because it's a special shell character.
To read TSV (Tab Separated Values), use:
$ hledger -f foo.tsv --separator ' ' print
Note, that's a real tab character in quotes, not '\t'.

File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Other separator characters, Up: TIPS
3.3 Reading multiple CSV files
3.4 Reading multiple CSV files
==============================
If you use multiple '-f' options to read multiple CSV files at once,
@ -705,7 +757,7 @@ used for all the CSV files.

File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS
3.4 Valid transactions
3.5 Valid transactions
======================
After reading a CSV file, hledger post-processes and validates the
@ -724,7 +776,7 @@ $ hledger -f file.csv print | hledger -f- print

File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS
3.5 Deduplicating, importing
3.6 Deduplicating, importing
============================
When you download a CSV file periodically, eg to get your latest bank
@ -754,7 +806,7 @@ CSV data. See:

File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS
3.6 Setting amounts
3.7 Setting amounts
===================
A posting amount can be set in one of these ways:
@ -783,7 +835,7 @@ A posting amount can be set in one of these ways:

File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS
3.7 Setting currency/commodity
3.8 Setting currency/commodity
==============================
If the currency/commodity symbol is included in the CSV's amount
@ -810,7 +862,7 @@ field(s), you don't have to do anything special.

File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS
3.8 Referencing other fields
3.9 Referencing other fields
============================
In field assignments, you can interpolate only CSV fields, not hledger
@ -847,8 +899,8 @@ if something

File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS
3.9 How CSV rules are evaluated
===============================
3.10 How CSV rules are evaluated
================================
Here's how to think of CSV rules being evaluated (if you really need
to). First,
@ -900,45 +952,54 @@ Node: Paypal6438
Ref: #paypal6532
Node: CSV RULES14415
Ref: #csv-rules14524
Node: skip14769
Ref: #skip14862
Node: fields15237
Ref: #fields15359
Node: Transaction field names16426
Ref: #transaction-field-names16586
Node: Posting field names16697
Ref: #posting-field-names16849
Node: field assignment18081
Ref: #field-assignment18217
Node: if19035
Ref: #if19144
Node: end20860
Ref: #end20966
Node: date-format21190
Ref: #date-format21322
Node: newest-first22071
Ref: #newest-first22209
Node: include22892
Ref: #include23000
Node: TIPS23444
Ref: #tips23526
Node: Valid CSV23775
Ref: #valid-csv23894
Node: Other separator characters24086
Ref: #other-separator-characters24274
Node: Reading multiple CSV files24603
Ref: #reading-multiple-csv-files24800
Node: Valid transactions25041
Ref: #valid-transactions25219
Node: Deduplicating importing25847
Ref: #deduplicating-importing26026
Node: Setting amounts27059
Ref: #setting-amounts27228
Node: Setting currency/commodity28214
Ref: #setting-currencycommodity28406
Node: Referencing other fields29209
Ref: #referencing-other-fields29409
Node: How CSV rules are evaluated30306
Ref: #how-csv-rules-are-evaluated30477
Node: skip14786
Ref: #skip14879
Node: fields15254
Ref: #fields15376
Node: Transaction field names16541
Ref: #transaction-field-names16701
Node: Posting field names16812
Ref: #posting-field-names16964
Node: field assignment18255
Ref: #field-assignment18391
Node: if19209
Ref: #if19318
Node: end21034
Ref: #end21140
Node: date-format21364
Ref: #date-format21496
Node: newest-first22245
Ref: #newest-first22383
Node: include23066
Ref: #include23195
Node: balance-type23639
Ref: #balance-type23757
Node: TIPS24457
Ref: #tips24539
Node: Rapid feedback24807
Ref: #rapid-feedback24924
Node: Valid CSV25384
Ref: #valid-csv25526
Node: Other separator characters25718
Ref: #other-separator-characters25906
Node: Reading multiple CSV files26345
Ref: #reading-multiple-csv-files26542
Node: Valid transactions26783
Ref: #valid-transactions26961
Node: Deduplicating importing27589
Ref: #deduplicating-importing27768
Node: Setting amounts28801
Ref: #setting-amounts28970
Node: Setting currency/commodity29956
Ref: #setting-currencycommodity30148
Node: Referencing other fields30951
Ref: #referencing-other-fields31151
Node: How CSV rules are evaluated32048
Ref: #how-csv-rules-are-evaluated32221

End Tag Table

Local Variables:
coding: utf-8
End:

74
hledger-lib/hledger_csv.txt
View File

@ -366,6 +366,9 @@ CSV RULES
can be left unnamed. Currently there must be least two items (there
must be at least one comma).
Note, always use comma in the fields list, even if your CSV uses an-
other separator character.
Here are the standard hledger field/pseudo-field names. For more about
the transaction parts they refer to, see the manual for hledger's jour-
nal format.
@ -375,28 +378,29 @@ CSV RULES
transaction's first line.
Posting field names
accountN, where N is 1 to 9, generates a posting, with that account
name. Most often there are two postings, so you'll want to set ac-
accountN, where N is 1 to 9, generates a posting, with that account
name. Most often there are two postings, so you'll want to set ac-
count1 and account2. If a posting's account name is left unset but its
amount is set, a default account name will be chosen (like expenses:un-
known or income:unknown).
amountN sets posting N's amount. Or, amount with no N sets posting
1's. If the CSV has debits and credits in separate fields, use
amountN-in and amountN-out instead. Or amount-in and amount-out with
amountN sets posting N's amount. Or, amount with no N sets posting
1's. If the CSV has debits and credits in separate fields, use
amountN-in and amountN-out instead. Or amount-in and amount-out with
no N for posting 1.
For convenience and backwards compatibility, if you set the amount of
posting 1 only, a second posting with the negative amount will be gen-
erated automatically. (Unless the account name is parenthesised indi-
For convenience and backwards compatibility, if you set the amount of
posting 1 only, a second posting with the negative amount will be gen-
erated automatically. (Unless the account name is parenthesised indi-
cating an unbalanced posting.)
If the CSV has the currency symbol in a separate field, you can use
currencyN to prepend it to posting N's amount. currency with no N af-
If the CSV has the currency symbol in a separate field, you can use
currencyN to prepend it to posting N's amount. currency with no N af-
fects ALL postings.
balanceN sets a balance assertion amount (or if the posting amount is
left empty, a balance assignment).
balanceN sets a balance assertion amount (or if the posting amount is
left empty, a balance assignment). You may need to adjust this with
the balance-type rule.
Finally, commentN sets a comment on the Nth posting. Comments can also
contain tags, as usual.
@ -551,7 +555,37 @@ CSV RULES
## common rules
include categorisation.rules
balance-type
Balance assertions generated by assigning to balanceN are of the simple
= type by default, which is a single-commodity, subaccount-excluding
assertion. You may find the subaccount-including variants more useful,
eg if you have created some virtual subaccounts of checking to help
with budgeting. You can select a different type of assertion with the
balance-type rule:
# balance assertions will consider all commodities and all subaccounts
balance-type ==*
Here are the balance assertion types for quick reference:
= single commodity, exclude subaccounts
=* single commodity, include subaccounts
== multi commodity, exclude subaccounts
==* multi commodity, include subaccounts
TIPS
Rapid feedback
It's a good idea to get rapid feedback while creating/troubleshooting
CSV rules. Here's a good way, using entr from http://eradman.com/entr-
project :
$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
A desc: query (eg) is used to select just one, or a few, transactions
of interest. "bash -c" is used to run multiple commands, so we can
echo a separator each time the command re-runs, making it easier to
read the output.
Valid CSV
hledger accepts CSV conforming to RFC 4180. When CSV values are en-
closed in quotes, note:
@ -561,14 +595,20 @@ TIPS
o spaces outside the quotes are not allowed
Other separator characters
With the --separator 'CHAR' option (experimental), hledger will expect
the separator to be CHAR instead of a comma. Ie it will read other
"Character Separated Values" formats, such as TSV (Tab Separated Val-
ues). Note: on the command line, use a real tab character in quotes,
not Eg:
You can use the --separator 'CHAR' command line option (experimental)
to read other kinds of character-separated data. Eg to read SSV (Semi-
colon Separated Values), use:
$ hledger -f foo.tsv --separator ';' print
Note the semicolon is quoted because it's a special shell character.
To read TSV (Tab Separated Values), use:
$ hledger -f foo.tsv --separator ' ' print
Note, that's a real tab character in quotes, not \t.
Reading multiple CSV files
If you use multiple -f options to read multiple CSV files at once,
hledger will look for a correspondingly-named rules file for each CSV

1
hledger-lib/hledger_journal.5
View File

@ -533,6 +533,7 @@ reconciled balances while cleaning up old entries.
You can disable them temporarily with the
\f[C]-I/--ignore-assertions\f[R] flag, which can be useful for
troubleshooting or for reading Ledger files.
(Note: this flag currently does not disable balance assignments, below).
.SS Assertions and ordering
.PP
hledger sorts an account\[aq]s postings and assertions first by date and

174
hledger-lib/hledger_journal.info
View File

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

@ -500,7 +500,8 @@ assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with
the '-I/--ignore-assertions' flag, which can be useful for
troubleshooting or for reading Ledger files.
troubleshooting or for reading Ledger files. (Note: this flag currently
does not disable balance assignments, below).
* Menu:
@ -1779,87 +1780,92 @@ Node: Virtual Postings15303
Ref: #virtual-postings15462
Node: Balance Assertions16682
Ref: #balance-assertions16857
Node: Assertions and ordering17816
Ref: #assertions-and-ordering18002
Node: Assertions and included files18702
Ref: #assertions-and-included-files18943
Node: Assertions and multiple -f options19276
Ref: #assertions-and-multiple--f-options19530
Node: Assertions and commodities19662
Ref: #assertions-and-commodities19892
Node: Assertions and prices21048
Ref: #assertions-and-prices21260
Node: Assertions and subaccounts21700
Ref: #assertions-and-subaccounts21927
Node: Assertions and virtual postings22251
Ref: #assertions-and-virtual-postings22491
Node: Assertions and precision22633
Ref: #assertions-and-precision22824
Node: Balance Assignments23091
Ref: #balance-assignments23272
Node: Balance assignments and prices24437
Ref: #balance-assignments-and-prices24609
Node: Transaction prices24833
Ref: #transaction-prices25002
Node: Comments27268
Ref: #comments27402
Node: Tags28572
Ref: #tags28690
Node: Directives30083
Ref: #directives30226
Node: Comment blocks35834
Ref: #comment-blocks35979
Node: Including other files36155
Ref: #including-other-files36335
Node: Default year36743
Ref: #default-year36912
Node: Declaring commodities37319
Ref: #declaring-commodities37502
Node: Default commodity39163
Ref: #default-commodity39339
Node: Market prices39973
Ref: #market-prices40138
Node: Declaring accounts40979
Ref: #declaring-accounts41155
Node: Account comments42080
Ref: #account-comments42243
Node: Account subdirectives42638
Ref: #account-subdirectives42833
Node: Account types43146
Ref: #account-types43330
Node: Account display order44972
Ref: #account-display-order45142
Node: Rewriting accounts46271
Ref: #rewriting-accounts46456
Node: Basic aliases47182
Ref: #basic-aliases47328
Node: Regex aliases48032
Ref: #regex-aliases48204
Node: Combining aliases48922
Ref: #combining-aliases49100
Node: end aliases50376
Ref: #end-aliases50524
Node: Default parent account50625
Ref: #default-parent-account50791
Node: Periodic transactions51675
Ref: #periodic-transactions51873
Node: Periodic rule syntax53745
Ref: #periodic-rule-syntax53951
Node: Two spaces between period expression and description!54655
Ref: #two-spaces-between-period-expression-and-description54974
Node: Forecasting with periodic transactions55658
Ref: #forecasting-with-periodic-transactions55963
Node: Budgeting with periodic transactions57989
Ref: #budgeting-with-periodic-transactions58228
Node: Auto postings / transaction modifiers58677
Ref: #auto-postings-transaction-modifiers58888
Node: Auto postings and dates61117
Ref: #auto-postings-and-dates61374
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61549
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61924
Node: Auto posting tags62302
Ref: #auto-posting-tags62541
Node: EDITOR SUPPORT63206
Ref: #editor-support63324
Node: Assertions and ordering17890
Ref: #assertions-and-ordering18076
Node: Assertions and included files18776
Ref: #assertions-and-included-files19017
Node: Assertions and multiple -f options19350
Ref: #assertions-and-multiple--f-options19604
Node: Assertions and commodities19736
Ref: #assertions-and-commodities19966
Node: Assertions and prices21122
Ref: #assertions-and-prices21334
Node: Assertions and subaccounts21774
Ref: #assertions-and-subaccounts22001
Node: Assertions and virtual postings22325
Ref: #assertions-and-virtual-postings22565
Node: Assertions and precision22707
Ref: #assertions-and-precision22898
Node: Balance Assignments23165
Ref: #balance-assignments23346
Node: Balance assignments and prices24511
Ref: #balance-assignments-and-prices24683
Node: Transaction prices24907
Ref: #transaction-prices25076
Node: Comments27342
Ref: #comments27476
Node: Tags28646
Ref: #tags28764
Node: Directives30157
Ref: #directives30300
Node: Comment blocks35908
Ref: #comment-blocks36053
Node: Including other files36229
Ref: #including-other-files36409
Node: Default year36817
Ref: #default-year36986
Node: Declaring commodities37393
Ref: #declaring-commodities37576
Node: Default commodity39237
Ref: #default-commodity39413
Node: Market prices40047
Ref: #market-prices40212
Node: Declaring accounts41053
Ref: #declaring-accounts41229
Node: Account comments42154
Ref: #account-comments42317
Node: Account subdirectives42712
Ref: #account-subdirectives42907
Node: Account types43220
Ref: #account-types43404
Node: Account display order45046
Ref: #account-display-order45216
Node: Rewriting accounts46345
Ref: #rewriting-accounts46530
Node: Basic aliases47256
Ref: #basic-aliases47402
Node: Regex aliases48106
Ref: #regex-aliases48278
Node: Combining aliases48996
Ref: #combining-aliases49174
Node: end aliases50450
Ref: #end-aliases50598
Node: Default parent account50699
Ref: #default-parent-account50865
Node: Periodic transactions51749
Ref: #periodic-transactions51947
Node: Periodic rule syntax53819
Ref: #periodic-rule-syntax54025
Node: Two spaces between period expression and description!54729
Ref: #two-spaces-between-period-expression-and-description55048
Node: Forecasting with periodic transactions55732
Ref: #forecasting-with-periodic-transactions56037
Node: Budgeting with periodic transactions58063
Ref: #budgeting-with-periodic-transactions58302
Node: Auto postings / transaction modifiers58751
Ref: #auto-postings-transaction-modifiers58962
Node: Auto postings and dates61191
Ref: #auto-postings-and-dates61448
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61623
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61998
Node: Auto posting tags62376
Ref: #auto-posting-tags62615
Node: EDITOR SUPPORT63280
Ref: #editor-support63398

End Tag Table

Local Variables:
coding: utf-8
End:

445
hledger-lib/hledger_journal.txt
View File

@ -384,27 +384,28 @@ FILE FORMAT
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
-I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files.
for reading Ledger files. (Note: this flag currently does not disable
balance assignments, below).
Assertions and ordering
hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif-
hledger sorts an account's postings and assertions first by date and
then (for postings on the same day) by parse order. Note this is dif-
ferent from Ledger, which sorts assertions only by parse order. (Also,
Ledger assertions do not see the accumulated effect of repeated post-
Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differently-
dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating.
dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating.
This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert intra-
day balances.
Assertions and included files
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same
day, you'll have to put the assertion in the right file.
Assertions and multiple -f options
@ -412,8 +413,8 @@ FILE FORMAT
-f options. Use include or concatenate the files instead.
Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance.
This is how assertions work in Ledger also. We could call this a "par-
tial" balance assertion.
@ -421,7 +422,7 @@ FILE FORMAT
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance.
You can make a stronger "total" balance assertion by writing a double
You can make a stronger "total" balance assertion by writing a double
equals sign (== EXPECTEDBALANCE). This asserts that there are no other
unasserted commodities in the account (or, that their balance is 0).
@ -441,7 +442,7 @@ FILE FORMAT
a 0 == $1
It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity
has multiple commodities. One workaround is to isolate each commodity
into its own subaccount:
2013/1/1
@ -455,21 +456,21 @@ FILE FORMAT
a:euro 0 == 1EUR
Assertions and prices
Balance assertions ignore transaction prices, and should normally be
Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ EUR1 = $1
We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
ments do use them (see below).
Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can
The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg:
2019/1/1
@ -483,16 +484,16 @@ FILE FORMAT
tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision
Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser-
Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts.
Balance Assignments
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when
setting opening balances:
; starting a new journal, set asset account balances
@ -510,14 +511,14 @@ FILE FORMAT
expenses:misc
The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it.
Balance assignments and prices
A transaction price in a balance assignment will cause the calculated
A transaction price in a balance assignment will cause the calculated
amount to have that price attached:
2019/1/1
@ -529,9 +530,9 @@ FILE FORMAT
Transaction prices
Within a transaction, you can note an amount's price in another commod-
ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer-
tain date.
@ -560,7 +561,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price's
Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above:
@ -571,8 +572,8 @@ FILE FORMAT
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last
Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last
amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different:
@ -586,13 +587,13 @@ FILE FORMAT
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the de-
You can attach comments to a transaction by writing them after the de-
scription and/or indented on the following lines (before the postings).
Similarly, you can attach comments to an individual posting by writing
Similarly, you can attach comments to an individual posting by writing
them after the amount and/or indented on the following lines. Transac-
tion and posting comments must begin with a semicolon (;).
@ -617,24 +618,24 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using comment and end
You can also comment larger regions of a file using comment and end
comment directives.
Tags
Tags are a way to add extra labels or labelled data to postings and
Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
Tags can have a value, which is the text after the colon, up to the
Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@ -648,65 +649,65 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, third-
tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
A directive is a line in the journal beginning with a special keyword,
A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also
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
here is a table summarising the directives and their effects, with
links to more detailed docs.
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
tries until end of
current file or end
directive
apply end apply prepend a common parent to following in-
apply end apply prepend a common parent to following in-
account account account names line/included en-
tries until end of
tries until end of
current file or end
directive
comment end com- ignore part of journal following in-
ment line/included en-
tries until end of
tries until end of
current file or end
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
style in that commodity
in all files; dis-
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
less entries and
entries in that
commodity in all
commodity in all
files; display
style: amounts of
that commodity in
@ -714,26 +715,24 @@ FILE FORMAT
include include entries/directives what the included
from another file directives affect
P declare a market price for a amounts of that
commodity commodity in re-
ports, when -V is
commodity commodity in re-
ports, when -V is
used
Y declare a year for yearless following in-
Y declare a year for yearless following in-
dates line/included en-
tries until end of
tries until end of
current file
And some definitions:
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
directive which entries and (when there are multiple files) which files
scope are affected by a directive
@ -741,34 +740,34 @@ FILE FORMAT
affect, and whether they are focussed on input (parsing) or output (re-
ports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
writing file options in a different order. It can be surprising at
times though.
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 path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can in-
The include directive can only be used in journal files. It can in-
clude journal, timeclock or timedot files, but not CSV files.
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
@ -790,18 +789,18 @@ 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 to expect when parsing input
- useful to disambiguate international number formats in your data.
- 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 format 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.
@ -814,8 +813,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
@ -828,14 +827,14 @@ 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.
Default commodity
The D directive sets a default commodity (and display format), to be
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
; commodity-less amounts should be treated as dollars
@ -850,9 +849,9 @@ FILE FORMAT
a decimal point.
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:
@ -863,16 +862,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/--value flag can be used to convert reported amounts to another
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
@ -882,20 +881,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
@ -913,7 +912,7 @@ FILE FORMAT
the next line instead.
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
@ -926,18 +925,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are
bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
Account types declared with tags
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
More generally, you can declare an account's type with an account di-
rective, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@ -948,8 +947,8 @@ FILE FORMAT
account expenses ; type:Expenses
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A
@ -959,7 +958,7 @@ FILE FORMAT
account expenses X
Overriding auto-detected types
If you ever override the types of those auto-detected english account
If you ever override the types of those auto-detected english account
names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why
@ -970,8 +969,8 @@ FILE FORMAT
account - ; type:L
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:
@ -993,16 +992,16 @@ 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
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
@ -1021,14 +1020,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
@ -1036,49 +1035,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:
@ -1089,22 +1088,22 @@ 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.
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
@ -1121,7 +1120,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
@ -1130,50 +1129,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
@ -1185,17 +1184,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:
@ -1209,82 +1208,82 @@ 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
With the --forecast flag, each periodic transaction rule generates fu-
ture transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
With the --forecast flag, each periodic transaction rule generates fu-
ture transactions recurring at the specified interval. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag:
o generated-transaction:~ PERIODICEXPR - shows that this was generated
o generated-transaction:~ PERIODICEXPR - shows that this was generated
by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not
There is also a hidden tag, with an underscore prefix, which does not
appear in hledger's output:
o _generated-transaction:~ PERIODICEXPR
This can be used to match transactions generated "just now", rather
This can be used to match transactions generated "just now", rather
than generated in the past and saved to the journal.
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
forecast period:
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 180
o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
actions with periodic rules, and every so often copy the output of
actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
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.
For more details, see: balance: Budget report and Budgeting and Fore-
For more details, see: balance: Budget report and Budgeting and Fore-
casting.
Auto postings / transaction modifiers
Transaction modifier rules, AKA auto posting rules, describe changes to
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
be applied automatically to certain matched transactions. Currently
just one kind of change is possible - adding extra postings, which we
call "automated postings" or just "auto postings". These rules become
active when you use the --auto flag.
A transaction modifier rule looks much like a normal transaction except
the first line is an equals sign followed by a query that matches cer-
tain postings (mnemonic: = suggests matching). And each "posting" is
the first line is an equals sign followed by a query that matches cer-
tain postings (mnemonic: = suggests matching). And each "posting" is
actually a posting-generating rule:
= QUERY
@ -1292,20 +1291,20 @@ FILE FORMAT
ACCT [AMT]
...
These posting-generating rules look like normal postings, except the
These posting-generating rules look like normal postings, except the
amount 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.
@ -1345,20 +1344,20 @@ FILE FORMAT
assets:checking $20
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, transaction modifiers are applied / 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.
@ -1368,11 +1367,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 transaction modifier
Also, any transaction that has been changed by transaction modifier
rules will have these tags added:
o modified: - this transaction was modified
@ -1381,18 +1380,18 @@ FILE FORMAT
tion was modified "just now".
EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with
Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the Editor configuration at hledger.org for the latest in-
formation.
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)
@ -1406,7 +1405,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)

2
hledger-lib/hledger_timeclock.5
View File

@ -63,7 +63,7 @@ use emacs and the built-in timeclock.el, or the extended timeclock-x.el
and perhaps the extras in ledgerutils.el
.IP \[bu] 2
at the command line, use these bash aliases:
\f[C]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]
\f[C]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]
.IP \[bu] 2
or use the old \f[C]ti\f[R] and \f[C]to\f[R] scripts in the ledger 2.x
repository.

7
hledger-lib/hledger_timeclock.info
View File

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

@ -59,3 +59,8 @@ Tag Table:
Node: Top78

End Tag Table

Local Variables:
coding: utf-8
End:

6
hledger-lib/hledger_timeclock.txt
View File

@ -45,9 +45,9 @@ DESCRIPTION
o use emacs and the built-in timeclock.el, or the extended timeclock-
x.el and perhaps the extras in ledgerutils.el
o at the command line, use these bash aliases: shell alias ti="echo i
`date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date
'+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
o at the command line, use these bash aliases: shell alias ti="echo
i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
`date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2

7
hledger-lib/hledger_timedot.info
View File

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

@ -115,3 +115,8 @@ Node: FILE FORMAT812
Ref: #file-format913

End Tag Table

Local Variables:
coding: utf-8
End:

75
hledger-ui/hledger-ui.1
View File

@ -47,113 +47,114 @@ before options as shown above.
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
.TP
.B \f[C]--watch\f[R]
\f[B]\f[CB]--watch\f[B]\f[R]
watch for data and date changes and reload automatically
.TP
.B \f[C]--theme=default|terminal|greenterm\f[R]
\f[B]\f[CB]--theme=default|terminal|greenterm\f[B]\f[R]
use this custom display theme
.TP
.B \f[C]--register=ACCTREGEX\f[R]
\f[B]\f[CB]--register=ACCTREGEX\f[B]\f[R]
start in the (first) matched account\[aq]s register screen
.TP
.B \f[C]--change\f[R]
\f[B]\f[CB]--change\f[B]\f[R]
show period balances (changes) at startup instead of historical balances
.TP
.B \f[C]-F --flat\f[R]
\f[B]\f[CB]-F --flat\f[B]\f[R]
show accounts as a list (default)
.TP
.B \f[C]-T --tree\f[R]
\f[B]\f[CB]-T --tree\f[B]\f[R]
show accounts as a tree
.TP
.B \f[C]--future\f[R]
\f[B]\f[CB]--future\f[B]\f[R]
show transactions dated later than today (normally hidden)
.PP
hledger input options:
.TP
.B \f[C]-f FILE --file=FILE\f[R]
\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R]
use a different input file.
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[R])
.TP
.B \f[C]--rules-file=RULESFILE\f[R]
\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R]
Conversion rules file to use when reading CSV (default: FILE.rules)
.TP
.B \f[C]--separator=CHAR\f[R]
\f[B]\f[CB]--separator=CHAR\f[B]\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq])
.TP
.B \f[C]--alias=OLD=NEW\f[R]
\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R]
rename accounts named OLD to NEW
.TP
.B \f[C]--anon\f[R]
\f[B]\f[CB]--anon\f[B]\f[R]
anonymize accounts and payees
.TP
.B \f[C]--pivot FIELDNAME\f[R]
\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R]
use some other field or tag for the account name
.TP
.B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions
\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R]
disable balance assertion checks (note: does not disable balance
assignments)
.PP
hledger reporting options:
.TP
.B \f[C]-b --begin=DATE\f[R]
\f[B]\f[CB]-b --begin=DATE\f[B]\f[R]
include postings/txns on or after this date
.TP
.B \f[C]-e --end=DATE\f[R]
\f[B]\f[CB]-e --end=DATE\f[B]\f[R]
include postings/txns before this date
.TP
.B \f[C]-D --daily\f[R]
\f[B]\f[CB]-D --daily\f[B]\f[R]
multiperiod/multicolumn report by day
.TP
.B \f[C]-W --weekly\f[R]
\f[B]\f[CB]-W --weekly\f[B]\f[R]
multiperiod/multicolumn report by week
.TP
.B \f[C]-M --monthly\f[R]
\f[B]\f[CB]-M --monthly\f[B]\f[R]
multiperiod/multicolumn report by month
.TP
.B \f[C]-Q --quarterly\f[R]
\f[B]\f[CB]-Q --quarterly\f[B]\f[R]
multiperiod/multicolumn report by quarter
.TP
.B \f[C]-Y --yearly\f[R]
\f[B]\f[CB]-Y --yearly\f[B]\f[R]
multiperiod/multicolumn report by year
.TP
.B \f[C]-p --period=PERIODEXP\f[R]
\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax
.TP
.B \f[C]--date2\f[R]
\f[B]\f[CB]--date2\f[B]\f[R]
match the secondary date instead (see command help for other effects)
.TP
.B \f[C]-U --unmarked\f[R]
\f[B]\f[CB]-U --unmarked\f[B]\f[R]
include only unmarked postings/txns (can combine with -P or -C)
.TP
.B \f[C]-P --pending\f[R]
\f[B]\f[CB]-P --pending\f[B]\f[R]
include only pending postings/txns
.TP
.B \f[C]-C --cleared\f[R]
\f[B]\f[CB]-C --cleared\f[B]\f[R]
include only cleared postings/txns
.TP
.B \f[C]-R --real\f[R]
\f[B]\f[CB]-R --real\f[B]\f[R]
include only non-virtual postings
.TP
.B \f[C]-NUM --depth=NUM\f[R]
\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R]
hide/aggregate accounts or postings more than NUM levels deep
.TP
.B \f[C]-E --empty\f[R]
\f[B]\f[CB]-E --empty\f[B]\f[R]
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
.TP
.B \f[C]-B --cost\f[R]
\f[B]\f[CB]-B --cost\f[B]\f[R]
convert amounts to their cost at transaction time (using the transaction
price, if any)
.TP
.B \f[C]-V --value\f[R]
\f[B]\f[CB]-V --value\f[B]\f[R]
convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.TP
.B \f[C]--auto\f[R]
\f[B]\f[CB]--auto\f[B]\f[R]
apply automated posting rules to modify transactions.
.TP
.B \f[C]--forecast\f[R]
\f[B]\f[CB]--forecast\f[B]\f[R]
apply periodic transaction rules to generate future transactions, to 6
months from now or report end date.
.PP
@ -164,13 +165,13 @@ Some reporting options can also be written as query arguments.
.PP
hledger help options:
.TP
.B \f[C]-h --help\f[R]
\f[B]\f[CB]-h --help\f[B]\f[R]
show general usage (or after COMMAND, command usage)
.TP
.B \f[C]--version\f[R]
\f[B]\f[CB]--version\f[B]\f[R]
show version
.TP
.B \f[C]--debug[=N]\f[R]
\f[B]\f[CB]--debug[=N]\f[B]\f[R]
show debug output (levels 1-9, default: 1)
.PP
A \[at]FILE argument will be expanded to the contents of FILE, which

34
hledger-ui/hledger-ui.info
View File

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

File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
@ -89,7 +89,8 @@ the data.
use some other field or tag for the account name
'-I --ignore-assertions'
ignore any failing balance assertions
disable balance assertion checks (note: does not disable balance
assignments)
hledger reporting options:
@ -425,17 +426,22 @@ Tag Table:
Node: Top71
Node: OPTIONS1101
Ref: #options1198
Node: KEYS4589
Ref: #keys4684
Node: SCREENS8991
Ref: #screens9076
Node: Accounts screen9166
Ref: #accounts-screen9294
Node: Register screen11510
Ref: #register-screen11665
Node: Transaction screen13661
Ref: #transaction-screen13819
Node: Error screen14689
Ref: #error-screen14811
Node: KEYS4634
Ref: #keys4729
Node: SCREENS9036
Ref: #screens9121
Node: Accounts screen9211
Ref: #accounts-screen9339
Node: Register screen11555
Ref: #register-screen11710
Node: Transaction screen13706
Ref: #transaction-screen13864
Node: Error screen14734
Ref: #error-screen14856

End Tag Table

Local Variables:
coding: utf-8
End:

217
hledger-ui/hledger-ui.txt
View File

@ -87,7 +87,8 @@ OPTIONS
use some other field or tag for the account name
-I --ignore-assertions
ignore any failing balance assertions
disable balance assertion checks (note: does not disable balance
assignments)
hledger reporting options:
@ -113,7 +114,7 @@ OPTIONS
multiperiod/multicolumn report by year
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
set start date, end date, and/or reporting interval all at once
using period expressions syntax
--date2
@ -136,21 +137,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep
-E --empty
show items with zero amount, normally hidden (and vice-versa in
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
-B --cost
convert amounts to their cost at transaction time (using the
convert amounts to their cost at transaction time (using the
transaction price, if any)
-V --value
convert amounts to their market value on the report end date
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
--auto apply automated posting rules to modify transactions.
--forecast
apply periodic transaction rules to generate future transac-
apply periodic transaction rules to generate future transac-
tions, to 6 months from now or report end date.
When a reporting option appears more than once in the command line, the
@ -170,138 +171,138 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this,
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
KEYS
? shows a help dialog listing all keys. (Some of these also appear in
? shows a help dialog listing all keys. (Some of these also appear in
the quick help at the bottom of each screen.) Press ? again (or ESCAPE,
or LEFT) to close it. The following keys work on most screens:
The cursor keys navigate: right (or enter) goes deeper, left returns to
the previous screen, up/down/page up/page down/home/end move up and
down through lists. Vi-style (h/j/k/l) and Emacs-style (CTRL-p/CTRL-
n/CTRL-f/CTRL-b) movement keys are also supported. A tip: movement
speed is limited by your keyboard repeat rate, to move faster you may
want to adjust it. (If you're on a mac, the Karabiner app is one way
the previous screen, up/down/page up/page down/home/end move up and
down through lists. Vi-style (h/j/k/l) and Emacs-style (CTRL-p/CTRL-
n/CTRL-f/CTRL-b) movement keys are also supported. A tip: movement
speed is limited by your keyboard repeat rate, to move faster you may
want to adjust it. (If you're on a mac, the Karabiner app is one way
to do that.)
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown). shift-
down/up steps downward and upward through these standard report period
durations: year, quarter, month, week, day. Then, shift-left/right
moves to the previous/next period. t sets the report period to today.
With the --watch option, when viewing a "current" period (the current
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown). shift-
down/up steps downward and upward through these standard report period
durations: year, quarter, month, week, day. Then, shift-left/right
moves to the previous/next period. t sets the report period to today.
With the --watch option, when viewing a "current" period (the current
day, week, month, quarter, or year), the period will move automatically
to track the current date. To set a non-standard period, you can use /
and a date: query.
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set
it, or ESCAPEto cancel. There are also keys for quickly adjusting some
common filters like account depth and transaction status (see below).
common filters like account depth and transaction status (see below).
BACKSPACE or DELETE removes all filters, showing all transactions.
As mentioned above, hledger-ui shows auto-generated periodic transac-
tions, and hides future transactions (auto-generated or not) by de-
fault. F toggles showing and hiding these future transactions. This
is similar to using a query like date:-tomorrow, but more convenient.
As mentioned above, hledger-ui shows auto-generated periodic transac-
tions, and hides future transactions (auto-generated or not) by de-
fault. F toggles showing and hiding these future transactions. This
is similar to using a query like date:-tomorrow, but more convenient.
(experimental)
ESCAPE removes all filters and jumps back to the top screen. Or, it
ESCAPE removes all filters and jumps back to the top screen. Or, it
cancels a minibuffer edit or help dialog in progress.
CTRL-l redraws the screen and centers the selection if possible (selec-
tions near the top won't be centered, since we don't scroll above the
tions near the top won't be centered, since we don't scroll above the
top).
g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable
g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable
pause.)
I toggles balance assertion checking. Disabling balance assertions
I toggles balance assertion checking. Disabling balance assertions
temporarily can be useful for troubleshooting.
a runs command-line hledger's add command, and reloads the updated
a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a terminal
interface. This key will be available if hledger-iadd is installed in
A is like a, but runs the hledger-iadd tool, which provides a terminal
interface. This key will be available if hledger-iadd is installed in
$PATH.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor
will be positioned at the current transaction when invoked from the
register and transaction screens, and at the error location (if possi-
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor
will be positioned at the current transaction when invoked from the
register and transaction screens, and at the error location (if possi-
ble) when invoked from the error screen.
q quits the application.
Experimental:
B toggles cost mode, showing amounts in their transaction price's com-
B toggles cost mode, showing amounts in their transaction price's com-
modity (like toggling the -B/--cost flag).
V toggles value mode, showing amounts' current market value in their
default valuation commodity (like toggling the -V/--market flag).
Note, "current market value" means the value on the report end date if
specified, otherwise today. To see the value on another date, you can
temporarily set that as the report end date. Eg: to see a transaction
as it was valued on july 30, go to the accounts or register screen,
V toggles value mode, showing amounts' current market value in their
default valuation commodity (like toggling the -V/--market flag).
Note, "current market value" means the value on the report end date if
specified, otherwise today. To see the value on another date, you can
temporarily set that as the report end date. Eg: to see a transaction
as it was valued on july 30, go to the accounts or register screen,
press /, and add date:-7/30 to the query.
At most one of cost or value mode can be active at once.
There's not yet any visual reminder when cost or value mode is active;
There's not yet any visual reminder when cost or value mode is active;
for now pressing B B V should reliably reset to normal mode.
With --watch active, if you save an edit to the journal file while
With --watch active, if you save an edit to the journal file while
viewing the transaction screen in cost or value mode, the B/V keys will
stop working. To work around, press g to force a manual reload, or
stop working. To work around, press g to force a manual reload, or
exit the transaction screen.
Additional screen-specific keys are described below.
SCREENS
Accounts screen
This is normally the first screen displayed. It lists accounts and
their balances, like hledger's balance command. By default, it shows
all accounts and their latest ending balances (including the balances
of subaccounts). if you specify a query on the command line, it shows
This is normally the first screen displayed. It lists accounts and
their balances, like hledger's balance command. By default, it shows
all accounts and their latest ending balances (including the balances
of subaccounts). if you specify a query on the command line, it shows
just the matched accounts and the balances from matched transactions.
Account names are shown as a flat list by default. Press T to toggle
tree mode. In flat mode, account balances are exclusive of subac-
counts, except where subaccounts are hidden by a depth limit (see be-
Account names are shown as a flat list by default. Press T to toggle
tree mode. In flat mode, account balances are exclusive of subac-
counts, except where subaccounts are hidden by a depth limit (see be-
low). In tree mode, all account balances are inclusive of subaccounts.
To see less detail, press a number key, 1 to 9, to set a depth limit.
To see less detail, press a number key, 1 to 9, to set a depth limit.
Or use - to decrease and +/= to increase the depth limit. 0 shows even
less detail, collapsing all accounts to a single total. To remove the
less detail, collapsing all accounts to a single total. To remove the
depth limit, set it higher than the maximum account depth, or press ES-
CAPE.
H toggles between showing historical balances or period balances. His-
torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions be-
fore the report start date, so they show the change in balance during
torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions be-
fore the report start date, so they show the change in balance during
the report period. They are more useful eg when viewing a time log.
U toggles filtering by unmarked status, including or excluding unmarked
postings in the balances. Similarly, P toggles pending postings, and C
toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are in-
toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are in-
cluded; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line
Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line
hledger).
Press right or enter to view an account's transactions register.
@ -310,63 +311,63 @@ SCREENS
This screen shows the transactions affecting a particular account, like
a check register. Each line represents one transaction and shows:
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected
by real postings.)
o the overall change to the current account's balance; positive for an
o the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow.
o the running historical total or period total for the current account,
after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while
after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while
the period total is not. If the historical total is not disturbed by
a filter query, it will be the running historical balance you would
a filter query, it will be the running historical balance you would
see on a bank register for the current account.
Transactions affecting this account's subaccounts will be included in
Transactions affecting this account's subaccounts will be included in
the register if the accounts screen is in tree mode, or if it's in flat
mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac-
mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac-
tions contributing to the balance shown on the accounts screen.
Tree mode/flat mode can be toggled with T here also.
U toggles filtering by unmarked status, showing or hiding unmarked
U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
cleared transactions. (By default, transactions with all statuses are
shown; if you activate one or two status filters, only those transac-
tions are shown; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored.
Z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com-
Z toggles nonzero mode, in which only transactions posting a nonzero
change are shown (hledger-ui shows zero items by default, unlike com-
mand-line hledger).
Press right (or enter) to view the selected transaction in detail.
Transaction screen
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour-
This screen shows a single transaction, as a general journal entry,
similar to hledger's print command and journal format (hledger_jour-
nal(5)).
The transaction's date(s) and any cleared flag, transaction code, de-
scription, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
The transaction's date(s) and any cleared flag, transaction code, de-
scription, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
certain cases, fewer).
up and down will step through all transactions listed in the previous
account register screen. In the title bar, the numbers in parentheses
show your position within that account register. They will vary de-
up and down will step through all transactions listed in the previous
account register screen. In the title bar, the numbers in parentheses
show your position within that account register. They will vary de-
pending on which account register you came from (remember most transac-
tions appear in multiple account registers). The #N number preceding
tions appear in multiple account registers). The #N number preceding
them is the transaction's position within the complete unfiltered jour-
nal, which is a more stable id (at least until the next reload).
Error screen
This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g
This screen will appear if there is a problem, such as a parse error,
when you press g to reload. Once you have fixed the problem, press g
again to reload and resume normal operation. (Or, you can press escape
to cancel the reload attempt.)
@ -374,17 +375,17 @@ ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede options with -- when invoked from hledger is awk-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-ui can't read from stdin).
@ -392,24 +393,24 @@ BUGS
-V affects only the accounts screen.
When you press g, the current and all previous screens are regenerated,
which may cause a noticeable pause with large files. Also there is no
which may cause a noticeable pause with large files. Also there is no
visual indication that this is in progress.
--watch is not yet fully robust. It works well for normal usage, but
many file changes in a short time (eg saving the file thousands of
times with an editor macro) can cause problems at least on OSX. Symp-
toms include: unresponsive UI, periodic resetting of the cursor posi-
--watch is not yet fully robust. It works well for normal usage, but
many file changes in a short time (eg saving the file thousands of
times with an editor macro) can cause problems at least on OSX. Symp-
toms include: unresponsive UI, periodic resetting of the cursor posi-
tion, momentary display of parse errors, high CPU usage eventually sub-
siding, and possibly a small but persistent build-up of CPU usage until
the program is restarted.
Also, if you are viewing files mounted from another machine, --watch
Also, if you are viewing files mounted from another machine, --watch
requires that both machine clocks are roughly in step.
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)
@ -423,7 +424,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)

77
hledger-web/hledger-web.1
View File

@ -51,123 +51,124 @@ in addition to any search query entered there.
Note: if invoking hledger-web as a hledger subcommand, write
\f[C]--\f[R] before options, as shown in the synopsis above.
.TP
.B \f[C]--serve\f[R]
\f[B]\f[CB]--serve\f[B]\f[R]
serve and log requests, don\[aq]t browse or auto-exit
.TP
.B \f[C]--serve-api\f[R]
\f[B]\f[CB]--serve-api\f[B]\f[R]
like --serve, but serve only the JSON web API, without the server-side
web UI
.TP
.B \f[C]--host=IPADDR\f[R]
\f[B]\f[CB]--host=IPADDR\f[B]\f[R]
listen on this IP address (default: 127.0.0.1)
.TP
.B \f[C]--port=PORT\f[R]
\f[B]\f[CB]--port=PORT\f[B]\f[R]
listen on this TCP port (default: 5000)
.TP
.B \f[C]--base-url=URL\f[R]
\f[B]\f[CB]--base-url=URL\f[B]\f[R]
set the base url (default: http://IPADDR:PORT).
You would change this when sharing over the network, or integrating
within a larger website.
.TP
.B \f[C]--file-url=URL\f[R]
\f[B]\f[CB]--file-url=URL\f[B]\f[R]
set the static files url (default: BASEURL/static).
hledger-web normally serves static files itself, but if you wanted to
serve them from another server for efficiency, you would set the url
with this.
.TP
.B \f[C]--capabilities=CAP[,CAP..]\f[R]
\f[B]\f[CB]--capabilities=CAP[,CAP..]\f[B]\f[R]
enable the view, add, and/or manage capabilities (default: view,add)
.TP
.B \f[C]--capabilities-header=HTTPHEADER\f[R]
\f[B]\f[CB]--capabilities-header=HTTPHEADER\f[B]\f[R]
read capabilities to enable from a HTTP header, like
X-Sandstorm-Permissions (default: disabled)
.PP
hledger input options:
.TP
.B \f[C]-f FILE --file=FILE\f[R]
\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R]
use a different input file.
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[R])
.TP
.B \f[C]--rules-file=RULESFILE\f[R]
\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R]
Conversion rules file to use when reading CSV (default: FILE.rules)
.TP
.B \f[C]--separator=CHAR\f[R]
\f[B]\f[CB]--separator=CHAR\f[B]\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq])
.TP
.B \f[C]--alias=OLD=NEW\f[R]
\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R]
rename accounts named OLD to NEW
.TP
.B \f[C]--anon\f[R]
\f[B]\f[CB]--anon\f[B]\f[R]
anonymize accounts and payees
.TP
.B \f[C]--pivot FIELDNAME\f[R]
\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R]
use some other field or tag for the account name
.TP
.B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions
\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R]
disable balance assertion checks (note: does not disable balance
assignments)
.PP
hledger reporting options:
.TP
.B \f[C]-b --begin=DATE\f[R]
\f[B]\f[CB]-b --begin=DATE\f[B]\f[R]
include postings/txns on or after this date
.TP
.B \f[C]-e --end=DATE\f[R]
\f[B]\f[CB]-e --end=DATE\f[B]\f[R]
include postings/txns before this date
.TP
.B \f[C]-D --daily\f[R]
\f[B]\f[CB]-D --daily\f[B]\f[R]
multiperiod/multicolumn report by day
.TP
.B \f[C]-W --weekly\f[R]
\f[B]\f[CB]-W --weekly\f[B]\f[R]
multiperiod/multicolumn report by week
.TP
.B \f[C]-M --monthly\f[R]
\f[B]\f[CB]-M --monthly\f[B]\f[R]
multiperiod/multicolumn report by month
.TP
.B \f[C]-Q --quarterly\f[R]
\f[B]\f[CB]-Q --quarterly\f[B]\f[R]
multiperiod/multicolumn report by quarter
.TP
.B \f[C]-Y --yearly\f[R]
\f[B]\f[CB]-Y --yearly\f[B]\f[R]
multiperiod/multicolumn report by year
.TP
.B \f[C]-p --period=PERIODEXP\f[R]
\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax
.TP
.B \f[C]--date2\f[R]
\f[B]\f[CB]--date2\f[B]\f[R]
match the secondary date instead (see command help for other effects)
.TP
.B \f[C]-U --unmarked\f[R]
\f[B]\f[CB]-U --unmarked\f[B]\f[R]
include only unmarked postings/txns (can combine with -P or -C)
.TP
.B \f[C]-P --pending\f[R]
\f[B]\f[CB]-P --pending\f[B]\f[R]
include only pending postings/txns
.TP
.B \f[C]-C --cleared\f[R]
\f[B]\f[CB]-C --cleared\f[B]\f[R]
include only cleared postings/txns
.TP
.B \f[C]-R --real\f[R]
\f[B]\f[CB]-R --real\f[B]\f[R]
include only non-virtual postings
.TP
.B \f[C]-NUM --depth=NUM\f[R]
\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R]
hide/aggregate accounts or postings more than NUM levels deep
.TP
.B \f[C]-E --empty\f[R]
\f[B]\f[CB]-E --empty\f[B]\f[R]
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
.TP
.B \f[C]-B --cost\f[R]
\f[B]\f[CB]-B --cost\f[B]\f[R]
convert amounts to their cost at transaction time (using the transaction
price, if any)
.TP
.B \f[C]-V --value\f[R]
\f[B]\f[CB]-V --value\f[B]\f[R]
convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.TP
.B \f[C]--auto\f[R]
\f[B]\f[CB]--auto\f[B]\f[R]
apply automated posting rules to modify transactions.
.TP
.B \f[C]--forecast\f[R]
\f[B]\f[CB]--forecast\f[B]\f[R]
apply periodic transaction rules to generate future transactions, to 6
months from now or report end date.
.PP
@ -178,13 +179,13 @@ Some reporting options can also be written as query arguments.
.PP
hledger help options:
.TP
.B \f[C]-h --help\f[R]
\f[B]\f[CB]-h --help\f[B]\f[R]
show general usage (or after COMMAND, command usage)
.TP
.B \f[C]--version\f[R]
\f[B]\f[CB]--version\f[B]\f[R]
show version
.TP
.B \f[C]--debug[=N]\f[R]
\f[B]\f[CB]--debug[=N]\f[B]\f[R]
show debug output (levels 1-9, default: 1)
.PP
A \[at]FILE argument will be expanded to the contents of FILE, which

26
hledger-web/hledger-web.info
View File

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

File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
@ -103,7 +103,8 @@ before options, as shown in the synopsis above.
use some other field or tag for the account name
'-I --ignore-assertions'
ignore any failing balance assertions
disable balance assertion checks (note: does not disable balance
assignments)
hledger reporting options:
@ -342,13 +343,18 @@ Tag Table:
Node: Top72
Node: OPTIONS1359
Ref: #options1464
Node: PERMISSIONS6743
Ref: #permissions6882
Node: EDITING UPLOADING DOWNLOADING8094
Ref: #editing-uploading-downloading8275
Node: RELOADING9109
Ref: #reloading9243
Node: JSON API9676
Ref: #json-api9770
Node: PERMISSIONS6788
Ref: #permissions6927
Node: EDITING UPLOADING DOWNLOADING8139
Ref: #editing-uploading-downloading8320
Node: RELOADING9154
Ref: #reloading9288
Node: JSON API9721
Ref: #json-api9815

End Tag Table

Local Variables:
coding: utf-8
End:

111
hledger-web/hledger-web.txt
View File

@ -97,7 +97,8 @@ OPTIONS
use some other field or tag for the account name
-I --ignore-assertions
ignore any failing balance assertions
disable balance assertion checks (note: does not disable balance
assignments)
hledger reporting options:
@ -123,7 +124,7 @@ OPTIONS
multiperiod/multicolumn report by year
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
set start date, end date, and/or reporting interval all at once
using period expressions syntax
--date2
@ -146,21 +147,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep
-E --empty
show items with zero amount, normally hidden (and vice-versa in
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
-B --cost
convert amounts to their cost at transaction time (using the
convert amounts to their cost at transaction time (using the
transaction price, if any)
-V --value
convert amounts to their market value on the report end date
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
--auto apply automated posting rules to modify transactions.
--forecast
apply periodic transaction rules to generate future transac-
apply periodic transaction rules to generate future transac-
tions, to 6 months from now or report end date.
When a reporting option appears more than once in the command line, the
@ -180,41 +181,41 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this,
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML
server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host
0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are
Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances.
You can use --base-url to change the protocol, hostname, port and path
You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's
a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg
With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites.
PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the
By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma-
o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma-
chine.
o putting it behind an authenticating proxy, using eg apache or nginx
@ -224,44 +225,44 @@ PERMISSIONS
You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or in-
o manage - allows editing, uploading or downloading the main or in-
cluded files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in-
If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in-
cludes.
Note, unlike any other hledger command, in this mode you (or any visi-
Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed.
@ -269,8 +270,8 @@ RELOADING
that both machine clocks are roughly in step.)
JSON API
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. (And when started with
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. (And when started with
--serve-api, it provides only these routes.):
/accountnames
@ -280,17 +281,17 @@ JSON API
/accounts
/accounttransactions/#AccountName
Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form,
hledger-web must be started with the add capability for this (enabled
Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form,
hledger-web must be started with the add capability for this (enabled
by default).
The payload should be a valid hledger transaction as JSON, similar to
The payload should be a valid hledger transaction as JSON, similar to
what you get from /transactions or /accounttransactions.
Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's
JSON-capable types from or to a file. Eg here we write the first
Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's
JSON-capable types from or to a file. Eg here we write the first
transaction of a sample journal:
$ make ghci-web
@ -305,23 +306,23 @@ JSON API
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
to serve the API.
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede options with -- when invoked from hledger is awk-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-web can't read from stdin).
@ -335,7 +336,7 @@ BUGS
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -349,7 +350,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)

184
hledger/hledger.1
View File

@ -159,101 +159,102 @@ by most hledger commands, run \f[C]hledger -h\f[R].
.PP
General help options:
.TP
.B \f[C]-h --help\f[R]
\f[B]\f[CB]-h --help\f[B]\f[R]
show general usage (or after COMMAND, command usage)
.TP
.B \f[C]--version\f[R]
\f[B]\f[CB]--version\f[B]\f[R]
show version
.TP
.B \f[C]--debug[=N]\f[R]
\f[B]\f[CB]--debug[=N]\f[B]\f[R]
show debug output (levels 1-9, default: 1)
.PP
General input options:
.TP
.B \f[C]-f FILE --file=FILE\f[R]
\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R]
use a different input file.
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[R])
.TP
.B \f[C]--rules-file=RULESFILE\f[R]
\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R]
Conversion rules file to use when reading CSV (default: FILE.rules)
.TP
.B \f[C]--separator=CHAR\f[R]
\f[B]\f[CB]--separator=CHAR\f[B]\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq])
.TP
.B \f[C]--alias=OLD=NEW\f[R]
\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R]
rename accounts named OLD to NEW
.TP
.B \f[C]--anon\f[R]
\f[B]\f[CB]--anon\f[B]\f[R]
anonymize accounts and payees
.TP
.B \f[C]--pivot FIELDNAME\f[R]
\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R]
use some other field or tag for the account name
.TP
.B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions
\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R]
disable balance assertion checks (note: does not disable balance
assignments)
.PP
General reporting options:
.TP
.B \f[C]-b --begin=DATE\f[R]
\f[B]\f[CB]-b --begin=DATE\f[B]\f[R]
include postings/txns on or after this date
.TP
.B \f[C]-e --end=DATE\f[R]
\f[B]\f[CB]-e --end=DATE\f[B]\f[R]
include postings/txns before this date
.TP
.B \f[C]-D --daily\f[R]
\f[B]\f[CB]-D --daily\f[B]\f[R]
multiperiod/multicolumn report by day
.TP
.B \f[C]-W --weekly\f[R]
\f[B]\f[CB]-W --weekly\f[B]\f[R]
multiperiod/multicolumn report by week
.TP
.B \f[C]-M --monthly\f[R]
\f[B]\f[CB]-M --monthly\f[B]\f[R]
multiperiod/multicolumn report by month
.TP
.B \f[C]-Q --quarterly\f[R]
\f[B]\f[CB]-Q --quarterly\f[B]\f[R]
multiperiod/multicolumn report by quarter
.TP
.B \f[C]-Y --yearly\f[R]
\f[B]\f[CB]-Y --yearly\f[B]\f[R]
multiperiod/multicolumn report by year
.TP
.B \f[C]-p --period=PERIODEXP\f[R]
\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax
.TP
.B \f[C]--date2\f[R]
\f[B]\f[CB]--date2\f[B]\f[R]
match the secondary date instead (see command help for other effects)
.TP
.B \f[C]-U --unmarked\f[R]
\f[B]\f[CB]-U --unmarked\f[B]\f[R]
include only unmarked postings/txns (can combine with -P or -C)
.TP
.B \f[C]-P --pending\f[R]
\f[B]\f[CB]-P --pending\f[B]\f[R]
include only pending postings/txns
.TP
.B \f[C]-C --cleared\f[R]
\f[B]\f[CB]-C --cleared\f[B]\f[R]
include only cleared postings/txns
.TP
.B \f[C]-R --real\f[R]
\f[B]\f[CB]-R --real\f[B]\f[R]
include only non-virtual postings
.TP
.B \f[C]-NUM --depth=NUM\f[R]
\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R]
hide/aggregate accounts or postings more than NUM levels deep
.TP
.B \f[C]-E --empty\f[R]
\f[B]\f[CB]-E --empty\f[B]\f[R]
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
.TP
.B \f[C]-B --cost\f[R]
\f[B]\f[CB]-B --cost\f[B]\f[R]
convert amounts to their cost at transaction time (using the transaction
price, if any)
.TP
.B \f[C]-V --value\f[R]
\f[B]\f[CB]-V --value\f[B]\f[R]
convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.TP
.B \f[C]--auto\f[R]
\f[B]\f[CB]--auto\f[B]\f[R]
apply automated posting rules to modify transactions.
.TP
.B \f[C]--forecast\f[R]
\f[B]\f[CB]--forecast\f[B]\f[R]
apply periodic transaction rules to generate future transactions, to 6
months from now or report end date.
.PP
@ -773,7 +774,7 @@ start and end date like so:
.PP
.TS
tab(@);
l l.
l r.
T{
\f[C]-p \[dq]2009\[dq]\f[R]
T}@T{
@ -1101,20 +1102,20 @@ more general \f[C]--value\f[R] option:
The TYPE part basically selects either \[dq]cost\[dq], or \[dq]market
value\[dq] plus a valuation date:
.TP
.B \f[C]--value=cost\f[R]
\f[B]\f[CB]--value=cost\f[B]\f[R]
Convert amounts to cost, using the prices recorded in transactions.
.TP
.B \f[C]--value=end\f[R]
\f[B]\f[CB]--value=end\f[B]\f[R]
Convert amounts to their value in a default valuation commodity, using
market prices on the last day of the report period (or if unspecified,
the journal\[aq]s end date); or in multiperiod reports, market prices on
the last day of each subperiod.
.TP
.B \f[C]--value=now\f[R]
\f[B]\f[CB]--value=now\f[B]\f[R]
Convert amounts to their value in default valuation commodity using
current market prices (as of when report is generated).
.TP
.B \f[C]--value=YYYY-MM-DD\f[R]
\f[B]\f[CB]--value=YYYY-MM-DD\f[B]\f[R]
Convert amounts to their value in default valuation commodity using
market prices on this date.
.PP
@ -1509,30 +1510,30 @@ T}
.PP
\f[B]Additional notes\f[R]
.TP
.B \f[I]cost\f[R]
\f[I]cost\f[R]
calculated using price(s) recorded in the transaction(s).
.TP
.B \f[I]value\f[R]
\f[I]value\f[R]
market value using available market price declarations, or the unchanged
amount if no conversion rate can be found.
.TP
.B \f[I]report start\f[R]
\f[I]report start\f[R]
the first day of the report period specified with -b or -p or date:,
otherwise today.
.TP
.B \f[I]report or journal start\f[R]
\f[I]report or journal start\f[R]
the first day of the report period specified with -b or -p or date:,
otherwise the earliest transaction date in the journal, otherwise today.
.TP
.B \f[I]report end\f[R]
\f[I]report end\f[R]
the last day of the report period specified with -e or -p or date:,
otherwise today.
.TP
.B \f[I]report or journal end\f[R]
\f[I]report or journal end\f[R]
the last day of the report period specified with -e or -p or date:,
otherwise the latest transaction date in the journal, otherwise today.
.TP
.B \f[I]report interval\f[R]
\f[I]report interval\f[R]
a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
report\[aq]s multi-period mode (whether showing one or many subperiods).
.SS Combining -B, -V, -X, --value
@ -1646,12 +1647,12 @@ The following kinds of search terms can be used.
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg
to exclude a particular subaccount.
.TP
.B \f[B]\f[CB]REGEX\f[B], \f[CB]acct:REGEX\f[B]\f[R]
\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R]
match account names by this regular expression.
(With no prefix, \f[C]acct:\f[R] is assumed.)
same as above
.TP
.B \f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[B]\f[R]
\f[B]\f[R]\f[C]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[R]\f[B]\f[R]
match postings with a single-commodity amount that is equal to, less
than, or greater than N.
(Multi-commodity amounts are not tested, and will always match.) The
@ -1659,10 +1660,10 @@ comparison has two modes: if N is preceded by a + or - sign (or is 0),
the two signed numbers are compared.
Otherwise, the absolute magnitudes are compared, ignoring sign.
.TP
.B \f[B]\f[CB]code:REGEX\f[B]\f[R]
\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R]
match by transaction code (eg check number)
.TP
.B \f[B]\f[CB]cur:REGEX\f[B]\f[R]
\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R]
match postings or transactions including any amounts whose
currency/commodity symbol is fully matched by REGEX.
(For a partial match, use \f[C].*REGEX.*\f[R]).
@ -1673,10 +1674,10 @@ quoting to hide it from the shell, so eg do:
\f[C]hledger print cur:\[aq]\[rs]$\[aq]\f[R] or
\f[C]hledger print cur:\[rs]\[rs]$\f[R].
.TP
.B \f[B]\f[CB]desc:REGEX\f[B]\f[R]
\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R]
match transaction descriptions.
.TP
.B \f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]
\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R]
match dates within the specified period.
PERIODEXPR is a period expression (with no report interval).
Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
@ -1684,27 +1685,27 @@ Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R],
If the \f[C]--date2\f[R] command line flag is present, this matches
secondary dates instead.
.TP
.B \f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]
\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R]
match secondary dates within the specified period.
.TP
.B \f[B]\f[CB]depth:N\f[B]\f[R]
\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R]
match (or display, depending on command) accounts at or above this depth
.TP
.B \f[B]\f[CB]note:REGEX\f[B]\f[R]
\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R]
match transaction notes (part of description right of \f[C]|\f[R], or
whole description when there\[aq]s no \f[C]|\f[R])
.TP
.B \f[B]\f[CB]payee:REGEX\f[B]\f[R]
\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R]
match transaction payee/payer names (part of description left of
\f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R])
.TP
.B \f[B]\f[CB]real:, real:0\f[B]\f[R]
\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R]
match real or virtual postings respectively
.TP
.B \f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]
\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R]
match unmarked, pending, or cleared transactions respectively
.TP
.B \f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]
\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R]
match by tag name, and optionally also by tag value.
Note a tag: query is considered to match a transaction if it matches any
of the postings.
@ -1714,7 +1715,7 @@ transaction.
The following special search term is used automatically in hledger-web,
only:
.TP
.B \f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]
\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R]
tells hledger-web to show the transaction register for this account.
Can be filtered further with \f[C]acct\f[R] etc.
.PP
@ -1749,6 +1750,8 @@ accounts, a
.PD
Show account names.
.PP
$FLAGS$
.PP
This command lists account names, either declared with account
directives (--declared), posted to (--used), or both (the default).
With query arguments, only matched account names and account names
@ -1784,6 +1787,8 @@ activity
.PD
Show an ascii barchart of posting counts per interval.
.PP
$FLAGS$
.PP
The activity command displays an ascii histogram showing transaction
counts by day, week, month or other reporting interval (by day is the
default).
@ -1808,6 +1813,8 @@ add
.PD
Prompt for transactions and add them to the journal.
.PP
$FLAGS$
.PP
Many hledger users edit their journals directly with a text editor, or
generate them from CSV.
For more interactive data entry, there is the \f[C]add\f[R] command,
@ -1891,6 +1898,8 @@ balance, bal, b
.PD
Show accounts and their balances.
.PP
$FLAGS$
.PP
The balance command is hledger\[aq]s most versatile command.
Note, despite the name, it is not always used for showing real-world
account balances; the more accounting-aware balancesheet and
@ -2512,6 +2521,8 @@ Note this report shows all account balances with normal positive sign
(like conventional financial statements, unlike balance/print/register)
(experimental).
.PP
$FLAGS$
.PP
Example:
.IP
.nf
@ -2559,6 +2570,8 @@ balancesheetequity, bse
Just like balancesheet, but also reports Equity (which it assumes is
under a top-level \f[C]equity\f[R] account).
.PP
$FLAGS$
.PP
Example:
.IP
.nf
@ -2603,6 +2616,8 @@ Note this report shows all account balances with normal positive sign
(like conventional financial statements, unlike balance/print/register)
(experimental).
.PP
$FLAGS$
.PP
Example:
.IP
.nf
@ -2644,6 +2659,8 @@ With --date2, checks secondary dates instead.
With --strict, dates must also be unique.
With a query, only matched transactions\[aq] dates are checked.
Reads the default journal file, or another specified with -f.
.PP
$FLAGS$
.SS check-dupes
.PP
check-dupes
@ -2654,6 +2671,8 @@ Reports account names having the same leaf but different prefixes.
In other words, two or more leaves that are categorized differently.
Reads the default journal file, or another specified as an argument.
.PP
$FLAGS$
.PP
An example: http://stefanorodighiero.net/software/hledger-dupes.html
.SS close
.PP
@ -2668,6 +2687,8 @@ Useful for bringing asset/liability balances forward into a new journal
file, or for closing out revenues/expenses to retained earnings at the
end of a period.
.PP
$FLAGS$
.PP
The closing transaction transfers balances to \[dq]equity:closing
balances\[dq], and the opening transaction transfers balances from
\[dq]equity:opening balances\[dq], or you can customise these with the
@ -2773,10 +2794,14 @@ commodities
.P
.PD
List all commodity/currency symbols used or declared in the journal.
.PP
$FLAGS$
.SS descriptions
.PP
descriptions Show descriptions.
.PP
$FLAGS$
.PP
This command lists all descriptions that appear in transactions.
.PP
Examples:
@ -2810,6 +2835,8 @@ from your bank (eg as CSV data).
When hledger and your bank disagree about the account balance, you can
compare the bank data with your journal to find out the cause.
.PP
$FLAGS$
.PP
Examples:
.IP
.nf
@ -2834,6 +2861,8 @@ files
List all files included in the journal.
With a REGEX argument, only file names matching the regular expression
(case sensitive) are shown.
.PP
$FLAGS$
.SS help
.PP
help
@ -2842,6 +2871,8 @@ help
.PD
Show any of the hledger manuals.
.PP
$FLAGS$
.PP
The \f[C]help\f[R] command displays any of the main hledger manuals, in
one of several ways.
Run it with no argument to list the manuals, or provide a full or
@ -2894,6 +2925,8 @@ Or with --dry-run, just print the transactions that would be added.
Or with --catchup, just mark all of the FILEs\[aq] transactions as
imported, without actually importing any.
.PP
$FLAGS$
.PP
The input files are specified as arguments - no need to write -f before
each one.
So eg to add new transactions from all CSV files to the main journal,
@ -2946,6 +2979,8 @@ Note this report shows all account balances with normal positive sign
(like conventional financial statements, unlike balance/print/register)
(experimental).
.PP
$FLAGS$
.PP
This command displays a simple income statement.
It currently assumes that you have top-level accounts named
\f[C]income\f[R] (or \f[C]revenue\f[R]) and \f[C]expense\f[R] (plural
@ -2990,6 +3025,8 @@ selection.
.PP
notes Show notes.
.PP
$FLAGS$
.PP
This command lists all notes that appear in transactions.
.PP
Examples:
@ -3005,6 +3042,8 @@ Snacks
.PP
payees Show payee names.
.PP
$FLAGS$
.PP
This command lists all payee names that appear in transactions.
.PP
Examples:
@ -3030,6 +3069,8 @@ With --inverted-costs, also print inverse prices based on transaction
prices.
Prices (and postings providing prices) can be filtered by a query.
Price amounts are always displayed with their full precision.
.PP
$FLAGS$
.SS print
.PP
print, txns, p
@ -3038,6 +3079,8 @@ print, txns, p
.PD
Show transaction journal entries, sorted by date.
.PP
$FLAGS$
.PP
The print command displays full journal entries (transactions) from the
journal file in date order, tidily formatted.
With --date2, transactions are sorted by secondary date instead.
@ -3164,6 +3207,8 @@ print-unique
.PD
Print transactions which do not reuse an already-seen description.
.PP
$FLAGS$
.PP
Example:
.IP
.nf
@ -3187,6 +3232,8 @@ register, reg, r
.PD
Show postings and their running total.
.PP
$FLAGS$
.PP
The register command displays postings in date order, one per line, and
their running total.
This is typically used with a query selecting a particular account, to
@ -3343,6 +3390,8 @@ If there are multiple equally good matches, it shows the most recent.
Query options (options, not arguments) can be used to restrict the
search space.
Helps ledger-autosync detect already-seen transactions when importing.
.PP
$FLAGS$
.SS rewrite
.PP
rewrite
@ -3353,6 +3402,8 @@ Print all transactions, rewriting the postings of matched transactions.
For now the only rewrite available is adding new postings, like print
--auto.
.PP
$FLAGS$
.PP
This is a start at a generic rewriter of transaction entries.
It reads the default journal and prints the transactions, like print,
but adds one or more specified postings to any transactions matching
@ -3524,6 +3575,8 @@ roi
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on
your investments.
.PP
$FLAGS$
.PP
This command assumes that you have account(s) that hold nothing but your
investments and whenever you record current appraisal/valuation of these
investments you offset unrealized profit and loss into account(s) that,
@ -3550,6 +3603,8 @@ stats
.PD
Show some journal statistics.
.PP
$FLAGS$
.PP
The stats command displays summary information for the whole journal, or
a matched part of it.
With a reporting interval, it shows a report for each report period.
@ -3587,6 +3642,8 @@ With a TAGREGEX argument, only tag names matching the regular expression
With QUERY arguments, only transactions matching the query are
considered.
With --values flag, the tags\[aq] unique values are listed instead.
.PP
$FLAGS$
.SS test
.PP
test
@ -3595,6 +3652,8 @@ test
.PD
Run built-in unit tests.
.PP
$FLAGS$
.PP
This command runs the unit tests built in to hledger and hledger-lib,
printing the results on stdout.
If any test fails, the exit code will be non-zero.
@ -3662,10 +3721,6 @@ hledger-web provides a simple web interface.
.PP
These are maintained separately, and usually updated shortly after a
hledger release.
.SS diff
.PP
hledger-diff shows differences in an account\[aq]s transactions between
one journal file and another.
.SS iadd
.PP
hledger-iadd is a more interactive, terminal UI replacement for the add
@ -3674,10 +3729,6 @@ command.
.PP
hledger-interest generates interest transactions for an account
according to various schemes.
.SS irr
.PP
hledger-irr calculates the internal rate of return of an investment
account, but it\[aq]s superseded now by the built-in roi command.
.SS Experimental add-ons
.PP
These are available in source form in the hledger repo\[aq]s bin/
@ -3693,10 +3744,7 @@ formats, and can also download the data if your bank offers OFX Direct
Connect.
.SS chart
.PP
hledger-chart.hs is an old pie chart generator, in need of some love.
.SS check
.PP
hledger-check.hs checks more powerful account balance assertions.
hledger-chart.hs is an old very basic pie chart generator.
.SH ENVIRONMENT
.PP
\f[B]COLUMNS\f[R] The screen width used by the register command.

437
hledger/hledger.info
View File

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

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
@ -179,7 +179,8 @@ by most hledger commands, run 'hledger -h'.
use some other field or tag for the account name
'-I --ignore-assertions'
ignore any failing balance assertions
disable balance assertion checks (note: does not disable balance
assignments)
General reporting options:
@ -1347,6 +1348,8 @@ File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS
accounts, a
Show account names.
$FLAGS$
This command lists account names, either declared with account
directives (-declared), posted to (-used), or both (the default). With
query arguments, only matched account names and account names referenced
@ -1377,6 +1380,8 @@ File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS
activity
Show an ascii barchart of posting counts per interval.
$FLAGS$
The activity command displays an ascii histogram showing transaction
counts by day, week, month or other reporting interval (by day is the
default). With query arguments, it counts only matched transactions.
@ -1398,6 +1403,8 @@ File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS
add
Prompt for transactions and add them to the journal.
$FLAGS$
Many hledger users edit their journals directly with a text editor,
or generate them from CSV. For more interactive data entry, there is the
'add' command, which prompts interactively on the console for new
@ -1469,6 +1476,8 @@ File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMAN
balance, bal, b
Show accounts and their balances.
$FLAGS$
The balance command is hledger's most versatile command. Note,
despite the name, it is not always used for showing real-world account
balances; the more accounting-aware balancesheet and incomestatement may
@ -2040,6 +2049,8 @@ date). It assumes that these accounts are under a top-level 'asset' or
(like conventional financial statements, unlike balance/print/register)
(experimental).
$FLAGS$
Example:
$ hledger balancesheet
@ -2083,6 +2094,8 @@ balancesheetequity, bse
Just like balancesheet, but also reports Equity (which it assumes is
under a top-level 'equity' account).
$FLAGS$
Example:
$ hledger balancesheetequity
@ -2123,6 +2136,8 @@ contain 'receivable' or 'A/R' in their name. Note this report shows all
account balances with normal positive sign (like conventional financial
statements, unlike balance/print/register) (experimental).
$FLAGS$
Example:
$ hledger cashflow
@ -2160,6 +2175,8 @@ checks secondary dates instead. With -strict, dates must also be
unique. With a query, only matched transactions' dates are checked.
Reads the default journal file, or another specified with -f.
$FLAGS$

File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS
@ -2171,6 +2188,8 @@ Reports account names having the same leaf but different prefixes. In
other words, two or more leaves that are categorized differently. Reads
the default journal file, or another specified as an argument.
$FLAGS$
An example: http://stefanorodighiero.net/software/hledger-dupes.html

@ -2186,6 +2205,8 @@ Useful for bringing asset/liability balances forward into a new journal
file, or for closing out revenues/expenses to retained earnings at the
end of a period.
$FLAGS$
The closing transaction transfers balances to "equity:closing
balances", and the opening transaction transfers balances from
"equity:opening balances", or you can customise these with the
@ -2272,6 +2293,8 @@ File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up:
commodities
List all commodity/currency symbols used or declared in the journal.
$FLAGS$

File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS
@ -2280,6 +2303,8 @@ File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: C
descriptions Show descriptions.
$FLAGS$
This command lists all descriptions that appear in transactions.
Examples:
@ -2312,6 +2337,8 @@ from your bank (eg as CSV data). When hledger and your bank disagree
about the account balance, you can compare the bank data with your
journal to find out the cause.
$FLAGS$
Examples:
$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
@ -2334,6 +2361,8 @@ files
List all files included in the journal. With a REGEX argument, only
file names matching the regular expression (case sensitive) are shown.
$FLAGS$

File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS
@ -2343,6 +2372,8 @@ File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS
help
Show any of the hledger manuals.
$FLAGS$
The 'help' command displays any of the main hledger manuals, in one
of several ways. Run it with no argument to list the manuals, or
provide a full or partial manual name to select one.
@ -2386,6 +2417,8 @@ the main journal file. Or with -dry-run, just print the transactions
that would be added. Or with -catchup, just mark all of the FILEs'
transactions as imported, without actually importing any.
$FLAGS$
The input files are specified as arguments - no need to write -f
before each one. So eg to add new transactions from all CSV files to
the main journal, it's just: 'hledger import *.csv'
@ -2436,6 +2469,8 @@ plural forms also allowed). Note this report shows all account balances
with normal positive sign (like conventional financial statements,
unlike balance/print/register) (experimental).
$FLAGS$
This command displays a simple income statement. It currently
assumes that you have top-level accounts named 'income' (or 'revenue')
and 'expense' (plural forms also allowed.)
@ -2478,6 +2513,8 @@ File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: CO
notes Show notes.
$FLAGS$
This command lists all notes that appear in transactions.
Examples:
@ -2494,6 +2531,8 @@ File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS
payees Show payee names.
$FLAGS$
This command lists all payee names that appear in transactions.
Examples:
@ -2516,6 +2555,8 @@ synthetic market prices based on transaction prices. With
Prices (and postings providing prices) can be filtered by a query.
Price amounts are always displayed with their full precision.
$FLAGS$

File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS
@ -2525,6 +2566,8 @@ File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMA
print, txns, p
Show transaction journal entries, sorted by date.
$FLAGS$
The print command displays full journal entries (transactions) from
the journal file in date order, tidily formatted. With -date2,
transactions are sorted by secondary date instead.
@ -2626,6 +2669,8 @@ File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COM
print-unique
Print transactions which do not reuse an already-seen description.
$FLAGS$
Example:
$ cat unique.journal
@ -2647,6 +2692,8 @@ File: hledger.info, Node: register, Next: register-match, Prev: print-unique,
register, reg, r
Show postings and their running total.
$FLAGS$
The register command displays postings in date order, one per line,
and their running total. This is typically used with a query selecting
a particular account, to see that account's activity:
@ -2772,6 +2819,8 @@ good matches, it shows the most recent. Query options (options, not
arguments) can be used to restrict the search space. Helps
ledger-autosync detect already-seen transactions when importing.
$FLAGS$

File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS
@ -2783,6 +2832,8 @@ Print all transactions, rewriting the postings of matched transactions.
For now the only rewrite available is adding new postings, like print
-auto.
$FLAGS$
This is a start at a generic rewriter of transaction entries. It
reads the default journal and prints the transactions, like print, but
adds one or more specified postings to any transactions matching QUERY.
@ -2938,6 +2989,8 @@ roi
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on
your investments.
$FLAGS$
This command assumes that you have account(s) that hold nothing but
your investments and whenever you record current appraisal/valuation of
these investments you offset unrealized profit and loss into account(s)
@ -2965,6 +3018,8 @@ File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS
stats
Show some journal statistics.
$FLAGS$
The stats command displays summary information for the whole journal,
or a matched part of it. With a reporting interval, it shows a report
for each report period.
@ -3000,6 +3055,8 @@ shown. With QUERY arguments, only transactions matching the query are
considered. With -values flag, the tags' unique values are listed
instead.
$FLAGS$

File: hledger.info, Node: test, Prev: tags, Up: COMMANDS
@ -3009,6 +3066,8 @@ File: hledger.info, Node: test, Prev: tags, Up: COMMANDS
test
Run built-in unit tests.
$FLAGS$
This command runs the unit tests built in to hledger and hledger-lib,
printing the results on stdout. If any test fails, the exit code will
be non-zero.
@ -3106,44 +3165,27 @@ hledger release.
* Menu:
* diff::
* iadd::
* interest::
* irr::
5.2.1 diff
----------
hledger-diff shows differences in an account's transactions between one
journal file and another.

File: hledger.info, Node: iadd, Next: interest, Prev: , Up: Third party add-ons
File: hledger.info, Node: iadd, Next: interest, Up: Third party add-ons
5.2.2 iadd
5.2.1 iadd
----------
hledger-iadd is a more interactive, terminal UI replacement for the add
command.

File: hledger.info, Node: interest, Next: irr, Prev: iadd, Up: Third party add-ons
File: hledger.info, Node: interest, Prev: iadd, Up: Third party add-ons
5.2.3 interest
5.2.2 interest
--------------
hledger-interest generates interest transactions for an account
according to various schemes.

File: hledger.info, Node: irr, Prev: interest, Up: Third party add-ons
5.2.4 irr
---------
hledger-irr calculates the internal rate of return of an investment
account, but it's superseded now by the built-in roi command.

File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS
@ -3158,7 +3200,6 @@ and tweaking these is a good way to start making your own!
* autosync::
* chart::
* check::

File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons
@ -3172,20 +3213,12 @@ and some CSV formats, and can also download the data if your bank offers
OFX Direct Connect.

File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons
File: hledger.info, Node: chart, Prev: autosync, Up: Experimental add-ons
5.3.2 chart
-----------
hledger-chart.hs is an old pie chart generator, in need of some love.

File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons
5.3.3 check
-----------
hledger-check.hs checks more powerful account balance assertions.
hledger-chart.hs is an old very basic pie chart generator.

Tag Table:
@ -3196,173 +3229,173 @@ Node: OPTIONS3637
Ref: #options3739
Node: General options4138
Ref: #general-options4263
Node: Command options6917
Ref: #command-options7068
Node: Command arguments7466
Ref: #command-arguments7620
Node: Argument files7741
Ref: #argument-files7917
Node: Special characters in arguments and queries8183
Ref: #special-characters-in-arguments-and-queries8417
Node: More escaping8868
Ref: #more-escaping9030
Node: Even more escaping9326
Ref: #even-more-escaping9520
Node: Less escaping10191
Ref: #less-escaping10353
Node: Command line tips10598
Ref: #command-line-tips10784
Node: Unicode characters11161
Ref: #unicode-characters11317
Node: Input files12729
Ref: #input-files12865
Node: Smart dates14794
Ref: #smart-dates14935
Node: Report start & end date16341
Ref: #report-start-end-date16513
Node: Report intervals17937
Ref: #report-intervals18102
Node: Period expressions18492
Ref: #period-expressions18652
Node: Depth limiting22607
Ref: #depth-limiting22751
Node: Pivoting23093
Ref: #pivoting23216
Node: Valuation24892
Ref: #valuation25021
Node: -B Cost25201
Ref: #b-cost25312
Node: -V Market value25510
Ref: #v-market-value25684
Node: -X Market value in specified commodity27116
Ref: #x-market-value-in-specified-commodity27355
Node: --value Flexible valuation27531
Ref: #value-flexible-valuation27757
Node: Effect of --value on reports31947
Ref: #effect-of---value-on-reports32163
Node: Combining -B -V -X --value37094
Ref: #combining--b--v--x---value37277
Node: Output destination37313
Ref: #output-destination37465
Node: Output format37748
Ref: #output-format37900
Node: Regular expressions38285
Ref: #regular-expressions38422
Node: QUERIES39783
Ref: #queries39885
Node: COMMANDS43847
Ref: #commands43959
Node: accounts45023
Ref: #accounts45121
Node: activity45820
Ref: #activity45930
Node: add46313
Ref: #add46412
Node: balance49157
Ref: #balance49268
Node: Classic balance report50726
Ref: #classic-balance-report50899
Node: Customising the classic balance report52268
Ref: #customising-the-classic-balance-report52496
Node: Colour support54572
Ref: #colour-support54739
Node: Flat mode54912
Ref: #flat-mode55060
Node: Depth limited balance reports55473
Ref: #depth-limited-balance-reports55658
Node: Percentages56114
Ref: #percentages56280
Node: Multicolumn balance report57417
Ref: #multicolumn-balance-report57597
Node: Budget report62911
Ref: #budget-report63054
Node: Nested budgets68256
Ref: #nested-budgets68368
Ref: #output-format-171848
Node: balancesheet71926
Ref: #balancesheet72062
Node: balancesheetequity73445
Ref: #balancesheetequity73594
Node: cashflow74155
Ref: #cashflow74283
Node: check-dates75379
Ref: #check-dates75506
Node: check-dupes75785
Ref: #check-dupes75909
Node: close76202
Ref: #close76316
Node: commodities79982
Ref: #commodities80109
Node: descriptions80191
Ref: #descriptions80319
Node: diff80500
Ref: #diff80606
Node: files81653
Ref: #files81753
Node: help81900
Ref: #help82000
Node: import83081
Ref: #import83195
Node: Importing balance assignments84088
Ref: #importing-balance-assignments84236
Node: incomestatement84885
Ref: #incomestatement85018
Node: notes86422
Ref: #notes86535
Node: payees86661
Ref: #payees86767
Node: prices86925
Ref: #prices87031
Node: print87372
Ref: #print87482
Node: print-unique91975
Ref: #print-unique92101
Node: register92386
Ref: #register92513
Node: Custom register output96685
Ref: #custom-register-output96814
Node: register-match98076
Ref: #register-match98210
Node: rewrite98561
Ref: #rewrite98676
Node: Re-write rules in a file100531
Ref: #re-write-rules-in-a-file100665
Node: Diff output format101875
Ref: #diff-output-format102044
Node: rewrite vs print --auto103136
Ref: #rewrite-vs.-print---auto103315
Node: roi103871
Ref: #roi103969
Node: stats104981
Ref: #stats105080
Node: tags105868
Ref: #tags105966
Node: test106260
Ref: #test106344
Node: ADD-ON COMMANDS107091
Ref: #add-on-commands107201
Node: Official add-ons108489
Ref: #official-add-ons108629
Node: ui108709
Ref: #ui108796
Node: web108850
Ref: #web108939
Node: Third party add-ons108985
Ref: #third-party-add-ons109160
Ref: #diff-1109319
Node: iadd109418
Ref: #iadd109528
Node: interest109610
Ref: #interest109731
Node: irr109826
Ref: #irr109924
Node: Experimental add-ons110055
Ref: #experimental-add-ons110207
Node: autosync110455
Ref: #autosync110566
Node: chart110805
Ref: #chart110924
Node: check110995
Ref: #check111097
Node: Command options6962
Ref: #command-options7113
Node: Command arguments7511
Ref: #command-arguments7665
Node: Argument files7786
Ref: #argument-files7962
Node: Special characters in arguments and queries8228
Ref: #special-characters-in-arguments-and-queries8462
Node: More escaping8913
Ref: #more-escaping9075
Node: Even more escaping9371
Ref: #even-more-escaping9565
Node: Less escaping10236
Ref: #less-escaping10398
Node: Command line tips10643
Ref: #command-line-tips10829
Node: Unicode characters11206
Ref: #unicode-characters11362
Node: Input files12774
Ref: #input-files12910
Node: Smart dates14839
Ref: #smart-dates14980
Node: Report start & end date16386
Ref: #report-start-end-date16558
Node: Report intervals17982
Ref: #report-intervals18147
Node: Period expressions18537
Ref: #period-expressions18697
Node: Depth limiting22652
Ref: #depth-limiting22796
Node: Pivoting23138
Ref: #pivoting23261
Node: Valuation24937
Ref: #valuation25066
Node: -B Cost25246
Ref: #b-cost25357
Node: -V Market value25555
Ref: #v-market-value25729
Node: -X Market value in specified commodity27161
Ref: #x-market-value-in-specified-commodity27400
Node: --value Flexible valuation27576
Ref: #value-flexible-valuation27802
Node: Effect of --value on reports31992
Ref: #effect-of---value-on-reports32208
Node: Combining -B -V -X --value37139
Ref: #combining--b--v--x---value37322
Node: Output destination37358
Ref: #output-destination37510
Node: Output format37793
Ref: #output-format37945
Node: Regular expressions38330
Ref: #regular-expressions38467
Node: QUERIES39828
Ref: #queries39930
Node: COMMANDS43892
Ref: #commands44004
Node: accounts45068
Ref: #accounts45166
Node: activity45877
Ref: #activity45987
Node: add46382
Ref: #add46481
Node: balance49232
Ref: #balance49343
Node: Classic balance report50813
Ref: #classic-balance-report50986
Node: Customising the classic balance report52355
Ref: #customising-the-classic-balance-report52583
Node: Colour support54659
Ref: #colour-support54826
Node: Flat mode54999
Ref: #flat-mode55147
Node: Depth limited balance reports55560
Ref: #depth-limited-balance-reports55745
Node: Percentages56201
Ref: #percentages56367
Node: Multicolumn balance report57504
Ref: #multicolumn-balance-report57684
Node: Budget report62998
Ref: #budget-report63141
Node: Nested budgets68343
Ref: #nested-budgets68455
Ref: #output-format-171936
Node: balancesheet72014
Ref: #balancesheet72150
Node: balancesheetequity73545
Ref: #balancesheetequity73694
Node: cashflow74267
Ref: #cashflow74395
Node: check-dates75503
Ref: #check-dates75630
Node: check-dupes75921
Ref: #check-dupes76045
Node: close76350
Ref: #close76464
Node: commodities80142
Ref: #commodities80269
Node: descriptions80363
Ref: #descriptions80491
Node: diff80684
Ref: #diff80790
Node: files81849
Ref: #files81949
Node: help82108
Ref: #help82208
Node: import83301
Ref: #import83415
Node: Importing balance assignments84320
Ref: #importing-balance-assignments84468
Node: incomestatement85117
Ref: #incomestatement85250
Node: notes86666
Ref: #notes86779
Node: payees86917
Ref: #payees87023
Node: prices87193
Ref: #prices87299
Node: print87652
Ref: #print87762
Node: print-unique92267
Ref: #print-unique92393
Node: register92690
Ref: #register92817
Node: Custom register output97001
Ref: #custom-register-output97130
Node: register-match98392
Ref: #register-match98526
Node: rewrite98889
Ref: #rewrite99004
Node: Re-write rules in a file100871
Ref: #re-write-rules-in-a-file101005
Node: Diff output format102215
Ref: #diff-output-format102384
Node: rewrite vs print --auto103476
Ref: #rewrite-vs.-print---auto103655
Node: roi104211
Ref: #roi104309
Node: stats105333
Ref: #stats105432
Node: tags106232
Ref: #tags106330
Node: test106636
Ref: #test106720
Node: ADD-ON COMMANDS107479
Ref: #add-on-commands107589
Node: Official add-ons108877
Ref: #official-add-ons109017
Node: ui109097
Ref: #ui109184
Node: web109238
Ref: #web109327
Node: Third party add-ons109373
Ref: #third-party-add-ons109548
Node: iadd109667
Ref: #iadd109768
Node: interest109850
Ref: #interest109959
Node: Experimental add-ons110054
Ref: #experimental-add-ons110206
Node: autosync110444
Ref: #autosync110555
Node: chart110794
Ref: #chart110899

End Tag Table

Local Variables:
coding: utf-8
End:

534
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff