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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2022-09-01 16:00:48 -07:00
parent 9cb04480b5
commit 705280283c
13 changed files with 2444 additions and 2273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER-UI" "1" "August 2022" "hledger-ui-1.26.99 " "hledger User Manuals" .TH "HLEDGER-UI" "1" "September 2022" "hledger-ui-1.27 " "hledger User Manuals"
@ -7,7 +7,7 @@
.PP .PP
hledger-ui is a terminal interface (TUI) for the hledger accounting hledger-ui is a terminal interface (TUI) for the hledger accounting
tool. tool.
This manual is for hledger-ui 1.26.99. This manual is for hledger-ui 1.27.
.SH SYNOPSIS .SH SYNOPSIS
.PP .PP
\f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R] \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]

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

@ -12,7 +12,7 @@ hledger-ui(1)
************* *************
hledger-ui is a terminal interface (TUI) for the hledger accounting hledger-ui is a terminal interface (TUI) for the hledger accounting
tool. This manual is for hledger-ui 1.26.99. tool. This manual is for hledger-ui 1.27.
'hledger-ui [OPTIONS] [QUERYARGS]' 'hledger-ui [OPTIONS] [QUERYARGS]'
'hledger ui -- [OPTIONS] [QUERYARGS]' 'hledger ui -- [OPTIONS] [QUERYARGS]'
@ -640,34 +640,34 @@ program is restarted.
 
Tag Table: Tag Table:
Node: Top221 Node: Top221
Node: OPTIONS1657 Node: OPTIONS1654
Ref: #options1755 Ref: #options1752
Node: MOUSE6637 Node: MOUSE6634
Ref: #mouse6732 Ref: #mouse6729
Node: KEYS7014 Node: KEYS7011
Ref: #keys7107 Ref: #keys7104
Node: SCREENS11193 Node: SCREENS11190
Ref: #screens11291 Ref: #screens11288
Node: Accounts screen11381 Node: Accounts screen11378
Ref: #accounts-screen11509 Ref: #accounts-screen11506
Node: Register screen13848 Node: Register screen13845
Ref: #register-screen14003 Ref: #register-screen14000
Node: Transaction screen15987 Node: Transaction screen15984
Ref: #transaction-screen16145 Ref: #transaction-screen16142
Node: Error screen17015 Node: Error screen17012
Ref: #error-screen17137 Ref: #error-screen17134
Node: TIPS17381 Node: TIPS17378
Ref: #tips17480 Ref: #tips17477
Node: Watch mode17532 Node: Watch mode17529
Ref: #watch-mode17649 Ref: #watch-mode17646
Node: Watch mode limitations18399 Node: Watch mode limitations18396
Ref: #watch-mode-limitations18540 Ref: #watch-mode-limitations18537
Node: ENVIRONMENT19676 Node: ENVIRONMENT19673
Ref: #environment19787 Ref: #environment19784
Node: FILES21172 Node: FILES21169
Ref: #files21271 Ref: #files21268
Node: BUGS21484 Node: BUGS21481
Ref: #bugs21561 Ref: #bugs21558
 
End Tag Table End Tag Table

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

@ -5,7 +5,7 @@ HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1)
NAME NAME
hledger-ui is a terminal interface (TUI) for the hledger accounting hledger-ui is a terminal interface (TUI) for the hledger accounting
tool. This manual is for hledger-ui 1.26.99. tool. This manual is for hledger-ui 1.27.
SYNOPSIS SYNOPSIS
hledger-ui [OPTIONS] [QUERYARGS] hledger-ui [OPTIONS] [QUERYARGS]
@ -549,4 +549,4 @@ SEE ALSO
hledger-ui-1.26.99 August 2022 HLEDGER-UI(1) hledger-ui-1.27 September 2022 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

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

@ -1,12 +1,12 @@
.TH "HLEDGER-WEB" "1" "August 2022" "hledger-web-1.26.99 " "hledger User Manuals" .TH "HLEDGER-WEB" "1" "September 2022" "hledger-web-1.27 " "hledger User Manuals"
.SH NAME .SH NAME
.PP .PP
hledger-web is a web interface (WUI) for the hledger accounting tool. hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.26.99. This manual is for hledger-web 1.27.
.SH SYNOPSIS .SH SYNOPSIS
.PP .PP
\f[C]hledger-web [OPTIONS]\f[R] \f[C]hledger-web [OPTIONS]\f[R]

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

@ -12,7 +12,7 @@ hledger-web(1)
************** **************
hledger-web is a web interface (WUI) for the hledger accounting tool. hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.26.99. This manual is for hledger-web 1.27.
'hledger-web [OPTIONS]' 'hledger-web [OPTIONS]'
'hledger web -- [OPTIONS]' 'hledger web -- [OPTIONS]'
@ -632,22 +632,22 @@ awkward.
 
Tag Table: Tag Table:
Node: Top223 Node: Top223
Node: OPTIONS1889 Node: OPTIONS1886
Ref: #options1994 Ref: #options1991
Node: PERMISSIONS9905 Node: PERMISSIONS9902
Ref: #permissions10044 Ref: #permissions10041
Node: EDITING UPLOADING DOWNLOADING11256 Node: EDITING UPLOADING DOWNLOADING11253
Ref: #editing-uploading-downloading11437 Ref: #editing-uploading-downloading11434
Node: RELOADING12271 Node: RELOADING12268
Ref: #reloading12405 Ref: #reloading12402
Node: JSON API12838 Node: JSON API12835
Ref: #json-api12952 Ref: #json-api12949
Node: ENVIRONMENT18442 Node: ENVIRONMENT18439
Ref: #environment18558 Ref: #environment18555
Node: FILES19869 Node: FILES19866
Ref: #files19969 Ref: #files19966
Node: BUGS20182 Node: BUGS20179
Ref: #bugs20260 Ref: #bugs20257
 
End Tag Table End Tag Table

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

@ -5,7 +5,7 @@ HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1)
NAME NAME
hledger-web is a web interface (WUI) for the hledger accounting tool. hledger-web is a web interface (WUI) for the hledger accounting tool.
This manual is for hledger-web 1.26.99. This manual is for hledger-web 1.27.
SYNOPSIS SYNOPSIS
hledger-web [OPTIONS] hledger-web [OPTIONS]
@ -586,4 +586,4 @@ SEE ALSO
hledger-web-1.26.99 August 2022 HLEDGER-WEB(1) hledger-web-1.27 September 2022 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

