simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-09-19 10:17:35 +03:00
Code Issues Projects Releases Wiki Activity

;doc: regen help/manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-02-22 11:33:50 -08:00
parent b9b5702946
commit 696ec4998b
18 changed files with 1246 additions and 1168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
hledger-lib/hledger_csv.5
View File

@ -156,7 +156,7 @@ fields date, description, amount-out, amount-in, balance
# We generate balance assertions by assigning to \[dq]balance\[dq]
# above, but you may sometimes need to remove these because:
#
# - the CSV balance differs from the true balance,
# - the CSV balance differs from the true balance,
# by up to 0.0000000000005 in my experience
#
# - it is sometimes calculated based on non-chronological ordering,
@ -237,7 +237,7 @@ amount2 %amzamount
# add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead.
# (Regex translation: \[dq]a field containing a non-zero dollar amount,
# (Regex translation: \[dq]a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields\[dq])
if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$
account3 expenses:fees
@ -298,11 +298,11 @@ date-format %-m/%-d/%Y
if
In Progress
Temporary Hold
Update to
Update to
skip
# add more fields to the description
description %description_ %itemtitle
description %description_ %itemtitle
# save some other fields as tags
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
@ -350,9 +350,9 @@ include common.rules
# apply some overrides specific to this csv
# Transfers from/to bank. These are usually marked Pending,
# Transfers from/to bank. These are usually marked Pending,
# which can be disregarded in this case.
if
if
Bank Account
Bank Deposit to PP Account
description %type for %referencetxnid %itemtitle

116
hledger-lib/hledger_csv.info
View File

@ -118,7 +118,7 @@ fields date, description, amount-out, amount-in, balance
# We generate balance assertions by assigning to "balance"
# above, but you may sometimes need to remove these because:
#
# - the CSV balance differs from the true balance,
# - the CSV balance differs from the true balance,
# by up to 0.0000000000005 in my experience
#
# - it is sometimes calculated based on non-chronological ordering,
@ -191,7 +191,7 @@ amount2 %amzamount
# add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead.
# (Regex translation: "a field containing a non-zero dollar amount,
# (Regex translation: "a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields")
if ,\$[1-9][.0-9]+(,[^,]*){1}$
account3 expenses:fees
@ -245,11 +245,11 @@ date-format %-m/%-d/%Y
if
In Progress
Temporary Hold
Update to
Update to
skip
# add more fields to the description
description %description_ %itemtitle
description %description_ %itemtitle
# save some other fields as tags
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
@ -297,9 +297,9 @@ include common.rules
# apply some overrides specific to this csv
# Transfers from/to bank. These are usually marked Pending,
# Transfers from/to bank. These are usually marked Pending,
# which can be disregarded in this case.
if
if
Bank Account
Bank Deposit to PP Account
description %type for %referencetxnid %itemtitle
@ -974,58 +974,58 @@ Node: Basic2413
Ref: #basic2513
Node: Bank of Ireland3055
Ref: #bank-of-ireland3190
Node: Amazon4653
Ref: #amazon4771
Node: Paypal6704
Ref: #paypal6798
Node: CSV RULES14681
Ref: #csv-rules14790
Node: skip15066
Ref: #skip15159
Node: fields15534
Ref: #fields15656
Node: Transaction field names16821
Ref: #transaction-field-names16981
Node: Posting field names17092
Ref: #posting-field-names17244
Node: field assignment18535
Ref: #field-assignment18678
Node: separator19496
Ref: #separator19625
Node: if20036
Ref: #if20138
Node: end21854
Ref: #end21960
Node: date-format22184
Ref: #date-format22316
Node: newest-first23065
Ref: #newest-first23203
Node: include23886
Ref: #include24015
Node: balance-type24459
Ref: #balance-type24579
Node: TIPS25279
Ref: #tips25361
Node: Rapid feedback25617
Ref: #rapid-feedback25734
Node: Valid CSV26194
Ref: #valid-csv26324
Node: File Extension26516
Ref: #file-extension26668
Node: Reading multiple CSV files27078
Ref: #reading-multiple-csv-files27263
Node: Valid transactions27504
Ref: #valid-transactions27682
Node: Deduplicating importing28310
Ref: #deduplicating-importing28489
Node: Setting amounts29522
Ref: #setting-amounts29691
Node: Setting currency/commodity30677
Ref: #setting-currencycommodity30869
Node: Referencing other fields31672
Ref: #referencing-other-fields31872
Node: How CSV rules are evaluated32769
Ref: #how-csv-rules-are-evaluated32942
Node: Amazon4652
Ref: #amazon4770
Node: Paypal6702
Ref: #paypal6796
Node: CSV RULES14675
Ref: #csv-rules14784
Node: skip15060
Ref: #skip15153
Node: fields15528
Ref: #fields15650
Node: Transaction field names16815
Ref: #transaction-field-names16975
Node: Posting field names17086
Ref: #posting-field-names17238
Node: field assignment18529
Ref: #field-assignment18672
Node: separator19490
Ref: #separator19619
Node: if20030
Ref: #if20132
Node: end21848
Ref: #end21954
Node: date-format22178
Ref: #date-format22310
Node: newest-first23059
Ref: #newest-first23197
Node: include23880
Ref: #include24009
Node: balance-type24453
Ref: #balance-type24573
Node: TIPS25273
Ref: #tips25355
Node: Rapid feedback25611
Ref: #rapid-feedback25728
Node: Valid CSV26188
Ref: #valid-csv26318
Node: File Extension26510
Ref: #file-extension26662
Node: Reading multiple CSV files27072
Ref: #reading-multiple-csv-files27257
Node: Valid transactions27498
Ref: #valid-transactions27676
Node: Deduplicating importing28304
Ref: #deduplicating-importing28483
Node: Setting amounts29516
Ref: #setting-amounts29685
Node: Setting currency/commodity30671
Ref: #setting-currencycommodity30863
Node: Referencing other fields31666
Ref: #referencing-other-fields31866
Node: How CSV rules are evaluated32763
Ref: #how-csv-rules-are-evaluated32936

End Tag Table

79
hledger-lib/hledger_journal.5
View File

