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_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_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
hledger-ui is a terminal interface (TUI) for the hledger accounting
tool.
This manual is for hledger-ui 1.26.99.
This manual is for hledger-ui 1.27.
.SH SYNOPSIS
.PP
\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
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]'
@ -640,34 +640,34 @@ program is restarted.

Tag Table:
Node: Top221
Node: OPTIONS1657
Ref: #options1755
Node: MOUSE6637
Ref: #mouse6732
Node: KEYS7014
Ref: #keys7107
Node: SCREENS11193
Ref: #screens11291
Node: Accounts screen11381
Ref: #accounts-screen11509
Node: Register screen13848
Ref: #register-screen14003
Node: Transaction screen15987
Ref: #transaction-screen16145
Node: Error screen17015
Ref: #error-screen17137
Node: TIPS17381
Ref: #tips17480
Node: Watch mode17532
Ref: #watch-mode17649
Node: Watch mode limitations18399
Ref: #watch-mode-limitations18540
Node: ENVIRONMENT19676
Ref: #environment19787
Node: FILES21172
Ref: #files21271
Node: BUGS21484
Ref: #bugs21561
Node: OPTIONS1654
Ref: #options1752
Node: MOUSE6634
Ref: #mouse6729
Node: KEYS7011
Ref: #keys7104
Node: SCREENS11190
Ref: #screens11288
Node: Accounts screen11378
Ref: #accounts-screen11506
Node: Register screen13845
Ref: #register-screen14000
Node: Transaction screen15984
Ref: #transaction-screen16142
Node: Error screen17012
Ref: #error-screen17134
Node: TIPS17378
Ref: #tips17477
Node: Watch mode17529
Ref: #watch-mode17646
Node: Watch mode limitations18396
Ref: #watch-mode-limitations18537
Node: ENVIRONMENT19673
Ref: #environment19784
Node: FILES21169
Ref: #files21268
Node: BUGS21481
Ref: #bugs21558

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
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
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_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
.PP
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
.PP
\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.
This manual is for hledger-web 1.26.99.
This manual is for hledger-web 1.27.
'hledger-web [OPTIONS]'
'hledger web -- [OPTIONS]'
@ -632,22 +632,22 @@ awkward.

Tag Table:
Node: Top223
Node: OPTIONS1889
Ref: #options1994
Node: PERMISSIONS9905
Ref: #permissions10044
Node: EDITING UPLOADING DOWNLOADING11256
Ref: #editing-uploading-downloading11437
Node: RELOADING12271
Ref: #reloading12405
Node: JSON API12838
Ref: #json-api12952
Node: ENVIRONMENT18442
Ref: #environment18558
Node: FILES19869
Ref: #files19969
Node: BUGS20182
Ref: #bugs20260
Node: OPTIONS1886
Ref: #options1991
Node: PERMISSIONS9902
Ref: #permissions10041
Node: EDITING UPLOADING DOWNLOADING11253
Ref: #editing-uploading-downloading11434
Node: RELOADING12268
Ref: #reloading12402
Node: JSON API12835
Ref: #json-api12949
Node: ENVIRONMENT18439
Ref: #environment18555
Node: FILES19866
Ref: #files19966
Node: BUGS20179
Ref: #bugs20257

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
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
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_define({{_monthyear_}}, {{August 2022}})m4_dnl
m4_define({{_monthyear_}}, {{September 2022}})m4_dnl