538
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "HLEDGER" "1" "August 2022" "hledger-1.26.99 " "hledger User Manuals" .TH "HLEDGER" "1" "September 2022" "hledger-1.27 " "hledger User Manuals"
@ -9,7 +9,7 @@
This is the command-line interface (CLI) for the hledger accounting This is the command-line interface (CLI) for the hledger accounting
tool. tool.
Here we also describe hledger\[aq]s concepts and file formats. Here we also describe hledger\[aq]s concepts and file formats.
This manual is for hledger 1.26.99. This manual is for hledger 1.27.
.SH SYNOPSIS .SH SYNOPSIS
.PP .PP
\f[C]hledger\f[R] \f[C]hledger\f[R]
@ -1564,38 +1564,257 @@ not the old one, and \f[C]amt:\f[R] matches the new quantity, and not
the old one. the old one.
Note: this changed in hledger 1.22, previously it was the reverse, see Note: this changed in hledger 1.22, previously it was the reverse, see
the discussion at #1625. the discussion at #1625.
.SH CONVERSION & COST .SH COST
.PP .PP
This section is about converting between commodities. This section is about recording the cost of things, in transactions
Some definitions: where one commodity is exchanged for another.
Eg an exchange of currency, or a stock purchase or sale.
First, a quick glossary:
.IP \[bu] 2 .IP \[bu] 2
A \[dq]commodity conversion\[dq] is an exchange of one currency or Conversion - an exchange of one currency or commodity for another.
commodity for another.
Eg a foreign currency exchange, or a purchase or sale of stock or Eg a foreign currency exchange, or a purchase or sale of stock or
cryptocurrency. cryptocurrency.
.IP \[bu] 2 .IP \[bu] 2
A \[dq]conversion transaction\[dq] is a transaction involving one or Conversion transaction - a transaction involving one or more
more such conversions. conversions.
.IP \[bu] 2 .IP \[bu] 2
\[dq]Conversion rate\[dq] is the exchange rate in a conversion - the Conversion rate - the cost per unit of one commodity in the other, ie
cost per unit of one commodity in the other. the exchange rate.
.IP \[bu] 2 .IP \[bu] 2
\[dq]Cost\[dq] is how much of one commodity was paid to acquire the Cost - how much of one commodity was paid to acquire the other.
other (when buying), or how much was received in exchange for the other And more generally, in hledger docs: the amount exchanged in the
(when selling). \[dq]secondary\[dq] commodity (usually your base currency), whether in a
We call both of these \[dq]cost\[dq] for convenience (after all, it is purchase or a sale, and whether expressed per unit or in total.
cost for one party or the other). Or, the \[at]/\[at]\[at] notation used to represent this.
.SS Recording conversions .IP \[bu] 2
Transaction price - another name for the cost expressed with
hledger\[aq]s cost notation.
.SS -B: Convert to cost
.PP .PP
As a concrete example, let\[aq]s assume 100 EUR was converted to 120 As discussed a little further on in Transaction prices, when recording a
USD. transaction you can also record the amount\[aq]s cost in another
There are several ways to record this in the journal, each with pros and commodity, by adding \f[C]\[at] UNITPRICE\f[R] or
cons which will be explained in more detail below. \f[C]\[at]\[at] TOTALPRICE\f[R].
(Also, these examples use journal format which is properly explained
much further below; sorry about that, you may want to read some of that
first.)
.SS Implicit conversion
.PP .PP
Then you can see a report with amounts converted to cost, by adding the
\f[C]-B/--cost\f[R] flag.
(Mnemonic: \[dq]B\[dq] from \[dq]cost Basis\[dq], as in Ledger).
Eg:
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135 ; 135 dollars is exchanged for..
assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal -N
$-135 assets:dollars
\[Eu]100 assets:euros
$ hledger bal -N -B
$-135 assets:dollars
$135 assets:euros # <- the euros\[aq] cost
\f[R]
.fi
.PP
Notes:
.PP
-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\[aq]s postings are reversed, while the transaction is
equivalent, -B shows something different:
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135 ; 135 dollars sold
assets:euros \[Eu]100 ; for 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal -N -B
\[Eu]-100 assets:dollars # <- the dollars\[aq] selling price
\[Eu]100 assets:euros
\f[R]
.fi
.PP
The \[at]/\[at]\[at] cost notation is convenient, but has some
drawbacks: it does not truly balance the transaction, so it disrupts the
accounting equation and tends to causes a non-zero total in balance
reports.
.SS Equity conversion postings
.PP
By contrast, conventional double entry bookkeeping (DEB) uses a
different notation: an extra pair of equity postings to balance
conversion transactions.
In this style, the above entry might be written:
.IP
.nf
\f[C]
2022-01-01 one hundred euros purchased at $1.35 each
assets:dollars $-135
equity:conversion $135
equity:conversion \[Eu]-100
assets:euros \[Eu]100
\f[R]
.fi
.PP
This style is more correct, but it\[aq]s also more verbose and makes
cost reporting more difficult for PTA tools.
.PP
Happily, current hledger can read either notation, or convert one to the
other when needed, so you can use the one you prefer.
.SS Inferring equity postings from cost
.PP
With \f[C]--infer-equity\f[R], hledger detects transactions written with
PTA cost notation and adds equity conversion postings to them (and
temporarily permits the coexistence of equity conversion postings and
cost notation, which normally would cause an unbalanced transaction
error).
Eg:
.IP
.nf
\f[C]
2022-01-01
assets:dollars -$135
assets:euros \[Eu]100 \[at] $1.35
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print --infer-equity
2022-01-01
assets:dollars $-135
assets:euros \[Eu]100 \[at] $1.35
equity:conversion:$-\[Eu]:\[Eu] \[Eu]-100 ; generated-posting:
equity:conversion:$-\[Eu]:$ $135.00 ; generated-posting:
\f[R]
.fi
.PP
The conversion account names can be changed with the conversion account
type declaration.
.PP
--infer-equity is useful when when transactions have been recorded using
PTA cost notation, to help preserve the accounting equation and balance
reports\[aq] zero total, or to produce more conventional journal entries
for sharing with non-PTA-users.
.PP
\f[I]Experimental\f[R]
.SS Inferring cost from equity postings
.PP
The reverse operation is possible using \f[C]--infer-costs\f[R], which
detects transactions written with equity conversion postings and adds
PTA cost notation to them (and temporarily permits the coexistence of
equity conversion postings and cost notation).
Eg:
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135
equity:conversion $135
equity:conversion \[Eu]-100
assets:euros \[Eu]100
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print --infer-costs
2022-01-01
assets:dollars $-135 \[at]\[at] \[Eu]100
equity:conversion $135
equity:conversion \[Eu]-100
assets:euros \[Eu]100
\f[R]
.fi
.PP
--infer-costs is useful when combined with -B/--cost, allowing cost
reporting even when transactions have been recorded using equity
postings:
.IP
.nf
\f[C]
$ hledger print --infer-costs -B
2009-01-01
assets:dollars \[Eu]-100
assets:euros \[Eu]100
\f[R]
.fi
.PP
Notes:
.PP
Postings will be recognised as equity conversion postings if they are 1.
to account(s) declared with type \f[C]V\f[R] (\f[C]Conversion\f[R]; or
if no such accounts are declared, accounts named
\f[C]equity:conversion\f[R], \f[C]equity:trade\f[R],
\f[C]equity:trading\f[R], or subaccounts of these) 2.
adjacent 3.
and exactly matching the amounts of two non-conversion postings.
.PP
The total cost is appended to the first matching posting in the
transaction.
If you need to assign it to a different posting, or if you have several
different sets of conversion postings in one transaction, you may need
to write the costs explicitly yourself.
Eg:
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135
equity:conversion \[Eu]-100
equity:conversion $135
assets:euros \[Eu]100 \[at]\[at] $135
\f[R]
.fi
.PP
or:
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-235
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought for $1.35 each
equity:conversion \[Eu]-100
equity:conversion $135
assets:pounds \[Po]80 \[at]\[at] $100 ; 80 pounds bought for $100 total
equity:conversion \[Po]-80
equity:conversion $100
\f[R]
.fi
.PP
--infer-equity and --infer-costs can be used together, eg if you have a
mixture of both notations.
.PP
\f[I]Experimental\f[R]
.SS When to infer cost/equity
.PP
Inferring equity postings or costs is still fairly new, so not enabled
by default.
We\[aq]re not sure yet if that should change.
Here are two suggestions to try, experience reports welcome:
.IP "1." 3
When you use -B, always use --infer-costs as well.
Eg: \f[C]hledger bal -B --infer-costs\f[R]
.IP "2." 3
Always run hledger with both flags enabled.
Eg: \f[C]alias hl=\[dq]hledger --infer-equity --infer-costs\[dq]\f[R]
.SS How to record conversions
.PP
Essentially there are four ways to record a conversion transaction in
hledger.
Here are all of them, with pros and cons.
.SS Conversion with implicit cost
.PP
Let\[aq]s assume 100 EUR is converted to 120 USD.
You can just record the outflow (100 EUR) and inflow (120 USD) in the You can just record the outflow (100 EUR) and inflow (120 USD) in the
appropriate asset account: appropriate asset account:
.IP .IP
@ -1613,25 +1832,24 @@ You can see the inferred rate by using \f[C]hledger print -x\f[R].
.PP .PP
Pro: Pro:
.IP \[bu] 2 .IP \[bu] 2
Easy, concise Concise, easy
.IP \[bu] 2
hledger can do cost reporting
.PP .PP
Con: Con:
.IP \[bu] 2 .IP \[bu] 2
Less error checking - typos in amounts or commodity symbols may not be Less error checking - typos in amounts or commodity symbols may not be
detected detected
.IP \[bu] 2 .IP \[bu] 2
conversion rate is not clear Conversion rate is not clear
.IP \[bu] 2 .IP \[bu] 2
disturbs the accounting equation Disturbs the accounting equation, unless you add the --infer-equity flag
.PP .PP
You can prevent accidental implicit conversions due to a mistyped You can prevent accidental implicit conversions due to a mistyped
commodity symbol, by using \f[C]hledger check commodities\f[R]. commodity symbol, by using \f[C]hledger check commodities\f[R].
.PP
You can prevent implicit conversions entirely, by using You can prevent implicit conversions entirely, by using
\f[C]hledger check balancednoautoconversion\f[R], or \f[C]hledger check balancednoautoconversion\f[R], or
\f[C]-s/--strict\f[R]. \f[C]-s/--strict\f[R].
.SS Priced conversion .SS Conversion with explicit cost
.PP .PP
You can add the conversion rate using \[at] notation: You can add the conversion rate using \[at] notation:
.IP .IP
@ -1650,16 +1868,14 @@ Pro:
.IP \[bu] 2 .IP \[bu] 2
Still concise Still concise
.IP \[bu] 2 .IP \[bu] 2
makes the conversion rate clear Makes the conversion rate clear
.IP \[bu] 2 .IP \[bu] 2
provides some error checking Provides more error checking
.IP \[bu] 2
hledger can do cost reporting
.PP .PP
Con: Con:
.IP \[bu] 2 .IP \[bu] 2
Disturbs the accounting equation without the --infer-equity flag Disturbs the accounting equation, unless you add the --infer-equity flag
.SS Equity conversion .SS Conversion with equity postings
.PP .PP
In strict double entry bookkeeping, the above transaction is not In strict double entry bookkeeping, the above transaction is not
balanced in EUR or in USD, since some EUR disappears, and some USD balanced in EUR or in USD, since some EUR disappears, and some USD
@ -1684,24 +1900,22 @@ Pro:
.IP \[bu] 2 .IP \[bu] 2
Preserves the accounting equation Preserves the accounting equation
.IP \[bu] 2 .IP \[bu] 2
keeps track of conversions and related gains/losses in one place Keeps track of conversions and related gains/losses in one place
.IP \[bu] 2 .IP \[bu] 2
works in any double entry accounting system Standard, works in any double entry accounting system
.IP \[bu] 2
hledger can convert this to transaction prices using the --infer-costs
flag
.PP .PP
Con: Con:
.IP \[bu] 2 .IP \[bu] 2
More verbose More verbose
.IP \[bu] 2 .IP \[bu] 2
conversion rate is not clear Conversion rate is not obvious
.IP \[bu] 2 .IP \[bu] 2
depends on the order of postings Cost reporting requires adding the --infer-costs flag
.SS Priced equity conversion .SS Conversion with equity postings and explicit cost
.PP .PP
Another notation is to record both the conversion rate and the equity Here both equity postings and \[at] notation are used together.
postings: hledger will usually complain about this redundancy, but when using the
--infer-costs flag it is accepted.
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1717,68 +1931,39 @@ Pro:
.IP \[bu] 2 .IP \[bu] 2
Preserves the accounting equation Preserves the accounting equation
.IP \[bu] 2 .IP \[bu] 2
keeps track of conversions and related gains/losses in one place Keeps track of conversions and related gains/losses in one place
.IP \[bu] 2 .IP \[bu] 2
makes the conversion rate clear Makes the conversion rate clear
.IP \[bu] 2 .IP \[bu] 2
provides some error checking Provides more error checking
.IP \[bu] 2
hledger can do cost reporting
.PP .PP
Con: Con:
.IP \[bu] 2 .IP \[bu] 2
Most verbose Most verbose
.IP \[bu] 2 .IP \[bu] 2
Requires --infer-costs flag Requires the --infer-costs flag
.IP \[bu] 2 .IP \[bu] 2
Not compatible with ledger Not compatible with ledger
.SS Inferring missing conversion rates .SS Cost tips
.PP
hledger will do this automatically for implicit conversions.
Currently it can not do this for equity conversions.
.SS Inferring missing equity postings
.PP
With the \f[C]--infer-equity\f[R] flag, hledger will add equity postings
to priced and implicit conversions.
.SS Inferring missing transaction prices from equity postings
.PP
With the \f[C]--infer-costs\f[R] flag, hledger will add transaction
prices from equity postings, and will be able to handle transaction
prices and equity postings together.
.SS Cost reporting
.PP
With the \f[C]-B/--cost\f[R] flag, hledger will convert the amounts in
priced and implicit conversions to their cost in the other commodity.
This is useful to see a report of what you paid for things (or how much
you sold things for).
Currently \f[C]-B/--cost\f[R] does not work on equity conversions, and
it disables \f[C]--infer-equity\f[R].
.PP
These operations are transient, only affecting reports.
If you want to change the journal file permanently, you could pipe each
entry through
\f[C]hledger -f- -I print [-x] [--infer-equity] [--infer-costs] [-B]\f[R]
.SS Conversion summary
.IP \[bu] 2 .IP \[bu] 2
Recording the conversion rate is good because it makes that clear and Recording the conversion rate explicitly is good because it makes that
allows cost reporting. clear and helps detect errors.
.IP \[bu] 2 .IP \[bu] 2
Recording equity postings is good because it balances the accounting Recording equity postings is good because it is correct bookkeeping and
equation and is correct bookkeeping. preserves the accounting equation.
.IP \[bu] 2 .IP \[bu] 2
Combining these is possible with the --infer-costs flag, but has certain Combining these is possible by using the --infer-costs flag (which
requirements for the order of postings. requires well-ordered postings).
.IP \[bu] 2 .IP \[bu] 2
When you want to see the cost (or sale proceeds) of things, use When you want to see the cost (or sale proceeds) of things, use
\f[C]-B/--cost\f[R]. \f[C]-B\f[R] (or \f[C]--cost\f[R]).
If you use equity conversion postings notation, use
\f[C]-B --infer-costs\f[R].
.IP \[bu] 2 .IP \[bu] 2
When you want to see a balanced balance sheet or correct journal If you use PTA cost notation, and you want to see a balanced balance
entries, use \f[C]--infer-equity\f[R]. sheet or print correct journal entries, use \f[C]--infer-equity\f[R].
.IP \[bu] 2 .IP \[bu] 2
\f[C]--cost\f[R] will remove any balancing equity posts, so as not to Conversion to cost is performed before valuation (described next).
disturb the accounting equation.
.IP \[bu] 2
Conversion/cost operations are performed before valuation.
.SH VALUATION .SH VALUATION
.PP .PP
Instead of reporting amounts in their original commodity, hledger can Instead of reporting amounts in their original commodity, hledger can
@ -6988,18 +7173,30 @@ number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]).
hledger was built with Decimal < 0.5.1.) hledger was built with Decimal < 0.5.1.)
.SS Transaction prices .SS Transaction prices
.PP .PP
Within a transaction, you can note an amount\[aq]s price in another (AKA Costs)
commodity.
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
certain date.
.PP .PP
There are several ways to record a transaction price: After a posting amount, you can note its cost or selling price in
another commodity, by writing either \f[C]\[at] UNITPRICE\f[R] or
\f[C]\[at]\[at] TOTALPRICE\f[R] after it.
This indicates a conversion transaction, where one commodity is
exchanged for another.
.PP
hledger docs have historically called this a \[dq]transaction price\[dq]
because it is specific to one transaction, unlike market prices which
are not.
\[dq]Cost\[dq] is shorter and might be preferable; just remember this
feature can represent either a buyer\[aq]s cost, or a seller\[aq]s
price.
.PP
Costs are usually written explicitly with \f[C]\[at]\f[R] or
\f[C]\[at]\[at]\f[R], but can also be inferred automatically for simple
multi-commodity transactions.
.PD 0
.P
.PD
As an example, here are several ways to record purchases of a foreign
currency in hledger, using the cost notation either explicitly or
implicitly:
.IP "1." 3 .IP "1." 3
Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount: Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount:
.RS 4 .RS 4
@ -7046,131 +7243,8 @@ Like 1, but the \f[C]\[at]\f[R] is parenthesised, i.e.
Like 2, but as in 4 the \f[C]\[at]\[at]\f[R] is parenthesised, i.e. Like 2, but as in 4 the \f[C]\[at]\[at]\f[R] is parenthesised, i.e.
\f[C](\[at]\[at])\f[R]; in hledger, this is equivalent to 2. \f[C](\[at]\[at])\f[R]; in hledger, this is equivalent to 2.
.PP .PP
Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction Amounts can be converted to cost at report time using the
price\[aq]s commodity, if any. \f[C]-B/--cost\f[R] flag; this is discussed more in the COST section.
(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], as in Ledger).
Eg here is how -B affects the balance report for the example above:
.IP
.nf
\f[C]
$ hledger bal -N --flat
$-135 assets:dollars
\[Eu]100 assets:euros
$ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros\[aq] cost
\f[R]
.fi
.PP
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\[aq]s postings are reversed, while the transaction is
equivalent, -B shows something different:
.IP
.nf
\f[C]
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros \[Eu]100 ; for 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal -N --flat -B
\[Eu]-100 assets:dollars # <- the dollars\[aq] selling price
\[Eu]100 assets:euros
\f[R]
.fi
.SS Equity conversion postings
.PP
Transaction prices can be converted to and from equity conversion
postings using the \f[C]--infer-equity\f[R] and \f[C]--infer-costs\f[R]
flags.
.PP
With \f[C]--infer-equity\f[R], hledger will add equity postings to
balance out any transaction prices.
.IP
.nf
\f[C]
2009/1/1
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought
assets:dollars -$135 ; for $135
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print --infer-equity
2009-01-01
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought
equity:conversion:$-\[Eu]:\[Eu] \[Eu]-100 ; 100 euros bought, generated-posting:
equity:conversion:$-\[Eu]:$ $135.00 ; 100 euros bought, generated-posting:
assets:dollars $-135 ; for $135
\f[R]
.fi
.PP
The reverse is possible using \f[C]--infer-costs\f[R], which will check
any equity conversion postings and generate a transaction price for the
\f[I]first\f[R] non-conversion posting which matches.
.IP
.nf
\f[C]
2009-01-01
assets:euros \[Eu]100 ; 100 euros bought
equity:conversion \[Eu]-100
equity:conversion $135
assets:dollars $-135 ; for $135
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger print --infer-costs
2009-01-01
assets:euros \[Eu]100 \[at]\[at] $135 ; 100 euros bought
equity:conversion \[Eu]-100
equity:conversion $135
assets:dollars $-135 ; for $135
\f[R]
.fi
.PP
Note that the above will assign the transaction price to the first
matching posting in the transaction.
If you want to assign it to a different posting, or if you have several
different sets of conversion postings which must match different
postings, you must manually specify the transaction price.
If you do this, equity conversion postings must occur in adjacent pairs
and must exactly match the amount of a non-conversion posting.
.IP
.nf
\f[C]
2009-01-01
assets:dollars $-135 ; $135 paid
equity:conversion \[Eu]-100
equity:conversion $135
assets:euros \[Eu]100 \[at]\[at] $135 ; to buy 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
2009-01-01
assets:euros \[Eu]100 \[at] $1.35 ; 100 euros bought
equity:conversion \[Eu]-100
equity:conversion $135
assets:pounds \[Po]80 \[at]\[at] $100 ; 80 pounds bought
equity:conversion \[Po]-80
equity:conversion $100
assets:dollars $-235 ; for $235 total
\f[R]
.fi
.PP
The account names used for the conversion accounts can be changed with
the conversion account type declaration.
.SS Lot prices, lot dates .SS Lot prices, lot dates
.PP .PP
Ledger allows another kind of price, lot price (four variants: Ledger allows another kind of price, lot price (four variants:
@ -8113,7 +8187,7 @@ or, it can be (these are used less often):
assets for the cashflow report) assets for the cashflow report)
.IP \[bu] 2 .IP \[bu] 2
\f[C]V\f[R] or \f[C]Conversion\f[R] (a subtype of Equity, for \f[C]V\f[R] or \f[C]Conversion\f[R] (a subtype of Equity, for
conversions (see CONVERSION & COST).) conversions (see COST).)
.PP .PP
Here is a typical set of account type declarations: Here is a typical set of account type declarations:
.IP .IP
@ -10933,7 +11007,7 @@ Show only asset and liability balances, as a flat list, limited to depth
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger bal assets liabilities --flat -2 $ hledger bal assets liabilities -2
$4000 assets:bank $4000 assets:bank
$105 assets:cash $105 assets:cash
$-50 liabilities:creditcard $-50 liabilities:creditcard
@ -10947,7 +11021,7 @@ balance sheet:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger bs --flat -2 $ hledger bs -2
Balance Sheet 2020-01-16 Balance Sheet 2020-01-16
|| 2020-01-16 || 2020-01-16