@ -443,7 +443,7 @@ Eg:
assets:cash $-10 ; <- these balance
expenses:food $7 ; <-
expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance
\f[R]
@ -573,15 +573,15 @@ commodity INR 9,99,99,999.00
commodity 1 000 000.9455
\f[R]
.fi
.SS Amount display format
.SS Amount display style
.PP
For each commodity, hledger chooses a consistent format to use when
displaying amounts.
(Except price amounts, which are always displayed as written).
The display format is chosen as follows:
The display style is chosen as follows:
.IP \[bu] 2
If there is a commodity directive for the commodity, that format is used
(see examples above).
If there is a commodity directive (or default commodity directive) for
the commodity, that format is used (see examples above).
.IP \[bu] 2
Otherwise the format of the first posting amount in that commodity seen
in the journal is used.
@ -591,13 +591,16 @@ maximum from all posting amounts in that commmodity.
Or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[R]).
.PP
Price amounts, and amounts in \f[C]D\f[R] directives don\[aq]t affect
the amount display format directly, but occasionally they can do so
indirectly.
(Eg when D\[aq]s default commodity is applied to a commodity-less
amount, or when an amountless posting is balanced using a price\[aq]s
commodity, or when -V is used.) If you find this causing problems, use a
commodity directive to set the display format.
Transaction prices don\[aq]t affect the amount display style directly,
but occasionally they can do so indirectly (eg when an posting\[aq]s
amount is inferred using a transaction price).
If you find this causing problems, use a commodity directive to fix the
display style.
.PP
In summary: amounts will be displayed much as they appear in your
journal, with the max observed number of decimal places.
If you want to see fewer decimal places in reports, use a commodity
directive to override that.
.SS Transaction prices
.PP
Within a transaction, you can note an amount\[aq]s price in another
@ -753,9 +756,6 @@ Use include or concatenate the files instead.
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity\[aq]s balance within the
(possibly multi-commodity) account balance.
.PD 0
.P
.PD
This is how assertions work in Ledger also.
We could call this a \[dq]partial\[dq] balance assertion.
.PP
@ -861,7 +861,7 @@ balances:
.IP
.nf
\f[C]
; starting a new journal, set asset account balances
; starting a new journal, set asset account balances
2016/1/1 opening balances
assets:checking = $409.32
assets:savings = $735.24
@ -1130,12 +1130,13 @@ The \f[C]commodity\f[R] directive has several functions:
It declares commodities which may be used in the journal.
This is currently not enforced, but can serve as documentation.
.IP "2." 3
It declares what decimal mark character to expect when parsing input -
useful to disambiguate international number formats in your data.
It declares what decimal mark character (period or comma) to expect when
parsing input - useful to disambiguate international number formats in
your data.
(Without this, hledger will parse both \f[C]1,000\f[R] and
\f[C]1.000\f[R] as 1).
.IP "3." 3
It declares the amount display format to use in output - decimal and
It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc.
.PP
You are likely to run into one of the problems solved by commodity
@ -1180,26 +1181,34 @@ The number must include a decimal mark: either a period or a comma,
followed by 0 or more decimal digits.
.SS Default commodity
.PP
The \f[C]D\f[R] 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\[aq]s default commodity directive.) The
commodity and display format will be applied to all subsequent
commodity-less amounts, or until the next \f[C]D\f[R] directive.
The \f[C]D\f[R] directive sets a default commodity, to be used for
amounts without a commodity symbol (ie, plain numbers).
This commodity will be applied to all subsequent commodity-less amounts,
or until the next \f[C]D\f[R] directive.
(Note, this is different from Ledger\[aq]s \f[C]D\f[R].)
.PP
For compatibility/historical reasons, \f[C]D\f[R] also acts like a
\f[C]commodity\f[R] directive, setting the commodity\[aq]s display style
(for output) and decimal mark (for parsing input).
As with \f[C]commodity\f[R], the amount must always be written with a
decimal mark (period or comma).
If both directives are used, \f[C]commodity\f[R]\[aq]s style takes
precedence.
.PP
The syntax is \f[C]D AMOUNT\f[R].
Eg:
.IP
.nf
\f[C]
; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places)
; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b
\f[R]
.fi
.PP
As with the \f[C]commodity\f[R] directive, the amount must always be
written with a decimal point.
.SS Market prices
.PP
The \f[C]P\f[R] directive declares a market price, which is an exchange
@ -1331,7 +1340,7 @@ account assets ; type:Asset
account liabilities ; type:Liability
account equity ; type:Equity
account revenues ; type:Revenue
account expenses ; type:Expenses
account expenses ; type:Expense
\f[R]
.fi
.SS Account types declared with account type codes
@ -1360,8 +1369,8 @@ Eg:
; make \[dq]liabilities\[dq] not have the liability type - who knows why
account liabilities ; type:E
; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities
; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities
account - ; type:L
\f[R]
.fi
@ -1767,8 +1776,8 @@ And each \[dq]posting\[dq] is actually a posting-generating rule:
.nf
\f[C]
= QUERY
ACCT AMT
ACCT [AMT]
ACCOUNT AMOUNT
ACCOUNT [AMOUNT]
...
\f[R]
.fi
@ -1799,7 +1808,7 @@ Eg, note the quotes around the second query term below:
.nf
\f[C]
= expenses:groceries \[aq]expenses:dining out\[aq]
(budget:funds:dining out) *-1
(budget:funds:dining out) *-1
\f[R]
.fi
.PP

261
hledger-lib/hledger_journal.info
View File

@ -406,7 +406,7 @@ zero (separately from other postings). Eg:
assets:cash $-10 ; <- these balance
expenses:food $7 ; <-
expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance
@ -479,10 +479,10 @@ comma:
* Menu:
* Digit group marks::
* Amount display format::
* Amount display style::

File: hledger_journal.info, Node: Digit group marks, Next: Amount display format, Up: Amounts
File: hledger_journal.info, Node: Digit group marks, Next: Amount display style, Up: Amounts
1.8.1 Digit group marks
-----------------------
@ -515,17 +515,17 @@ commodity INR 9,99,99,999.00
commodity 1 000 000.9455

File: hledger_journal.info, Node: Amount display format, Prev: Digit group marks, Up: Amounts
File: hledger_journal.info, Node: Amount display style, Prev: Digit group marks, Up: Amounts
1.8.2 Amount display format
---------------------------
1.8.2 Amount display style
--------------------------
For each commodity, hledger chooses a consistent format to use when
displaying amounts. (Except price amounts, which are always displayed
as written). The display format is chosen as follows:
as written). The display style is chosen as follows:
* If there is a commodity directive for the commodity, that format is
used (see examples above).
* If there is a commodity directive (or default commodity directive)
for the commodity, that format is used (see examples above).
* Otherwise the format of the first posting amount in that commodity
seen in the journal is used. But the number of decimal places
@ -535,12 +535,15 @@ as written). The display format is chosen as follows:
* Or if there are no such amounts in the journal, a default format is
used (like '$1000.00').
Price amounts, and amounts in 'D' directives don't affect the amount
display format directly, but occasionally they can do so indirectly.
(Eg when D's default commodity is applied to a commodity-less amount, or
when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, use a commodity
directive to set the display format.
Transaction prices don't affect the amount display style directly,
but occasionally they can do so indirectly (eg when an posting's amount
is inferred using a transaction price). If you find this causing
problems, use a commodity directive to fix the display style.
In summary: amounts will be displayed much as they appear in your
journal, with the max observed number of decimal places. If you want to
see fewer decimal places in reports, use a commodity directive to
override that.

File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions
@ -691,9 +694,8 @@ File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions
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
"partial" balance assertion.
(possibly multi-commodity) account balance. This is how assertions work
in Ledger also. We could call this a "partial" balance assertion.
To assert the balance of more than one commodity in an account, you
can write multiple postings, each asserting one commodity's balance.
@ -800,7 +802,7 @@ 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
; starting a new journal, set asset account balances
2016/1/1 opening balances
assets:checking = $409.32
assets:savings = $735.24
@ -1011,14 +1013,13 @@ The 'commodity' directive has several functions:
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. (Without this, hledger will parse both '1,000' and '1.000'
as 1).
2. It declares what decimal mark character (period or comma) to expect
when parsing input - useful to disambiguate international number
formats in your data. (Without this, hledger will parse both
'1,000' and '1.000' as 1).
3. It declares the amount display format to use in output - decimal
and digit group marks, number of decimal places, symbol placement
etc.
3. It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity
directives, sooner or later, so it's a good idea to just always use them
@ -1057,23 +1058,27 @@ File: hledger_journal.info, Node: Default commodity, Next: Market prices, Pre
1.12.5 Default commodity
------------------------
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
amounts, or until the next 'D' directive.
The 'D' directive sets a default commodity, to be used for amounts
without a commodity symbol (ie, plain numbers). This commodity will be
applied to all subsequent commodity-less amounts, or until the next 'D'
directive. (Note, this is different from Ledger's 'D'.)
For compatibility/historical reasons, 'D' also acts like a
'commodity' directive, setting the commodity's display style (for
output) and decimal mark (for parsing input). As with 'commodity', the
amount must always be written with a decimal mark (period or comma). If
both directives are used, 'commodity''s style takes precedence.
The syntax is 'D AMOUNT'. Eg:
; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places)
; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b
As with the 'commodity' directive, the amount must always be written
with a decimal point.