538
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"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
tool.
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
.PP
\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.
Note: this changed in hledger 1.22, previously it was the reverse, see
the discussion at #1625.
.SH CONVERSION & COST
.SH COST
.PP
This section is about converting between commodities.
Some definitions:
This section is about recording the cost of things, in transactions
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
A \[dq]commodity conversion\[dq] is an exchange of one currency or
commodity for another.
Conversion - an exchange of one currency or commodity for another.
Eg a foreign currency exchange, or a purchase or sale of stock or
cryptocurrency.
.IP \[bu] 2
A \[dq]conversion transaction\[dq] is a transaction involving one or
more such conversions.
Conversion transaction - a transaction involving one or more
conversions.
.IP \[bu] 2
\[dq]Conversion rate\[dq] is the exchange rate in a conversion - the
cost per unit of one commodity in the other.
Conversion rate - the cost per unit of one commodity in the other, ie
the exchange rate.
.IP \[bu] 2
\[dq]Cost\[dq] is how much of one commodity was paid to acquire the
other (when buying), or how much was received in exchange for the other
(when selling).
We call both of these \[dq]cost\[dq] for convenience (after all, it is
cost for one party or the other).
.SS Recording conversions
Cost - how much of one commodity was paid to acquire the other.
And more generally, in hledger docs: the amount exchanged in the
\[dq]secondary\[dq] commodity (usually your base currency), whether in a
purchase or a sale, and whether expressed per unit or in total.
Or, the \[at]/\[at]\[at] notation used to represent this.
.IP \[bu] 2
Transaction price - another name for the cost expressed with
hledger\[aq]s cost notation.
.SS -B: Convert to cost
.PP
As a concrete example, let\[aq]s assume 100 EUR was converted to 120
USD.
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.)
.SS Implicit conversion
As discussed a little further on in Transaction prices, when recording a
transaction you can also record the amount\[aq]s cost in another
commodity, by adding \f[C]\[at] UNITPRICE\f[R] or
\f[C]\[at]\[at] TOTALPRICE\f[R].
.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
appropriate asset account:
.IP
@ -1613,25 +1832,24 @@ You can see the inferred rate by using \f[C]hledger print -x\f[R].
.PP
Pro:
.IP \[bu] 2
Easy, concise
.IP \[bu] 2
hledger can do cost reporting
Concise, easy
.PP
Con:
.IP \[bu] 2
Less error checking - typos in amounts or commodity symbols may not be
detected
.IP \[bu] 2
conversion rate is not clear
Conversion rate is not clear
.IP \[bu] 2
disturbs the accounting equation
Disturbs the accounting equation, unless you add the --infer-equity flag
.PP
You can prevent accidental implicit conversions due to a mistyped
commodity symbol, by using \f[C]hledger check commodities\f[R].
.PP
You can prevent implicit conversions entirely, by using
\f[C]hledger check balancednoautoconversion\f[R], or
\f[C]-s/--strict\f[R].
.SS Priced conversion
.SS Conversion with explicit cost
.PP
You can add the conversion rate using \[at] notation:
.IP
@ -1650,16 +1868,14 @@ Pro:
.IP \[bu] 2
Still concise
.IP \[bu] 2
makes the conversion rate clear
Makes the conversion rate clear
.IP \[bu] 2
provides some error checking
.IP \[bu] 2
hledger can do cost reporting
Provides more error checking
.PP
Con:
.IP \[bu] 2
Disturbs the accounting equation without the --infer-equity flag
.SS Equity conversion
Disturbs the accounting equation, unless you add the --infer-equity flag
.SS Conversion with equity postings
.PP
In strict double entry bookkeeping, the above transaction is not
balanced in EUR or in USD, since some EUR disappears, and some USD
@ -1684,24 +1900,22 @@ Pro:
.IP \[bu] 2
Preserves the accounting equation
.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
works in any double entry accounting system
.IP \[bu] 2
hledger can convert this to transaction prices using the --infer-costs
flag
Standard, works in any double entry accounting system
.PP
Con:
.IP \[bu] 2
More verbose
.IP \[bu] 2
conversion rate is not clear
Conversion rate is not obvious
.IP \[bu] 2
depends on the order of postings
.SS Priced equity conversion
Cost reporting requires adding the --infer-costs flag
.SS Conversion with equity postings and explicit cost
.PP
Another notation is to record both the conversion rate and the equity
postings:
Here both equity postings and \[at] notation are used together.
hledger will usually complain about this redundancy, but when using the
--infer-costs flag it is accepted.
.IP
.nf
\f[C]
@ -1717,68 +1931,39 @@ Pro:
.IP \[bu] 2
Preserves the accounting equation
.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
makes the conversion rate clear
Makes the conversion rate clear
.IP \[bu] 2
provides some error checking
.IP \[bu] 2
hledger can do cost reporting
Provides more error checking
.PP
Con:
.IP \[bu] 2
Most verbose
.IP \[bu] 2
Requires --infer-costs flag
Requires the --infer-costs flag
.IP \[bu] 2
Not compatible with ledger
.SS Inferring missing conversion rates
.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
.SS Cost tips
.IP \[bu] 2
Recording the conversion rate is good because it makes that clear and
allows cost reporting.
Recording the conversion rate explicitly is good because it makes that
clear and helps detect errors.
.IP \[bu] 2
Recording equity postings is good because it balances the accounting
equation and is correct bookkeeping.
Recording equity postings is good because it is correct bookkeeping and
preserves the accounting equation.
.IP \[bu] 2
Combining these is possible with the --infer-costs flag, but has certain
requirements for the order of postings.
Combining these is possible by using the --infer-costs flag (which
requires well-ordered postings).
.IP \[bu] 2
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
When you want to see a balanced balance sheet or correct journal
entries, use \f[C]--infer-equity\f[R].
If you use PTA cost notation, and you want to see a balanced balance
sheet or print correct journal entries, use \f[C]--infer-equity\f[R].
.IP \[bu] 2
\f[C]--cost\f[R] will remove any balancing equity posts, so as not to
disturb the accounting equation.
.IP \[bu] 2
Conversion/cost operations are performed before valuation.
Conversion to cost is performed before valuation (described next).
.SH VALUATION
.PP
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.)
.SS Transaction prices
.PP
Within a transaction, you can note an amount\[aq]s price in another
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.
(AKA Costs)
.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
Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount:
.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.
\f[C](\[at]\[at])\f[R]; in hledger, this is equivalent to 2.
.PP
Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
price\[aq]s commodity, if any.
(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.
Amounts can be converted to cost at report time using the
\f[C]-B/--cost\f[R] flag; this is discussed more in the COST section.
.SS Lot prices, lot dates
.PP
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)
.IP \[bu] 2
\f[C]V\f[R] or \f[C]Conversion\f[R] (a subtype of Equity, for
conversions (see CONVERSION & COST).)
conversions (see COST).)
.PP
Here is a typical set of account type declarations:
.IP
@ -10933,7 +11007,7 @@ Show only asset and liability balances, as a flat list, limited to depth
.IP
.nf
\f[C]
$ hledger bal assets liabilities --flat -2
$ hledger bal assets liabilities -2
$4000 assets:bank
$105 assets:cash
$-50 liabilities:creditcard
@ -10947,7 +11021,7 @@ balance sheet:
.IP
.nf
\f[C]
$ hledger bs --flat -2
$ hledger bs -2
Balance Sheet 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
This is the command-line interface (CLI) for the hledger accounting
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
hledger
@ -1054,35 +1054,194 @@ QUERIES
this changed in hledger 1.22, previously it was the reverse, see the
discussion at #1625.
CONVERSION & COST
This section is about converting between commodities. Some defini-
tions:
COST
This section is about recording the cost of things, in transactions
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
for another. Eg a foreign currency exchange, or a purchase or sale
of stock or cryptocurrency.
o Conversion - an exchange of one currency or commodity for another.
Eg a foreign currency exchange, or a purchase or sale of stock or
cryptocurrency.
o A "conversion transaction" is a transaction involving one or more
such conversions.
o Conversion transaction - a transaction involving one or more conver-
sions.
o "Conversion rate" is the exchange rate in a conversion - the cost per
unit of one commodity in the other.
o Conversion rate - the cost per unit of one commodity in the other, ie
the exchange rate.
o "Cost" is how much of one commodity was paid to acquire the other
(when buying), or how much was received in exchange for the other
(when selling). We call both of these "cost" for convenience (after
all, it is cost for one party or the other).
o Cost - how much of one commodity was paid to acquire the other. And
more generally, in hledger docs: the amount exchanged in the "sec-
ondary" commodity (usually your base currency), whether in a purchase
or a sale, and whether expressed per unit or in total. Or, the @/@@
notation used to represent this.
Recording conversions
As a concrete example, let's assume 100 EUR was converted to 120 USD.
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.)
o Transaction price - another name for the cost expressed with
hledger's cost notation.
Implicit conversion
You can just record the outflow (100 EUR) and inflow (120 USD) in the
appropriate asset account:
-B: Convert to cost
As discussed a little further on in Transaction prices, when recording
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
assets:cash -100 EUR
@ -1094,25 +1253,25 @@ CONVERSION & COST
Pro:
o Easy, concise
o hledger can do cost reporting
o Concise, easy
Con:
o Less error checking - typos in amounts or commodity symbols may not
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-
modity symbol, by using hledger check commodities. You can prevent
implicit conversions entirely, by using hledger check balancednoauto-
conversion, or -s/--strict.
modity symbol, by using hledger check commodities.
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:
2021-01-01
@ -1126,17 +1285,16 @@ CONVERSION & COST
o Still concise
o makes the conversion rate clear
o Makes the conversion rate clear
o provides some error checking
o hledger can do cost reporting
o Provides more error checking
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-
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
@ -1155,24 +1313,22 @@ CONVERSION & COST
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 hledger can convert this to transaction prices using the --infer-
costs flag
o Standard, works in any double entry accounting system
Con:
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
Another notation is to record both the conversion rate and the equity
postings:
Conversion with equity postings and explicit cost
Here both equity postings and @ notation are used together. hledger
will usually complain about this redundancy, but when using the
--infer-costs flag it is accepted.
2021-01-01
assets:cash -100 EUR @ 1.20 USD
@ -1184,66 +1340,38 @@ CONVERSION & COST
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 hledger can do cost reporting
o Provides more error checking
Con:
o Most verbose
o Requires --infer-costs flag
o Requires the --infer-costs flag
o Not compatible with ledger
Inferring missing conversion rates
hledger will do this automatically for implicit conversions. Currently
it can not do this for equity conversions.
Cost tips
o Recording the conversion rate explicitly is good because it makes
that clear and helps detect errors.
Inferring missing equity postings
With the --infer-equity flag, hledger will add equity postings to
priced and implicit conversions.
o Recording equity postings is good because it is correct bookkeeping
and preserves the accounting equation.
Inferring missing transaction prices from equity postings
With the --infer-costs flag, hledger will add transaction prices from
equity postings, and will be able to handle transaction prices and
equity postings together.
o Combining these is possible by using the --infer-costs flag (which
requires well-ordered postings).
Cost reporting
With the -B/--cost 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 -B/--cost does not work on equity conver-
sions, and it disables --infer-equity.
o When you want to see the cost (or sale proceeds) of things, use -B
(or --cost). If you use equity conversion postings notation, use -B
--infer-costs.
These operations are transient, only affecting reports. If you want to
change the journal file permanently, you could pipe each entry through
hledger -f- -I print [-x] [--infer-equity] [--infer-costs] [-B]
o If you use PTA cost notation, and you want to see a balanced balance
sheet or print correct journal entries, use --infer-equity.
Conversion summary
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.
o Conversion to cost is performed before valuation (described next).
VALUATION
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
amounts report end date report or DATE/today
or today journal end
balance unchanged unchanged unchanged unchanged unchanged
asser-
tions/assign-
ments
register
starting bal- cost value at valued at day value at value at
ance (-H) report or each historical report or DATE/today
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-
(-T, -A) played val- played val- played val- played values
ues ues ues
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
ues ues ues
@ -1798,8 +1923,6 @@ OUTPUT
balance Y 1 Y 1 Y 1,2 Y
bal- Y 1 Y 1 Y 1 Y
ancesheet
bal- Y 1 Y 1 Y 1 Y
ancesheete-
quity
@ -5023,15 +5146,23 @@ JOURNAL FORMAT
this could vary if hledger was built with Decimal < 0.5.1.)
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
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.
(AKA Costs)
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:
@ -5059,92 +5190,8 @@ JOURNAL FORMAT
5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger,
this is equivalent to 2.
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:
$ 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.
Amounts can be converted to cost at report time using the -B/--cost
flag; this is discussed more in the COST section.
Lot prices, lot dates
Ledger allows another kind of price, lot price (four variants: {UNIT-
@ -5402,9 +5449,6 @@ JOURNAL FORMAT
any text, ignored.
alias Rewrites account names, in following entries until end of Y
current file or end aliases.
apply Prepends a common parent account to all account names, in Y
account following entries until end of current file or end apply
account.
@ -5802,8 +5846,7 @@ JOURNAL FORMAT
o C or Cash (a subtype of Asset, indicating liquid assets for the cash-
flow report)
o V or Conversion (a subtype of Equity, for conversions (see CONVERSION
& COST).)
o V or Conversion (a subtype of Equity, for conversions (see COST).)
Here is a typical set of account type declarations:
@ -6388,8 +6431,6 @@ CSV FORMAT
below, after the examples:
skip skip one or more header lines or matched CSV
records
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
depth 2:
$ hledger bal assets liabilities --flat -2
$ hledger bal assets liabilities -2
$4000 assets:bank
$105 assets:cash
$-50 liabilities:creditcard
@ -7932,7 +7973,7 @@ COMMON TASKS
Show the same thing without negative numbers, formatted as a simple
balance sheet:
$ hledger bs --flat -2
$ hledger bs -2
Balance Sheet 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)