1640
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

451
hledger/hledger.txt
View File

@ -6,7 +6,7 @@ HLEDGER(1) hledger User Manuals HLEDGER(1)
NAME NAME
This is the command-line interface (CLI) for the hledger accounting This is the command-line interface (CLI) for the hledger accounting
tool. Here we also describe hledger's concepts and file formats. This tool. Here we also describe hledger's concepts and file formats. This
manual is for hledger 1.26.99. manual is for hledger 1.27.
SYNOPSIS SYNOPSIS
hledger hledger
@ -1054,35 +1054,194 @@ QUERIES
this changed in hledger 1.22, previously it was the reverse, see the this changed in hledger 1.22, previously it was the reverse, see the
discussion at #1625. discussion at #1625.
CONVERSION & COST COST
This section is about converting between commodities. Some defini- This section is about recording the cost of things, in transactions
tions: where one commodity is exchanged for another. Eg an exchange of cur-
rency, or a stock purchase or sale. First, a quick glossary:
o A "commodity conversion" is an exchange of one currency or commodity o Conversion - an exchange of one currency or commodity for another.
for another. Eg a foreign currency exchange, or a purchase or sale Eg a foreign currency exchange, or a purchase or sale of stock or
of stock or cryptocurrency. cryptocurrency.
o A "conversion transaction" is a transaction involving one or more o Conversion transaction - a transaction involving one or more conver-
such conversions. sions.
o "Conversion rate" is the exchange rate in a conversion - the cost per o Conversion rate - the cost per unit of one commodity in the other, ie
unit of one commodity in the other. the exchange rate.
o "Cost" is how much of one commodity was paid to acquire the other o Cost - how much of one commodity was paid to acquire the other. And
(when buying), or how much was received in exchange for the other more generally, in hledger docs: the amount exchanged in the "sec-
(when selling). We call both of these "cost" for convenience (after ondary" commodity (usually your base currency), whether in a purchase
all, it is cost for one party or the other). or a sale, and whether expressed per unit or in total. Or, the @/@@
notation used to represent this.
Recording conversions o Transaction price - another name for the cost expressed with
As a concrete example, let's assume 100 EUR was converted to 120 USD. hledger's cost notation.
There are several ways to record this in the journal, each with pros
and cons which will be explained in more detail below. (Also, these
examples use journal format which is properly explained much further
below; sorry about that, you may want to read some of that first.)
Implicit conversion -B: Convert to cost
You can just record the outflow (100 EUR) and inflow (120 USD) in the As discussed a little further on in Transaction prices, when recording
appropriate asset account: a transaction you can also record the amount's cost in another commod-
ity, by adding @ UNITPRICE or @@ TOTALPRICE.
Then you can see a report with amounts converted to cost, by adding the
-B/--cost flag. (Mnemonic: "B" from "cost Basis", as in Ledger). Eg:
2022-01-01
assets:dollars $-135 ; 135 dollars is exchanged for..
assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
$ hledger bal -N
$-135 assets:dollars
EUR100 assets:euros
$ hledger bal -N -B
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
Notes:
-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:
2022-01-01
assets:dollars $-135 ; 135 dollars sold
assets:euros EUR100 ; for 100 euros
$ hledger bal -N -B
EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros
The @/@@ cost notation is convenient, but has some drawbacks: it does
not truly balance the transaction, so it disrupts the accounting equa-
tion and tends to causes a non-zero total in balance reports.
Equity conversion postings
By contrast, conventional double entry bookkeeping (DEB) uses a differ-
ent notation: an extra pair of equity postings to balance conversion
transactions. In this style, the above entry might be written:
2022-01-01 one hundred euros purchased at $1.35 each
assets:dollars $-135
equity:conversion $135
equity:conversion EUR-100
assets:euros EUR100
This style is more correct, but it's also more verbose and makes cost
reporting more difficult for PTA tools.
Happily, current hledger can read either notation, or convert one to
the other when needed, so you can use the one you prefer.
Inferring equity postings from cost
With --infer-equity, hledger detects transactions written with PTA cost
notation and adds equity conversion postings to them (and temporarily
permits the coexistence of equity conversion postings and cost nota-
tion, which normally would cause an unbalanced transaction error). Eg:
2022-01-01
assets:dollars -$135
assets:euros EUR100 @ $1.35
$ hledger print --infer-equity
2022-01-01
assets:dollars $-135
assets:euros EUR100 @ $1.35
equity:conversion:$-EUR:EUR EUR-100 ; generated-posting:
equity:conversion:$-EUR:$ $135.00 ; generated-posting:
The conversion account names can be changed with the conversion account
type declaration.
--infer-equity is useful when when transactions have been recorded
using PTA cost notation, to help preserve the accounting equation and
balance reports' zero total, or to produce more conventional journal
entries for sharing with non-PTA-users.
Experimental
Inferring cost from equity postings
The reverse operation is possible using --infer-costs, which detects
transactions written with equity conversion postings and adds PTA cost
notation to them (and temporarily permits the coexistence of equity
conversion postings and cost notation). Eg:
2022-01-01
assets:dollars $-135
equity:conversion $135
equity:conversion EUR-100
assets:euros EUR100
$ hledger print --infer-costs
2022-01-01
assets:dollars $-135 @@ EUR100
equity:conversion $135
equity:conversion EUR-100
assets:euros EUR100
--infer-costs is useful when combined with -B/--cost, allowing cost
reporting even when transactions have been recorded using equity post-
ings:
$ hledger print --infer-costs -B
2009-01-01
assets:dollars EUR-100
assets:euros EUR100
Notes:
Postings will be recognised as equity conversion postings if they are
1. to account(s) declared with type V (Conversion; or if no such
accounts are declared, accounts named equity:conversion, equity:trade,
equity:trading, or subaccounts of these) 2. adjacent 3. and exactly
matching the amounts of two non-conversion postings.
The total cost is appended to the first matching posting in the trans-
action. If you need to assign it to a different posting, or if you
have several different sets of conversion postings in one transaction,
you may need to write the costs explicitly yourself. Eg:
2022-01-01
assets:dollars $-135
equity:conversion EUR-100
equity:conversion $135
assets:euros EUR100 @@ $135
or:
2022-01-01
assets:dollars $-235
assets:euros EUR100 @ $1.35 ; 100 euros bought for $1.35 each
equity:conversion EUR-100
equity:conversion $135
assets:pounds 80 @@ $100 ; 80 pounds bought for $100 total
equity:conversion -80
equity:conversion $100
--infer-equity and --infer-costs can be used together, eg if you have a
mixture of both notations.
Experimental
When to infer cost/equity
Inferring equity postings or costs is still fairly new, so not enabled
by default. We're not sure yet if that should change. Here are two
suggestions to try, experience reports welcome:
1. When you use -B, always use --infer-costs as well. Eg: hledger bal
-B --infer-costs
2. Always run hledger with both flags enabled. Eg: alias hl="hledger
--infer-equity --infer-costs"
How to record conversions
Essentially there are four ways to record a conversion transaction in
hledger. Here are all of them, with pros and cons.
Conversion with implicit cost
Let's assume 100 EUR is converted to 120 USD. You can just record the
outflow (100 EUR) and inflow (120 USD) in the appropriate asset
account:
2021-01-01 2021-01-01
assets:cash -100 EUR assets:cash -100 EUR
@ -1094,25 +1253,25 @@ CONVERSION & COST
Pro: Pro:
o Easy, concise o Concise, easy
o hledger can do cost reporting
Con: Con:
o Less error checking - typos in amounts or commodity symbols may not o Less error checking - typos in amounts or commodity symbols may not
be detected be detected
o conversion rate is not clear o Conversion rate is not clear
o disturbs the accounting equation o Disturbs the accounting equation, unless you add the --infer-equity
flag
You can prevent accidental implicit conversions due to a mistyped com- You can prevent accidental implicit conversions due to a mistyped com-
modity symbol, by using hledger check commodities. You can prevent modity symbol, by using hledger check commodities.
implicit conversions entirely, by using hledger check balancednoauto-
conversion, or -s/--strict.
Priced conversion You can prevent implicit conversions entirely, by using hledger check
balancednoautoconversion, or -s/--strict.
Conversion with explicit cost
You can add the conversion rate using @ notation: You can add the conversion rate using @ notation:
2021-01-01 2021-01-01
@ -1126,17 +1285,16 @@ CONVERSION & COST
o Still concise o Still concise
o makes the conversion rate clear o Makes the conversion rate clear
o provides some error checking o Provides more error checking
o hledger can do cost reporting
Con: Con:
o Disturbs the accounting equation without the --infer-equity flag o Disturbs the accounting equation, unless you add the --infer-equity
flag
Equity conversion Conversion with equity postings
In strict double entry bookkeeping, the above transaction is not bal- In strict double entry bookkeeping, the above transaction is not bal-
anced in EUR or in USD, since some EUR disappears, and some USD anced in EUR or in USD, since some EUR disappears, and some USD
appears. This violates the accounting equation (A+L+E=0), and prevents appears. This violates the accounting equation (A+L+E=0), and prevents
@ -1155,24 +1313,22 @@ CONVERSION & COST
o Preserves the accounting equation o Preserves the accounting equation
o keeps track of conversions and related gains/losses in one place o Keeps track of conversions and related gains/losses in one place
o works in any double entry accounting system o Standard, works in any double entry accounting system
o hledger can convert this to transaction prices using the --infer-
costs flag
Con: Con:
o More verbose o More verbose
o conversion rate is not clear o Conversion rate is not obvious
o depends on the order of postings o Cost reporting requires adding the --infer-costs flag
Priced equity conversion Conversion with equity postings and explicit cost
Another notation is to record both the conversion rate and the equity Here both equity postings and @ notation are used together. hledger
postings: will usually complain about this redundancy, but when using the
--infer-costs flag it is accepted.
2021-01-01 2021-01-01
assets:cash -100 EUR @ 1.20 USD assets:cash -100 EUR @ 1.20 USD
@ -1184,66 +1340,38 @@ CONVERSION & COST
o Preserves the accounting equation o Preserves the accounting equation
o keeps track of conversions and related gains/losses in one place o Keeps track of conversions and related gains/losses in one place
o makes the conversion rate clear o Makes the conversion rate clear
o provides some error checking o Provides more error checking
o hledger can do cost reporting
Con: Con:
o Most verbose o Most verbose
o Requires --infer-costs flag o Requires the --infer-costs flag
o Not compatible with ledger o Not compatible with ledger
Inferring missing conversion rates Cost tips
hledger will do this automatically for implicit conversions. Currently o Recording the conversion rate explicitly is good because it makes
it can not do this for equity conversions. that clear and helps detect errors.
Inferring missing equity postings o Recording equity postings is good because it is correct bookkeeping
With the --infer-equity flag, hledger will add equity postings to and preserves the accounting equation.
priced and implicit conversions.
Inferring missing transaction prices from equity postings o Combining these is possible by using the --infer-costs flag (which
With the --infer-costs flag, hledger will add transaction prices from requires well-ordered postings).
equity postings, and will be able to handle transaction prices and
equity postings together.
Cost reporting o When you want to see the cost (or sale proceeds) of things, use -B
With the -B/--cost flag, hledger will convert the amounts in priced and (or --cost). If you use equity conversion postings notation, use -B
implicit conversions to their cost in the other commodity. This is --infer-costs.
useful to see a report of what you paid for things (or how much you
sold things for). Currently -B/--cost does not work on equity conver-
sions, and it disables --infer-equity.
These operations are transient, only affecting reports. If you want to o If you use PTA cost notation, and you want to see a balanced balance
change the journal file permanently, you could pipe each entry through sheet or print correct journal entries, use --infer-equity.
hledger -f- -I print [-x] [--infer-equity] [--infer-costs] [-B]
Conversion summary o Conversion to cost is performed before valuation (described next).
o Recording the conversion rate is good because it makes that clear and
allows cost reporting.
o Recording equity postings is good because it balances the accounting
equation and is correct bookkeeping.
o Combining these is possible with the --infer-costs flag, but has cer-
tain requirements for the order of postings.
o When you want to see the cost (or sale proceeds) of things, use
-B/--cost.
o When you want to see a balanced balance sheet or correct journal
entries, use --infer-equity.
o --cost will remove any balancing equity posts, so as not to disturb
the accounting equation.
o Conversion/cost operations are performed before valuation.
VALUATION VALUATION
Instead of reporting amounts in their original commodity, hledger can Instead of reporting amounts in their original commodity, hledger can
@ -1587,15 +1715,14 @@ VALUATION
posting cost value at value at posting value at value at posting cost value at value at posting value at value at
amounts report end date report or DATE/today amounts report end date report or DATE/today
or today journal end or today journal end
balance unchanged unchanged unchanged unchanged unchanged balance unchanged unchanged unchanged unchanged unchanged
asser- asser-
tions/assign- tions/assign-
ments ments
register register
starting bal- cost value at valued at day value at value at starting bal- cost value at valued at day value at value at
ance (-H) report or each historical report or DATE/today ance (-H) report or each historical report or DATE/today
journal end posting was made journal end journal end posting was made journal end
@ -1658,8 +1785,6 @@ VALUATION
row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis- row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis-
(-T, -A) played val- played val- played val- played values (-T, -A) played val- played val- played val- played values
ues ues ues ues ues ues
column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis-
played val- played val- values played val- played values played val- played val- values played val- played values
ues ues ues ues ues ues
@ -1798,8 +1923,6 @@ OUTPUT
balance Y 1 Y 1 Y 1,2 Y balance Y 1 Y 1 Y 1,2 Y
bal- Y 1 Y 1 Y 1 Y bal- Y 1 Y 1 Y 1 Y
ancesheet ancesheet
bal- Y 1 Y 1 Y 1 Y bal- Y 1 Y 1 Y 1 Y
ancesheete- ancesheete-
quity quity
@ -5023,15 +5146,23 @@ JOURNAL FORMAT
this could vary if hledger was built with Decimal < 0.5.1.) this could vary if hledger was built with Decimal < 0.5.1.)
Transaction prices Transaction prices
Within a transaction, you can note an amount's price in another commod- (AKA Costs)
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.
There are several ways to record a transaction price: After a posting amount, you can note its cost or selling price in
another commodity, by writing either @ UNITPRICE or @@ TOTALPRICE after
it. This indicates a conversion transaction, where one commodity is
exchanged for another.
hledger docs have historically called this a "transaction price"
because it is specific to one transaction, unlike market prices which
are not. "Cost" is shorter and might be preferable; just remember this
feature can represent either a buyer's cost, or a seller's price.
Costs are usually written explicitly with @ or @@, but can also be
inferred automatically for simple multi-commodity transactions.
As an example, here are several ways to record purchases of a foreign
currency in hledger, using the cost notation either explicitly or
implicitly:
1. Write the price per unit, as @ UNITPRICE after the amount: 1. Write the price per unit, as @ UNITPRICE after the amount:
@ -5059,92 +5190,8 @@ JOURNAL FORMAT
5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger, 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger,
this is equivalent to 2. this is equivalent to 2.
Use the -B/--cost flag to convert amounts to their transaction price's Amounts can be converted to cost at report time using the -B/--cost
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). flag; this is discussed more in the COST section.
Eg here is how -B affects the balance report for the example above:
$ hledger bal -N --flat
$-135 assets:dollars
EUR100 assets:euros
$ hledger bal -N --flat -B
$-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
amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different:
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B
EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros
Equity conversion postings
Transaction prices can be converted to and from equity conversion post-
ings using the --infer-equity and --infer-costs flags.
With --infer-equity, hledger will add equity postings to balance out
any transaction prices.
2009/1/1
assets:euros EUR100 @ $1.35 ; 100 euros bought
assets:dollars -$135 ; for $135
$ hledger print --infer-equity
2009-01-01
assets:euros EUR100 @ $1.35 ; 100 euros bought
equity:conversion:$-EUR:EUR EUR-100 ; 100 euros bought, generated-posting:
equity:conversion:$-EUR:$ $135.00 ; 100 euros bought, generated-posting:
assets:dollars $-135 ; for $135
The reverse is possible using --infer-costs, which will check any
equity conversion postings and generate a transaction price for the
first non-conversion posting which matches.
2009-01-01
assets:euros EUR100 ; 100 euros bought
equity:conversion EUR-100
equity:conversion $135
assets:dollars $-135 ; for $135
$ hledger print --infer-costs
2009-01-01
assets:euros EUR100 @@ $135 ; 100 euros bought
equity:conversion EUR-100
equity:conversion $135
assets:dollars $-135 ; for $135
Note that the above will assign the transaction price to the first
matching posting in the transaction. If you want to assign it to a
different posting, or if you have several different sets of conversion
postings which must match different postings, you must manually specify
the transaction price. If you do this, equity conversion postings must
occur in adjacent pairs and must exactly match the amount of a non-con-
version posting.
2009-01-01
assets:dollars $-135 ; $135 paid
equity:conversion EUR-100
equity:conversion $135
assets:euros EUR100 @@ $135 ; to buy 100 euros
2009-01-01
assets:euros EUR100 @ $1.35 ; 100 euros bought
equity:conversion EUR-100
equity:conversion $135
assets:pounds 80 @@ $100 ; 80 pounds bought
equity:conversion -80
equity:conversion $100
assets:dollars $-235 ; for $235 total
The account names used for the conversion accounts can be changed with
the conversion account type declaration.
Lot prices, lot dates Lot prices, lot dates
Ledger allows another kind of price, lot price (four variants: {UNIT- Ledger allows another kind of price, lot price (four variants: {UNIT-
@ -5402,9 +5449,6 @@ JOURNAL FORMAT
any text, ignored. any text, ignored.
alias Rewrites account names, in following entries until end of Y alias Rewrites account names, in following entries until end of Y
current file or end aliases. current file or end aliases.
apply Prepends a common parent account to all account names, in Y apply Prepends a common parent account to all account names, in Y
account following entries until end of current file or end apply account following entries until end of current file or end apply
account. account.
@ -5802,8 +5846,7 @@ JOURNAL FORMAT
o C or Cash (a subtype of Asset, indicating liquid assets for the cash- o C or Cash (a subtype of Asset, indicating liquid assets for the cash-
flow report) flow report)
o V or Conversion (a subtype of Equity, for conversions (see CONVERSION o V or Conversion (a subtype of Equity, for conversions (see COST).)
& COST).)
Here is a typical set of account type declarations: Here is a typical set of account type declarations:
@ -6388,8 +6431,6 @@ CSV FORMAT
below, after the examples: below, after the examples:
skip skip one or more header lines or matched CSV skip skip one or more header lines or matched CSV
records records
fields list name CSV fields, assign them to hledger fields list name CSV fields, assign them to hledger
@ -7922,7 +7963,7 @@ COMMON TASKS
Show only asset and liability balances, as a flat list, limited to Show only asset and liability balances, as a flat list, limited to
depth 2: depth 2:
$ hledger bal assets liabilities --flat -2 $ hledger bal assets liabilities -2
$4000 assets:bank $4000 assets:bank
$105 assets:cash $105 assets:cash
$-50 liabilities:creditcard $-50 liabilities:creditcard
@ -7932,7 +7973,7 @@ COMMON TASKS
Show the same thing without negative numbers, formatted as a simple Show the same thing without negative numbers, formatted as a simple
balance sheet: balance sheet:
$ hledger bs --flat -2 $ hledger bs -2
Balance Sheet 2020-01-16 Balance Sheet 2020-01-16
|| 2020-01-16 || 2020-01-16
@ -8114,4 +8155,4 @@ SEE ALSO
hledger-1.26.99 August 2022 HLEDGER(1) hledger-1.27 September 2022 HLEDGER(1)