File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives
@ -1197,7 +1202,7 @@ account assets ; type:Asset
account liabilities ; type:Liability
account equity ; type:Equity
account revenues ; type:Revenue
account expenses ; type:Expenses
account expenses ; type:Expense
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,
@ -1216,8 +1221,8 @@ need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why
account liabilities ; type:E
; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities
; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities
account - ; type:L

@ -1612,8 +1617,8 @@ certain postings (mnemonic: '=' suggests matching). And each "posting"
is actually a posting-generating rule:
= QUERY
ACCT AMT
ACCT [AMT]
ACCOUNT AMOUNT
ACCOUNT [AMOUNT]
...
These posting-generating rules look like normal postings, except the
@ -1635,7 +1640,7 @@ quotes, as on the command line. Eg, note the quotes around the second
query term below:
= expenses:groceries 'expenses:dining out'
(budget:funds:dining out) *-1
(budget:funds:dining out) *-1
These rules have global effect - a rule appearing anywhere in your
data can potentially affect any transaction, including transactions
@ -1754,92 +1759,92 @@ Node: Postings12506
Ref: #postings12634
Node: Virtual Postings13660
Ref: #virtual-postings13777
Node: Account names15083
Ref: #account-names15224
Node: Amounts15711
Ref: #amounts15850
Node: Digit group marks16783
Ref: #digit-group-marks16932
Node: Amount display format17870
Ref: #amount-display-format18027
Node: Transaction prices19052
Ref: #transaction-prices19218
Node: Balance Assertions21484
Ref: #balance-assertions21664
Node: Assertions and ordering22697
Ref: #assertions-and-ordering22885
Node: Assertions and included files23585
Ref: #assertions-and-included-files23828
Node: Assertions and multiple -f options24161
Ref: #assertions-and-multiple--f-options24417
Node: Assertions and commodities24549
Ref: #assertions-and-commodities24781
Node: Assertions and prices25937
Ref: #assertions-and-prices26151
Node: Assertions and subaccounts26591
Ref: #assertions-and-subaccounts26820
Node: Assertions and virtual postings27144
Ref: #assertions-and-virtual-postings27386
Node: Assertions and precision27528
Ref: #assertions-and-precision27721
Node: Balance Assignments27988
Ref: #balance-assignments28162
Node: Balance assignments and prices29327
Ref: #balance-assignments-and-prices29499
Node: Directives29723
Ref: #directives29882
Node: Comment blocks35530
Ref: #comment-blocks35675
Node: Including other files35851
Ref: #including-other-files36031
Node: Default year36439
Ref: #default-year36608
Node: Declaring commodities37015
Ref: #declaring-commodities37198
Node: Default commodity38859
Ref: #default-commodity39035
Node: Market prices39669
Ref: #market-prices39834
Node: Declaring accounts40675
Ref: #declaring-accounts40851
Node: Account comments41776
Ref: #account-comments41939
Node: Account subdirectives42363
Ref: #account-subdirectives42558
Node: Account types42871
Ref: #account-types43055
Node: Account display order44697
Ref: #account-display-order44867
Node: Rewriting accounts46018
Ref: #rewriting-accounts46203
Node: Basic aliases46929
Ref: #basic-aliases47075
Node: Regex aliases47779
Ref: #regex-aliases47951
Node: Combining aliases48669
Ref: #combining-aliases48847
Node: end aliases50123
Ref: #end-aliases50271
Node: Default parent account50372
Ref: #default-parent-account50538
Node: Periodic transactions51422
Ref: #periodic-transactions51621
Node: Periodic rule syntax53493
Ref: #periodic-rule-syntax53699
Node: Two spaces between period expression and description!54403
Ref: #two-spaces-between-period-expression-and-description54722
Node: Forecasting with periodic transactions55406
Ref: #forecasting-with-periodic-transactions55711
Node: Budgeting with periodic transactions57737
Ref: #budgeting-with-periodic-transactions57976
Node: Auto postings / transaction modifiers58425
Ref: #auto-postings-transaction-modifiers58637
Node: Auto postings and dates61122
Ref: #auto-postings-and-dates61379
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61554
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61929
Node: Auto posting tags62307
Ref: #auto-posting-tags62546
Node: Account names15082
Ref: #account-names15223
Node: Amounts15710
Ref: #amounts15849
Node: Digit group marks16781
Ref: #digit-group-marks16929
Node: Amount display style17867
Ref: #amount-display-style18021
Node: Transaction prices19182
Ref: #transaction-prices19348
Node: Balance Assertions21614
Ref: #balance-assertions21794
Node: Assertions and ordering22827
Ref: #assertions-and-ordering23015
Node: Assertions and included files23715
Ref: #assertions-and-included-files23958
Node: Assertions and multiple -f options24291
Ref: #assertions-and-multiple--f-options24547
Node: Assertions and commodities24679
Ref: #assertions-and-commodities24911
Node: Assertions and prices26068
Ref: #assertions-and-prices26282
Node: Assertions and subaccounts26722
Ref: #assertions-and-subaccounts26951
Node: Assertions and virtual postings27275
Ref: #assertions-and-virtual-postings27517
Node: Assertions and precision27659
Ref: #assertions-and-precision27852
Node: Balance Assignments28119
Ref: #balance-assignments28293
Node: Balance assignments and prices29457
Ref: #balance-assignments-and-prices29629
Node: Directives29853
Ref: #directives30012
Node: Comment blocks35660
Ref: #comment-blocks35805
Node: Including other files35981
Ref: #including-other-files36161
Node: Default year36569
Ref: #default-year36738
Node: Declaring commodities37145
Ref: #declaring-commodities37328
Node: Default commodity39001
Ref: #default-commodity39177
Node: Market prices40066
Ref: #market-prices40231
Node: Declaring accounts41072
Ref: #declaring-accounts41248
Node: Account comments42173
Ref: #account-comments42336
Node: Account subdirectives42760
Ref: #account-subdirectives42955
Node: Account types43268
Ref: #account-types43452
Node: Account display order45091
Ref: #account-display-order45261
Node: Rewriting accounts46412
Ref: #rewriting-accounts46597
Node: Basic aliases47323
Ref: #basic-aliases47469
Node: Regex aliases48173
Ref: #regex-aliases48345
Node: Combining aliases49063
Ref: #combining-aliases49241
Node: end aliases50517
Ref: #end-aliases50665
Node: Default parent account50766
Ref: #default-parent-account50932
Node: Periodic transactions51816
Ref: #periodic-transactions52015
Node: Periodic rule syntax53887
Ref: #periodic-rule-syntax54093
Node: Two spaces between period expression and description!54797
Ref: #two-spaces-between-period-expression-and-description55116
Node: Forecasting with periodic transactions55800
Ref: #forecasting-with-periodic-transactions56105
Node: Budgeting with periodic transactions58131
Ref: #budgeting-with-periodic-transactions58370
Node: Auto postings / transaction modifiers58819
Ref: #auto-postings-transaction-modifiers59031
Node: Auto postings and dates61527
Ref: #auto-postings-and-dates61784
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334
Node: Auto posting tags62712
Ref: #auto-posting-tags62951

End Tag Table

230
hledger-lib/hledger_journal.txt
View File

@ -403,13 +403,13 @@ FILE FORMAT
commodity INR 9,99,99,999.00
commodity 1 000 000.9455
Amount display format
Amount display style
For each commodity, hledger chooses a consistent format to use when
displaying amounts. (Except price amounts, which are always displayed
as written). The display format is chosen as follows:
as written). The display style is chosen as follows:
o If there is a commodity directive for the commodity, that format is
used (see examples above).
o If there is a commodity directive (or default commodity directive)
for the commodity, that format is used (see examples above).
o Otherwise the format of the first posting amount in that commodity
seen in the journal is used. But the number of decimal places ("pre-
@ -419,18 +419,21 @@ FILE FORMAT
o Or if there are no such amounts in the journal, a default format is
used (like $1000.00).
Price amounts, and amounts in D directives don't affect the amount dis-
play format directly, but occasionally they can do so indirectly. (Eg
when D's default commodity is applied to a commodity-less amount, or
when an amountless posting is balanced using a price's commodity, or
when -V is used.) If you find this causing problems, use a commodity
directive to set the display format.
Transaction prices don't affect the amount display style directly, but
occasionally they can do so indirectly (eg when an posting's amount is
inferred using a transaction price). If you find this causing prob-
lems, use a commodity directive to fix the display style.
In summary: amounts will be displayed much as they appear in your jour-
nal, with the max observed number of decimal places. If you want to
see fewer decimal places in reports, use a commodity directive to over-
ride that.
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.
@ -459,7 +462,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:
@ -470,8 +473,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:
@ -484,9 +487,9 @@ FILE FORMAT
EUR100 assets:euros
Balance Assertions
hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a
hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a
and b after each posting:
2013/1/1
@ -498,32 +501,32 @@ FILE FORMAT
b $-1 =$-2
After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
and report an error if any of them fail. Balance assertions can pro-
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. (Note: this flag currently does not disable
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
@ -531,16 +534,15 @@ 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
(possibly multi-commodity) account balance.
This is how assertions work in Ledger also. We could call this a "par-
tial" balance assertion.
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 "partial" balance assertion.
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).
@ -560,7 +562,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
@ -574,21 +576,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
@ -602,16 +604,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
@ -629,14 +631,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
@ -647,79 +649,82 @@ FILE FORMAT
(a) $1 @ EUR2 = $1 @ EUR2
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 to be default commodity:
D declare a commodity to be default commodity:
used for commodityless following commod-
amounts, and its number no- ityless entries un-
tation & display style til end of current
file; number nota-
amounts, and its number no- ityless entries un-
tation & display style til end of current
file; number nota-
tion: following en-
tries in that com-
tries in that com-
modity until end of
current file; dis-
current file; dis-
play style: amounts
of that commodity
in reports
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:
subdi- optional indented directive line immediately following a parent
subdi- optional indented directive line immediately following a parent
rec- directive
tive
number how to interpret numbers when parsing journal entries (the iden-
nota- tity of the decimal separator character). (Currently each com-
nota- tity of the decimal separator character). (Currently each com-
tion modity can have its own notation, even in the same file.)
dis- how to display amounts of a commodity in reports (symbol side
dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places)
style
direc- which entries and (when there are multiple files) which files
direc- which entries and (when there are multiple files) which files
tive are affected by a directive
scope
@ -727,34 +732,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
@ -776,14 +781,15 @@ 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.
(Without this, hledger will parse both 1,000 and 1.000 as 1).
2. It declares what decimal mark character (period or comma) to expect
when parsing input - useful to disambiguate international number
formats in your data. (Without this, hledger will parse both 1,000
and 1.000 as 1).
3. It declares the amount display format to use in output - decimal and
3. It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di-
@ -818,23 +824,27 @@ FILE FORMAT
comma, followed by 0 or more decimal digits.
Default commodity
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
amounts, or until the next D directive.
The D directive sets a default commodity, to be used for amounts with-
out a commodity symbol (ie, plain numbers). This commodity will be ap-
plied to all subsequent commodity-less amounts, or until the next D di-
rective. (Note, this is different from Ledger's D.)
For compatibility/historical reasons, D also acts like a commodity di-
rective, setting the commodity's display style (for output) and decimal
mark (for parsing input). As with commodity, the amount must always be
written with a decimal mark (period or comma). If both directives are
used, commodity's style takes precedence.
The syntax is D AMOUNT. Eg:
; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places)
; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
D $1,000.00
1/1
a 5 ; <- commodity-less amount, becomes $1
a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b
As with the commodity directive, the amount must always be written with
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
@ -935,7 +945,7 @@ FILE FORMAT
account liabilities ; type:Liability
account equity ; type:Equity
account revenues ; type:Revenue
account expenses ; type:Expenses
account expenses ; type:Expense
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
@ -1281,8 +1291,8 @@ FILE FORMAT
actually a posting-generating rule:
= QUERY
ACCT AMT
ACCT [AMT]
ACCOUNT AMOUNT
ACCOUNT [AMOUNT]
...
These posting-generating rules look like normal postings, except the

2
hledger-lib/hledger_timedot.5
View File

@ -55,7 +55,7 @@ An example:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1
inc:client1 .... .... .... .... .... ....
fos:haskell .... ..
fos:haskell .... ..
biz:research .
2016/2/2

2
hledger-lib/hledger_timedot.info
View File

@ -46,7 +46,7 @@ example:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1
inc:client1 .... .... .... .... .... ....
fos:haskell .... ..
fos:haskell .... ..
biz:research .
2016/2/2

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

@ -26,19 +26,17 @@ limited data entry capability.
It is easier than hledger\[aq]s command-line interface, and sometimes
quicker and more convenient than the web interface.
.PP
Note hledger-ui has some different defaults (experimental):
.IP \[bu] 2
it generates rule-based transactions and postings by default (--forecast
and --auto are always on).
.IP \[bu] 2
it hides transactions dated in the future by default (change this with
--future or the F key).
.PP
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc.
.PP
Unlike hledger, hledger-ui hides all future-dated transactions by
default.
They can be revealed, along with any rule-generated periodic
transactions, by pressing the F key (or starting with --forecast) to
enable \[dq]forecast mode\[dq].
.SH OPTIONS
.PP
Note: if invoking hledger-ui as a hledger subcommand, write \f[C]--\f[R]
@ -64,9 +62,6 @@ show accounts as a list (default)
.TP
\f[B]\f[CB]-T --tree\f[B]\f[R]
show accounts as a tree
.TP
\f[B]\f[CB]--future\f[B]\f[R]
show transactions dated later than today (normally hidden)
.PP
hledger input options:
.TP
@ -155,8 +150,9 @@ most recent applicable market price, if any)
apply automated posting rules to modify transactions.
.TP
\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.
generate future transactions from periodic transaction rules, for the
next 6 months or till report end date.
In hledger-ui, also make ordinary future transactions visible.
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -218,12 +214,11 @@ account depth and transaction status (see below).
\f[C]BACKSPACE\f[R] or \f[C]DELETE\f[R] removes all filters, showing all
transactions.
.PP
As mentioned above, hledger-ui shows auto-generated periodic
transactions, and hides future transactions (auto-generated or not) by
default.
\f[C]F\f[R] toggles showing and hiding these future transactions.
This is similar to using a query like \f[C]date:-tomorrow\f[R], but more
convenient.
As mentioned above, by default hledger-ui hides future transactions -
both ordinary transactions recorded in the journal, and periodic
transactions generated by rule.
\f[C]F\f[R] toggles forecast mode, in which future/forecasted
transactions are shown.
(experimental)
.PP
\f[C]ESCAPE\f[R] removes all filters and jumps back to the top screen.
@ -371,9 +366,6 @@ 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 transactions contributing
to the balance shown on the accounts screen.
.PD 0
.P
.PD
Tree mode/flat mode can be toggled with \f[C]T\f[R] here also.
.PP
\f[C]U\f[R] toggles filtering by unmarked status, showing or hiding

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

@ -22,19 +22,17 @@ limited data entry capability. It is easier than hledger's command-line
interface, and sometimes quicker and more convenient than the web
interface.
Note hledger-ui has some different defaults (experimental):
* it generates rule-based transactions and postings by default
(-forecast and -auto are always on).
* it hides transactions dated in the future by default (change this
with -future or the F key).
Like hledger, it reads data from one or more files in hledger
journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc.
Unlike hledger, hledger-ui hides all future-dated transactions by
default. They can be revealed, along with any rule-generated periodic
transactions, by pressing the F key (or starting with -forecast) to
enable "forecast mode".
* Menu:
* OPTIONS::
@ -75,9 +73,6 @@ the data.
'-T --tree'
show accounts as a tree
'--future'
show transactions dated later than today (normally hidden)
hledger input options:
@ -168,8 +163,9 @@ the data.
apply automated posting rules to modify transactions.
'--forecast'
apply periodic transaction rules to generate future transactions,
to 6 months from now or report end date.
generate future transactions from periodic transaction rules, for
the next 6 months or till report end date. In hledger-ui, also
make ordinary future transactions visible.
When a reporting option appears more than once in the command line,
the last one takes precedence.
@ -229,11 +225,10 @@ some 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
transactions, and hides future transactions (auto-generated or not) by
default. 'F' toggles showing and hiding these future transactions.
This is similar to using a query like 'date:-tomorrow', but more
convenient. (experimental)
As mentioned above, by default hledger-ui hides future transactions -
both ordinary transactions recorded in the journal, and periodic
transactions generated by rule. 'F' toggles forecast mode, in which
future/forecasted transactions are shown. (experimental)
'ESCAPE' removes all filters and jumps back to the top screen. Or,
it cancels a minibuffer edit or help dialog in progress.
@ -380,8 +375,8 @@ a check register. Each line represents one transaction and shows:
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 transactions
contributing to the balance shown on the accounts screen.
Tree mode/flat mode can be toggled with 'T' here also.
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
transactions. Similarly, 'P' toggles pending transactions, and 'C'
@ -504,26 +499,26 @@ program is restarted.

Tag Table:
Node: Top71
Node: OPTIONS1520
Ref: #options1617
Node: KEYS5053
Ref: #keys5148
Node: SCREENS9455
Ref: #screens9560
Node: Accounts screen9650
Ref: #accounts-screen9778
Node: Register screen11994
Ref: #register-screen12149
Node: Transaction screen14145
Ref: #transaction-screen14303
Node: Error screen15173
Ref: #error-screen15295
Node: ENVIRONMENT15539
Ref: #environment15653
Node: FILES16460
Ref: #files16559
Node: BUGS16772
Ref: #bugs16849
Node: OPTIONS1476
Ref: #options1573
Node: KEYS5004
Ref: #keys5099
Node: SCREENS9375
Ref: #screens9480
Node: Accounts screen9570
Ref: #accounts-screen9698
Node: Register screen11914
Ref: #register-screen12069
Node: Transaction screen14066
Ref: #transaction-screen14224
Node: Error screen15094
Ref: #error-screen15216
Node: ENVIRONMENT15460
Ref: #environment15574
Node: FILES16381
Ref: #files16480
Node: BUGS16693
Ref: #bugs16770

End Tag Table

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

@ -22,25 +22,22 @@ DESCRIPTION
line interface, and sometimes quicker and more convenient than the web
interface.
Note hledger-ui has some different defaults (experimental):
o it generates rule-based transactions and postings by default (--fore-
cast and --auto are always on).
o it hides transactions dated in the future by default (change this
with --future or the F key).
Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
or $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). For more about this see hledger(1),
hledger_journal(5) etc.
Unlike hledger, hledger-ui hides all future-dated transactions by de-
fault. They can be revealed, along with any rule-generated periodic
transactions, by pressing the F key (or starting with --forecast) to
enable "forecast mode".
OPTIONS
Note: if invoking hledger-ui as a hledger subcommand, write -- before
Note: if invoking hledger-ui as a hledger subcommand, write -- before
options as shown above.
Any QUERYARGS are interpreted as a hledger search query which filters
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
--watch
@ -53,7 +50,7 @@ OPTIONS
start in the (first) matched account's register screen
--change
show period balances (changes) at startup instead of historical
show period balances (changes) at startup instead of historical
balances
-F --flat
@ -62,9 +59,6 @@ OPTIONS
-T --tree
show accounts as a tree
--future
show transactions dated later than today (normally hidden)
hledger input options:
-f FILE --file=FILE
@ -72,7 +66,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE
Conversion rules file to use when reading CSV (default:
Conversion rules file to use when reading CSV (default:
FILE.rules)
--separator=CHAR
@ -114,7 +108,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
@ -137,22 +131,23 @@ 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-
tions, to 6 months from now or report end date.
generate future transactions from periodic transaction rules,
for the next 6 months or till report end date. In hledger-ui,
also make ordinary future transactions visible.
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -204,105 +199,104 @@ KEYS
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.
(experimental)
As mentioned above, by default hledger-ui hides future transactions -
both ordinary transactions recorded in the journal, and periodic trans-
actions generated by rule. F toggles forecast mode, in which fu-
ture/forecasted transactions are shown. (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.
@ -311,27 +305,27 @@ 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-
tions contributing to the balance shown on the accounts screen.
Tree mode/flat mode can be toggled with T here also.
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
transactions. Similarly, P toggles pending transactions, and C toggles

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

@ -176,8 +176,9 @@ most recent applicable market price, if any)
apply automated posting rules to modify transactions.
.TP
\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.
generate future transactions from periodic transaction rules, for the
next 6 months or till report end date.
In hledger-ui, also make ordinary future transactions visible.
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.

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

@ -187,8 +187,9 @@ before options, as shown in the synopsis above.
apply automated posting rules to modify transactions.
'--forecast'
apply periodic transaction rules to generate future transactions,
to 6 months from now or report end date.
generate future transactions from periodic transaction rules, for
the next 6 months or till report end date. In hledger-ui, also
make ordinary future transactions visible.
When a reporting option appears more than once in the command line,
the last one takes precedence.
@ -428,20 +429,20 @@ Tag Table:
Node: Top72
Node: OPTIONS1752
Ref: #options1857
Node: PERMISSIONS8130
Ref: #permissions8269
Node: EDITING UPLOADING DOWNLOADING9481
Ref: #editing-uploading-downloading9662
Node: RELOADING10496
Ref: #reloading10630
Node: JSON API11063
Ref: #json-api11177
Node: ENVIRONMENT12618
Ref: #environment12734
Node: FILES13467
Ref: #files13567
Node: BUGS13780
Ref: #bugs13858
Node: PERMISSIONS8201
Ref: #permissions8340
Node: EDITING UPLOADING DOWNLOADING9552
Ref: #editing-uploading-downloading9733
Node: RELOADING10567
Ref: #reloading10701
Node: JSON API11134
Ref: #json-api11248
Node: ENVIRONMENT12689
Ref: #environment12805
Node: FILES13538
Ref: #files13638
Node: BUGS13851
Ref: #bugs13929

End Tag Table

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

@ -166,8 +166,9 @@ OPTIONS
--auto apply automated posting rules to modify transactions.
--forecast
apply periodic transaction rules to generate future transac-
tions, to 6 months from now or report end date.
generate future transactions from periodic transaction rules,
for the next 6 months or till report end date. In hledger-ui,
also make ordinary future transactions visible.
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -186,54 +187,54 @@ 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.
Both of these options are ignored when --socket is used. In this case,
it creates an AF_UNIX socket file at the supplied path and uses that
for communication. This is an alternative way of running multiple
hledger-web instances behind a reverse proxy that handles authentica-
tion for different users. The path can be derived in a predictable
it creates an AF_UNIX socket file at the supplied path and uses that
for communication. This is an alternative way of running multiple
hledger-web instances behind a reverse proxy that handles authentica-
tion for different users. The path can be derived in a predictable
way, eg by using the username within the path. As an example, nginx as
reverse proxy can use the variabel $remote_user to derive a path from
the username used in a HTTP basic authentication. The following
proxy_pass directive allows access to all hledger-web instances that
reverse proxy can use the variabel $remote_user to derive a path from
the username used in a HTTP basic authentication. The following
proxy_pass directive allows access to all hledger-web instances that
created a socket in /tmp/hledger/:
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
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
@ -243,44 +244,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.
@ -288,8 +289,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
@ -299,17 +300,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
@ -324,21 +325,21 @@ 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).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI
more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing
@ -349,13 +350,13 @@ ENVIRONMENT
To see the effect you may need to killall Dock, or reboot.
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).
@ -369,7 +370,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)
@ -383,7 +384,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)

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

@ -291,14 +291,12 @@ Balance changes in 2008:
(Average is rounded to the dollar here since all journal amounts are)
Limitations:
A limitation of multicolumn balance reports: eliding of boring parent
accounts in tree mode, as in the classic balance report, is not yet
supported.
In multicolumn reports the -V/--value flag uses the market price on the
report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
The --transpose flag can be used to exchange the rows and columns of a
multicolumn report.
Budget report

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

@ -39,7 +39,8 @@ will not appear in the output. Similarly, when a transaction price is
implied but not written, it will not appear in the output. You can use
the -x/--explicit flag to make all amounts and transaction prices
explicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors.
journal more readable and robust against data entry errors. -x is also
implied by using any of -B,-V,-X,--value.
Note, -x/--explicit will cause postings with a multi-commodity amount
(these can arise when a multi-commodity transaction has an implicit

67
hledger/hledger.1
View File

@ -179,7 +179,7 @@ like this:
assets:bank:checking $1000 = $1000
assets:bank:savings $2000 = $2000
assets:cash $100 = $100
liabilities:creditcard $-50 = $-$50
liabilities:creditcard $-50 = $-50
equity:opening/closing balances
\f[R]
.fi
@ -628,8 +628,9 @@ most recent applicable market price, if any)
apply automated posting rules to modify transactions.
.TP
\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.
generate future transactions from periodic transaction rules, for the
next 6 months or till report end date.
In hledger-ui, also make ordinary future transactions visible.
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -1694,10 +1695,11 @@ more general \f[C]--value\f[R] option:
.IP
.nf
\f[C]
--value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
--value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at posting dates
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
@ -1710,6 +1712,11 @@ value\[dq] plus a valuation date:
\f[B]\f[CB]--value=cost\f[B]\f[R]
Convert amounts to cost, using the prices recorded in transactions.
.TP
\f[B]\f[CB]--value=then\f[B]\f[R]
Convert amounts to their value in a default valuation commodity, using
market prices on each posting\[aq]s date.
This is currently supported only by the print and register commands.
.TP
\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,
@ -1905,7 +1912,7 @@ Related: #329, #1083.
.PP
.TS
tab(@);
lw(14.4n) lw(13.8n) lw(14.6n) lw(15.2n) lw(12.0n).
lw(11.7n) lw(11.2n) lw(11.9n) lw(13.1n) lw(12.4n) lw(9.8n).
T{
Report type
T}@T{
@ -1913,6 +1920,8 @@ T}@T{
T}@T{
\f[C]-V\f[R], \f[C]-X\f[R]
T}@T{
\f[C]--value=then\f[R]
T}@T{
\f[C]--value=end\f[R]
T}@T{
\f[C]--value=DATE\f[R], \f[C]--value=now\f[R]
@ -1924,6 +1933,7 @@ T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
posting amounts
@ -1932,6 +1942,8 @@ cost
T}@T{
value at report end or today
T}@T{
value at posting date
T}@T{
value at report or journal end
T}@T{
value at DATE/today
@ -1946,12 +1958,15 @@ T}@T{
unchanged
T}@T{
unchanged
T}@T{
unchanged
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
\f[B]register\f[R]
@ -1959,6 +1974,7 @@ T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
starting balance (with -H)
@ -1967,6 +1983,8 @@ cost
T}@T{
value at day before report or journal start
T}@T{
not supported
T}@T{
value at day before report or journal start
T}@T{
value at DATE/today
@ -1978,6 +1996,8 @@ cost
T}@T{
value at report end or today
T}@T{
value at posting date
T}@T{
value at report or journal end
T}@T{
value at DATE/today
@ -1989,6 +2009,8 @@ summarised cost
T}@T{
value at period ends
T}@T{
sum of postings in interval, valued at interval start
T}@T{
value at period ends
T}@T{
value at DATE/today
@ -2003,12 +2025,15 @@ T}@T{
sum/average of displayed values
T}@T{
sum/average of displayed values
T}@T{
sum/average of displayed values
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
\f[B]balance (bs, bse, cf, is..)\f[R]
@ -2016,6 +2041,7 @@ T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
balances (no report interval)
@ -2024,6 +2050,8 @@ sums of costs
T}@T{
value at report end or today of sums of postings
T}@T{
not supported
T}@T{
value at report or journal end of sums of postings
T}@T{
value at DATE/today of sums of postings
@ -2035,6 +2063,8 @@ sums of costs
T}@T{
value at period ends of sums of postings
T}@T{
not supported
T}@T{
value at period ends of sums of postings
T}@T{
value at DATE/today of sums of postings
@ -2046,6 +2076,8 @@ sums of costs of postings before report start
T}@T{
sums of postings before report start
T}@T{
not supported
T}@T{
sums of postings before report start
T}@T{
sums of postings before report start
@ -2057,6 +2089,8 @@ like balances
T}@T{
like balances
T}@T{
not supported
T}@T{
like balances
T}@T{
like balances
@ -2068,6 +2102,8 @@ sum of displayed values
T}@T{
sum of displayed values
T}@T{
not supported
T}@T{
sum of displayed values
T}@T{
sum of displayed values
@ -2079,6 +2115,8 @@ sums/averages of displayed values
T}@T{
sums/averages of displayed values
T}@T{
not supported
T}@T{
sums/averages of displayed values
T}@T{
sums/averages of displayed values
@ -2090,6 +2128,8 @@ sums of displayed values
T}@T{
sums of displayed values
T}@T{
not supported
T}@T{
sums of displayed values
T}@T{
sums of displayed values
@ -2101,6 +2141,8 @@ sum/average of column totals
T}@T{
sum/average of column totals
T}@T{
not supported
T}@T{
sum/average of column totals
T}@T{
sum/average of column totals
@ -2110,6 +2152,7 @@ T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
.TE
.PP
@ -2668,14 +2711,12 @@ Balance changes in 2008:
\f[R]
.fi
.PP
Limitations:
A limitation of multicolumn balance reports: eliding of boring parent
accounts in tree mode, as in the classic balance report, is not yet
supported.
.PP
In multicolumn reports the \f[C]-V/--value\f[R] flag uses the market
price on the report end date, for all columns (not the price on each
column\[aq]s end date).
.PP
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
The \f[C]--transpose\f[R] flag can be used to exchange the rows and
columns of a multicolumn report.
.SS Budget report
.PP
With \f[C]--budget\f[R], extra columns are displayed showing budget
@ -3521,6 +3562,8 @@ You can use the \f[C]-x\f[R]/\f[C]--explicit\f[R] flag to make all
amounts and transaction prices explicit, which can be useful for
troubleshooting or for making your journal more readable and robust
against data entry errors.
\f[C]-x\f[R] is also implied by using any of
\f[C]-B\f[R],\f[C]-V\f[R],\f[C]-X\f[R],\f[C]--value\f[R].
.PP
Note, \f[C]-x\f[R]/\f[C]--explicit\f[R] will cause postings with a
multi-commodity amount (these can arise when a multi-commodity

493
hledger/hledger.info
View File

@ -186,7 +186,7 @@ balances on this date. Here are two ways to do it:
assets:bank:checking $1000 = $1000
assets:bank:savings $2000 = $2000
assets:cash $100 = $100
liabilities:creditcard $-50 = $-$50
liabilities:creditcard $-50 = $-50
equity:opening/closing balances
These are start-of-day balances, ie whatever was in the account at
@ -621,8 +621,9 @@ by most hledger commands, run 'hledger -h'.
apply automated posting rules to modify transactions.
'--forecast'
apply periodic transaction rules to generate future transactions,
to 6 months from now or report end date.
generate future transactions from periodic transaction rules, for
the next 6 months or till report end date. In hledger-ui, also
make ordinary future transactions visible.
When a reporting option appears more than once in the command line,
the last one takes precedence.
@ -1415,10 +1416,11 @@ _(experimental, added 201905)_
'-B', '-V' and '-X' are special cases of the more general '--value'
option:
--value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD.
--value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol.
Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at posting dates
- default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date
@ -1429,6 +1431,11 @@ a valuation date:
'--value=cost'
Convert amounts to cost, using the prices recorded in transactions.
'--value=then'
Convert amounts to their value in a default valuation commodity,
using market prices on each posting's date. This is currently
supported only by the print and register commands.
'--value=end'
Convert amounts to their value in a default valuation commodity,
@ -1582,67 +1589,76 @@ troubleshooting or reporting bugs. See also the definitions and notes
below. If you find problems, please report them, ideally with a
reproducible example. Related: #329, #1083.
Report type '-B', '-V', '-X' '--value=end' '--value=DATE',
'--value=cost' '--value=now'
-----------------------------------------------------------------------------
Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE',
type '--value=cost' '--value=now'
-------------------------------------------------------------------------------
*print*
posting cost value at value at value at
amounts report end or report or DATE/today
today journal end
balance unchanged unchanged unchanged unchanged
assertions /
posting cost value at value at value at value at
amounts report end posting date report or DATE/today
or today journal end
balance unchanged unchanged unchanged unchanged unchanged
assertions
/
assignments
*register*
starting cost value at day value at day value at
balance (with before report before report DATE/today
-H) or journal or journal
start start
posting cost value at value at value at
amounts (no report end or report or DATE/today
report today journal end
starting cost value at not value at value at
balance day before supported day before DATE/today
(with -H) report or report or
journal journal
start start
posting cost value at value at value at value at
amounts report end posting date report or DATE/today
(no report or today journal end
interval)
summary summarised value at value at value at
posting cost period ends period ends DATE/today
amounts (with
report
interval)
running sum/average sum/average sum/average of sum/average
total/average of displayed of displayed displayed of
values values values displayed
values
*balance (bs,
bse, cf,
is..)*
balances (no sums of value at value at value at
report costs report end or report or DATE/today
interval) today of sums journal end of of sums of
of postings sums of postings
postings
balances sums of value at value at value at
(with report costs period ends period ends of DATE/today
interval) of sums of sums of of sums of
postings postings postings
starting sums of sums of sums of sums of
balances costs of postings postings postings
(with report postings before report before report before
interval and before start start report
-H) report start start
budget like like balances like balances like
amounts with balances balances
summary summarised value at sum of value at value at
posting cost period postings in period ends DATE/today
amounts ends interval,
(with valued at
report interval
interval) start
running sum/average sum/average sum/average sum/average sum/average
total/averageof of of displayed of of
displayed displayed values displayed displayed
values values values values
*balance
(bs, bse,
cf, is..)*
balances sums of value at not value at value at
(no report costs report end supported report or DATE/today
interval) or today journal end of sums
of sums of of sums of of
postings postings postings
balances sums of value at not value at value at
(with costs period supported period ends DATE/today
report ends of of sums of of sums
interval) sums of postings of
postings postings
starting sums of sums of not sums of sums of
balances costs of postings supported postings postings
(with postings before before before
report before report report report
interval report start start start
and -H) start
budget like like not like like
amounts balances balances supported balances balances
with
-budget
grand total sum of sum of sum of sum of
(no report displayed displayed displayed displayed
interval) values values values values
row sums/averages sums/averages sums/averages sums/averages
totals/averages of displayed of displayed of displayed of
(with report values values values displayed
interval) values
column totals sums of sums of sums of sums of
displayed displayed displayed displayed
values values values values
grand sum/average sum/average sum/average of sum/average
total/average of column of column column totals of column
totals totals totals
grand sum of sum of not sum of sum of
total (no displayed displayed supported displayed displayed
report values values values values
interval)
row sums/averagessums/averagesnot sums/averages sums/averages
totals/averagesof of supported of of
(with displayed displayed displayed displayed
report values values values values
interval)
column sums of sums of not sums of sums of
totals displayed displayed supported displayed displayed
values values values values
grand sum/average sum/average not sum/average sum/average
total/averageof column of column supported of column of
totals totals totals column
totals
*Additional notes*
@ -2200,14 +2216,12 @@ Balance changes in 2008:
(Average is rounded to the dollar here since all journal amounts are)
Limitations:
A limitation of multicolumn balance reports: eliding of boring parent
accounts in tree mode, as in the classic balance report, is not yet
supported.
In multicolumn reports the '-V/--value' flag uses the market price on
the report end date, for all columns (not the price on each column's end
date).
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
The '--transpose' flag can be used to exchange the rows and columns
of a multicolumn report.

File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance
@ -2984,7 +2998,8 @@ will not appear in the output. Similarly, when a transaction price is
implied but not written, it will not appear in the output. You can use
the '-x'/'--explicit' flag to make all amounts and transaction prices
explicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors.
journal more readable and robust against data entry errors. '-x' is
also implied by using any of '-B','-V','-X','--value'.
Note, '-x'/'--explicit' will cause postings with a multi-commodity
amount (these can arise when a multi-commodity transaction has an
@ -3678,177 +3693,177 @@ Node: Starting a journal file4414
Ref: #starting-a-journal-file4612
Node: Setting opening balances5800
Ref: #setting-opening-balances5996
Node: Recording transactions9138
Ref: #recording-transactions9318
Node: Reconciling9874
Ref: #reconciling10017
Node: Reporting12274
Ref: #reporting12414
Node: Migrating to a new file16413
Ref: #migrating-to-a-new-file16561
Node: OPTIONS16860
Ref: #options16967
Node: General options17337
Ref: #general-options17462
Node: Command options20161
Ref: #command-options20312
Node: Command arguments20710
Ref: #command-arguments20857
Node: Queries21737
Ref: #queries21892
Node: Special characters in arguments and queries25854
Ref: #special-characters-in-arguments-and-queries26082
Node: More escaping26533
Ref: #more-escaping26695
Node: Even more escaping26991
Ref: #even-more-escaping27185
Node: Less escaping27856
Ref: #less-escaping28018
Node: Unicode characters28263
Ref: #unicode-characters28445
Node: Input files29857
Ref: #input-files30000
Node: Output destination31929
Ref: #output-destination32081
Node: Output format32364
Ref: #output-format32514
Node: Regular expressions32899
Ref: #regular-expressions33056
Node: Smart dates34417
Ref: #smart-dates34568
Node: Report start & end date35929
Ref: #report-start-end-date36101
Node: Report intervals37539
Ref: #report-intervals37704
Node: Period expressions38094
Ref: #period-expressions38254
Node: Depth limiting42380
Ref: #depth-limiting42524
Node: Pivoting42866
Ref: #pivoting42989
Node: Valuation44665
Ref: #valuation44767
Node: -B Cost44947
Ref: #b-cost45058
Node: -V Market value45256
Ref: #v-market-value45430
Node: -X Market value in specified commodity46862
Ref: #x-market-value-in-specified-commodity47101
Node: --value Flexible valuation47277
Ref: #value-flexible-valuation47503
Node: Effect of --value on reports51693
Ref: #effect-of---value-on-reports51909
Node: Combining -B -V -X --value56840
Ref: #combining--b--v--x---value57023
Node: COMMANDS57059
Ref: #commands57167
Node: accounts58251
Ref: #accounts58349
Node: activity59048
Ref: #activity59158
Node: add59541
Ref: #add59640
Node: balance62379
Ref: #balance62490
Node: Classic balance report63948
Ref: #classic-balance-report64121
Node: Customising the classic balance report65490
Ref: #customising-the-classic-balance-report65718
Node: Colour support67794
Ref: #colour-support67961
Node: Flat mode68134
Ref: #flat-mode68282
Node: Depth limited balance reports68695
Ref: #depth-limited-balance-reports68880
Node: Percentages69336
Ref: #percentages69502
Node: Multicolumn balance report70639
Ref: #multicolumn-balance-report70819
Node: Budget report76133
Ref: #budget-report76276
Node: Nested budgets81478
Ref: #nested-budgets81590
Ref: #output-format-185071
Node: balancesheet85149
Ref: #balancesheet85285
Node: balancesheetequity86668
Ref: #balancesheetequity86817
Node: cashflow87378
Ref: #cashflow87506
Node: check-dates88602
Ref: #check-dates88729
Node: check-dupes89008
Ref: #check-dupes89132
Node: close89425
Ref: #close89539
Node: close usage91061
Ref: #close-usage91154
Node: commodities93967
Ref: #commodities94094
Node: descriptions94176
Ref: #descriptions94304
Node: diff94485
Ref: #diff94591
Node: files95638
Ref: #files95738
Node: help95885
Ref: #help95985
Node: import97066
Ref: #import97180
Node: Importing balance assignments98073
Ref: #importing-balance-assignments98221
Node: incomestatement98870
Ref: #incomestatement99003
Node: notes100407
Ref: #notes100520
Node: payees100646
Ref: #payees100752
Node: prices100910
Ref: #prices101016
Node: print101357
Ref: #print101467
Node: print-unique106111
Ref: #print-unique106237
Node: register106522
Ref: #register106649
Node: Custom register output110821
Ref: #custom-register-output110950
Node: register-match112212
Ref: #register-match112346
Node: rewrite112697
Ref: #rewrite112812
Node: Re-write rules in a file114667
Ref: #re-write-rules-in-a-file114801
Node: Diff output format116011
Ref: #diff-output-format116180
Node: rewrite vs print --auto117272
Ref: #rewrite-vs.-print---auto117451
Node: roi118007
Ref: #roi118105
Node: stats119117
Ref: #stats119216
Node: tags120004
Ref: #tags120102
Node: test120396
Ref: #test120504
Node: Add-on Commands121251
Ref: #add-on-commands121368
Node: ui122711
Ref: #ui122799
Node: web122853
Ref: #web122956
Node: iadd123072
Ref: #iadd123183
Node: interest123265
Ref: #interest123372
Node: ENVIRONMENT123612
Ref: #environment123724
Node: FILES124553
Ref: #files-1124656
Node: LIMITATIONS124869
Ref: #limitations124988
Node: TROUBLESHOOTING125730
Ref: #troubleshooting125843
Node: Recording transactions9137
Ref: #recording-transactions9317
Node: Reconciling9873
Ref: #reconciling10016
Node: Reporting12273
Ref: #reporting12413
Node: Migrating to a new file16412
Ref: #migrating-to-a-new-file16560
Node: OPTIONS16859
Ref: #options16966
Node: General options17336
Ref: #general-options17461
Node: Command options20231
Ref: #command-options20382
Node: Command arguments20780
Ref: #command-arguments20927
Node: Queries21807
Ref: #queries21962
Node: Special characters in arguments and queries25924
Ref: #special-characters-in-arguments-and-queries26152
Node: More escaping26603
Ref: #more-escaping26765
Node: Even more escaping27061
Ref: #even-more-escaping27255
Node: Less escaping27926
Ref: #less-escaping28088
Node: Unicode characters28333
Ref: #unicode-characters28515
Node: Input files29927
Ref: #input-files30070
Node: Output destination31999
Ref: #output-destination32151
Node: Output format32434
Ref: #output-format32584
Node: Regular expressions32969
Ref: #regular-expressions33126
Node: Smart dates34487
Ref: #smart-dates34638
Node: Report start & end date35999
Ref: #report-start-end-date36171
Node: Report intervals37609
Ref: #report-intervals37774
Node: Period expressions38164
Ref: #period-expressions38324
Node: Depth limiting42450
Ref: #depth-limiting42594
Node: Pivoting42936
Ref: #pivoting43059
Node: Valuation44735
Ref: #valuation44837
Node: -B Cost45017
Ref: #b-cost45128
Node: -V Market value45326
Ref: #v-market-value45500
Node: -X Market value in specified commodity46932
Ref: #x-market-value-in-specified-commodity47171
Node: --value Flexible valuation47347
Ref: #value-flexible-valuation47573
Node: Effect of --value on reports52078
Ref: #effect-of---value-on-reports52294
Node: Combining -B -V -X --value57840
Ref: #combining--b--v--x---value58023
Node: COMMANDS58059
Ref: #commands58167
Node: accounts59251
Ref: #accounts59349
Node: activity60048
Ref: #activity60158
Node: add60541
Ref: #add60640
Node: balance63379
Ref: #balance63490
Node: Classic balance report64948
Ref: #classic-balance-report65121
Node: Customising the classic balance report66490
Ref: #customising-the-classic-balance-report66718
Node: Colour support68794
Ref: #colour-support68961
Node: Flat mode69134
Ref: #flat-mode69282
Node: Depth limited balance reports69695
Ref: #depth-limited-balance-reports69880
Node: Percentages70336
Ref: #percentages70502
Node: Multicolumn balance report71639
Ref: #multicolumn-balance-report71819
Node: Budget report77081
Ref: #budget-report77224
Node: Nested budgets82426
Ref: #nested-budgets82538
Ref: #output-format-186019
Node: balancesheet86097
Ref: #balancesheet86233
Node: balancesheetequity87616
Ref: #balancesheetequity87765
Node: cashflow88326
Ref: #cashflow88454
Node: check-dates89550
Ref: #check-dates89677
Node: check-dupes89956
Ref: #check-dupes90080
Node: close90373
Ref: #close90487
Node: close usage92009
Ref: #close-usage92102
Node: commodities94915
Ref: #commodities95042
Node: descriptions95124
Ref: #descriptions95252
Node: diff95433
Ref: #diff95539
Node: files96586
Ref: #files96686
Node: help96833
Ref: #help96933
Node: import98014
Ref: #import98128
Node: Importing balance assignments99021
Ref: #importing-balance-assignments99169
Node: incomestatement99818
Ref: #incomestatement99951
Node: notes101355
Ref: #notes101468
Node: payees101594
Ref: #payees101700
Node: prices101858
Ref: #prices101964
Node: print102305
Ref: #print102415
Node: print-unique107123
Ref: #print-unique107249
Node: register107534
Ref: #register107661
Node: Custom register output111833
Ref: #custom-register-output111962
Node: register-match113224
Ref: #register-match113358
Node: rewrite113709
Ref: #rewrite113824
Node: Re-write rules in a file115679
Ref: #re-write-rules-in-a-file115813
Node: Diff output format117023
Ref: #diff-output-format117192
Node: rewrite vs print --auto118284
Ref: #rewrite-vs.-print---auto118463
Node: roi119019
Ref: #roi119117
Node: stats120129
Ref: #stats120228
Node: tags121016
Ref: #tags121114
Node: test121408
Ref: #test121516
Node: Add-on Commands122263
Ref: #add-on-commands122380
Node: ui123723
Ref: #ui123811
Node: web123865
Ref: #web123968
Node: iadd124084
Ref: #iadd124195
Node: interest124277
Ref: #interest124384
Node: ENVIRONMENT124624
Ref: #environment124736
Node: FILES125565
Ref: #files-1125668
Node: LIMITATIONS125881
Ref: #limitations126000
Node: TROUBLESHOOTING126742
Ref: #troubleshooting126855

End Tag Table

713
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff