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 2023-08-22 08:41:22 +01:00
parent 95b67ef86b
commit 115b639ec2
11 changed files with 2474 additions and 2826 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_}}, {{June 2023}})m4_dnl m4_define({{_monthyear_}}, {{August 2023}})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_}}, {{June 2023}})m4_dnl m4_define({{_monthyear_}}, {{August 2023}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER-UI" "1" "June 2023" "hledger-ui-1.30.99 " "hledger User Manuals" .TH "HLEDGER-UI" "1" "August 2023" "hledger-ui-1.30.99 " "hledger User Manuals"

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

@ -1,8 +1,6 @@
HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1) HLEDGER-UI(1) hledger User Manuals HLEDGER-UI(1)
NAME NAME
hledger-ui - robust, friendly plain text accounting (TUI version) hledger-ui - robust, friendly plain text accounting (TUI version)
@ -529,6 +527,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.30.99 August 2023 HLEDGER-UI(1)
hledger-ui-1.30.99 June 2023 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_}}, {{June 2023}})m4_dnl m4_define({{_monthyear_}}, {{August 2023}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER-WEB" "1" "June 2023" "hledger-web-1.30.99 " "hledger User Manuals" .TH "HLEDGER-WEB" "1" "August 2023" "hledger-web-1.30.99 " "hledger User Manuals"

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

@ -1,8 +1,6 @@
HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1) HLEDGER-WEB(1) hledger User Manuals HLEDGER-WEB(1)
NAME NAME
hledger-web - robust, friendly plain text accounting (Web version) hledger-web - robust, friendly plain text accounting (Web version)
@ -569,6 +567,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.30.99 August 2023 HLEDGER-WEB(1)
hledger-web-1.30.99 June 2023 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_}}, {{June 2023}})m4_dnl m4_define({{_monthyear_}}, {{August 2023}})m4_dnl

785
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "HLEDGER" "1" "June 2023" "hledger-1.30.99 " "hledger User Manuals" .TH "HLEDGER" "1" "August 2023" "hledger-1.30.99 " "hledger User Manuals"
@ -759,7 +759,7 @@ Here are those commands and the formats currently supported:
.PP .PP
.TS .TS
tab(@); tab(@);
lw(25.9n) lw(9.1n) lw(9.1n) lw(11.7n) lw(7.8n) lw(6.5n). lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).
T{ T{
- -
T}@T{ T}@T{
@ -1814,7 +1814,7 @@ making it \f[V]€100 \[at]\[at] $135\f[R], as in example 2:
.RE .RE
.PP .PP
Amounts can be converted to cost at report time using the Amounts can be converted to cost at report time using the
\f[V]-B/--cost\f[R] flag; this is discussed more in the ˜COST REPORTING \f[V]-B/--cost\f[R] flag; this is discussed more in the Cost reporting
section. section.
.PP .PP
Note that the cost normally should be a positive amount, though it\[aq]s Note that the cost normally should be a positive amount, though it\[aq]s
@ -2619,7 +2619,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[V]V\f[R] or \f[V]Conversion\f[R] (a subtype of Equity, for \f[V]V\f[R] or \f[V]Conversion\f[R] (a subtype of Equity, for
conversions (see COST REPORTING).) conversions (see Cost reporting).)
.PP .PP
Here is a typical set of account type declarations: Here is a typical set of account type declarations:
.IP .IP
@ -3133,7 +3133,7 @@ P 2010-01-01 € $1.40
.PP .PP
The \f[V]-V\f[R], \f[V]-X\f[R] and \f[V]--value\f[R] flags use these The \f[V]-V\f[R], \f[V]-X\f[R] and \f[V]--value\f[R] flags use these
market prices to show amount values in another commodity. market prices to show amount values in another commodity.
See Valuation. See Value reporting.
.PP .PP
.SS \f[V]payee\f[R] directive .SS \f[V]payee\f[R] directive
.PP .PP
@ -3499,6 +3499,11 @@ $ hledger print --explicit
(a) $1 \[at] €2 = $1 \[at] €2 (a) $1 \[at] €2 = $1 \[at] €2
\f[R] \f[R]
.fi .fi
.SS Balance assignments and multiple files
.PP
Balance assignments handle multiple files like balance assertions.
They see balance from other files previously included from the current
file, but not from previous sibling or parent files.
.SS Bracketed posting dates .SS Bracketed posting dates
.PP .PP
For setting posting dates and secondary posting dates, Ledger\[aq]s For setting posting dates and secondary posting dates, Ledger\[aq]s
@ -4073,7 +4078,7 @@ For others, use numeric format: +HHMM or -HHMM.
.SS \f[V]newest-first\f[R] .SS \f[V]newest-first\f[R]
.PP .PP
hledger tries to ensure that the generated transactions will be ordered hledger tries to ensure that the generated transactions will be ordered
chronologically, including intra-day transactions. chronologically, including same-day transactions.
Usually it can auto-detect how the CSV records are ordered. Usually it can auto-detect how the CSV records are ordered.
But if it encounters CSV where all records are on the same date, it But if it encounters CSV where all records are on the same date, it
assumes that the records are oldest first. assumes that the records are oldest first.
@ -4098,10 +4103,11 @@ newest-first
.fi .fi
.SS \f[V]intra-day-reversed\f[R] .SS \f[V]intra-day-reversed\f[R]
.PP .PP
CSV records for each day are sometimes ordered in reverse compared to If CSV records within a single day are ordered opposite to the overall
the overall date order. record order, you can add the \f[V]intra-day-reversed\f[R] rule to
Eg, here dates are newest first, but the transactions on each date are improve the order of journal entries.
oldest first: Eg, here the overall record order is newest first, but same-day records
are oldest first:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -4111,9 +4117,6 @@ oldest first:
2022-10-01, txn 2... 2022-10-01, txn 2...
\f[R] \f[R]
.fi .fi
.PP
In this situation, add the \f[V]intra-day-reversed\f[R] rule, and
hledger will compensate, improving the order of transactions.
.IP .IP
.nf .nf
\f[C] \f[C]
@ -4326,103 +4329,69 @@ below), a default account name will be chosen (like
\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]). \[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).
.SS amount field .SS amount field
.PP .PP
Amount setting can get a bit complex. There are several ways to set posting amounts from CSV, useful in
Assigning to \f[V]amount\f[R] is sufficient for simple transactions, but different situations.
there are four field name variants you can use for different situations: .IP "1." 3
\f[B]\f[VB]amount\f[B]\f[R] is the oldest and simplest.
Assigning to this sets the amount of the first and second postings.
In the second posting, the amount will be negated; also, if it has a
cost attached, it will be converted to cost.
.IP "2." 3
\f[B]\f[VB]amount-in\f[B]\f[R] and \f[B]\f[VB]amount-out\f[B]\f[R] work
exactly like the above, but should be used when the CSV has two amount
fields (such as \[dq]Debit\[dq] and \[dq]Credit\[dq], or
\[dq]Inflow\[dq] and \[dq]Outflow\[dq]).
Whichever field has a non-zero value will be used as the amount of the
first and second postings.
Here are some tips to avoid confusion:
.RS 4
.IP \[bu] 2 .IP \[bu] 2
\f[B]\f[VB]amountN\f[B] sets a specific posting\[aq]s amount from one It\[aq]s not \[dq]amount-in for posting 1 and amount-out for posting
CSV field or arbitrary value.\f[R] 2\[dq], it is \[dq]extract a single amount from the amount-in or
.PD 0 amount-out field, and use that for posting 1 and (negated) for posting
.P 2\[dq].
.PD
Assigning to \f[V]amountN\f[R] sets the amount of the Nth posting - and
also causes that posting to be generated.
N is most often 1 or 2 but can go up to 99, potentially generating a
99-posting transaction.
(Posting numbers don\[aq]t have to be consecutive; higher posting
numbers can sometimes be useful with conditional rules, to ensure a
certain ordering of postings.)
.IP \[bu] 2 .IP \[bu] 2
\f[B]\f[VB]amountN-in/-out\f[B] sets a specific posting\[aq]s amount Don\[aq]t use both \f[V]amount\f[R] and
from two CSV fields.\f[R] \f[V]amount-in\f[R]/\f[V]amount-out\f[R] in the same rules file; choose
.PD 0 based on whether the amount is in a single CSV field or spread across
.P two fields.
.PD
When the amount is provided as two CSV fields -
\[dq]Debit\[dq]/\[dq]Credit\[dq],
\[dq]Deposit\[dq]/\[dq]Withdrawal\[dq], \[dq]Money In\[dq]/\[dq]Money
Out\[dq] or similar - assign those fields to \f[V]amountN-in\f[R] and
\f[V]amountN-out\f[R] respectively (or possibly the other way round,
depending on signs).
This will set the Nth posting\[aq]s amount to whichever of the two CSV
field values is non-zero.
Some notes:
.RS 2
.IP \[bu] 2 .IP \[bu] 2
Don\[aq]t mix \f[V]amountN\f[R] and \f[V]amountN-in\f[R]/\f[V]-out\f[R]. In each record, at most one of the two CSV fields should contain a
When you have one CSV amount field, use \f[V]amountN\f[R]. non-zero amount; the other field must contain a zero or nothing.
When you have two CSV amount fields, use
\f[V]amountN-in\f[R]/\f[V]amountN-out\f[R].
.IP \[bu] 2 .IP \[bu] 2
\f[V]amountN-in\f[R] and \f[V]amountN-out\f[R] are always used together, hledger assumes both CSV fields contain unsigned numbers, and it
as a pair. automatically negates the amount-out values.
Assign to both of them.
.IP \[bu] 2 .IP \[bu] 2
They do not generate two separate postings; rather, they generate the If the data doesn\[aq]t fit these requirements, you\[aq]ll probably need
Nth posting\[aq]s single amount, from the value found in one or other of an if rule (see below).
the two CSV fields.
.IP \[bu] 2
In each record, at least one of the two CSV fields must contain a zero
amount or be empty.
.IP \[bu] 2
hledger assumes the two CSV fields contain unsigned numbers, and it will
automatically negate the -out amount.
.IP \[bu] 2
This variant can be convenient, but it doesn\[aq]t handle every
two-amount-field situation; if you need more flexibility, use an
\f[V]if\f[R] rule (see \[dq]Setting amounts\[dq] below).
.RE .RE
.PP .IP "3." 3
The other two variants are older and considered legacy syntax, but can \f[B]\f[VB]amountN\f[B]\f[R] (where N is a number from 1 to 99) sets the
still be convenient sometimes: amount of only a single posting: the Nth posting in the transaction.
.IP \[bu] 2 You\[aq]ll usually need at least two such assignments to make a balanced
\f[B]\f[VB]amount\f[B] sets posting 1 and 2\[aq]s amounts from one CSV transaction.
field or value.\f[R] You can also generate more than two postings, to represent more complex
.PD 0 transactions.
.P The posting numbers don\[aq]t have to be consecutive; with if rules,
.PD higher posting numbers can be useful to ensure a certain order of
Assigning to \f[V]amount\f[R], with no posting number, postings.
.RS 2 .IP "4." 3
.IP \[bu] 2 \f[B]\f[VB]amountN-in\f[B]\f[R] and \f[B]\f[VB]amountN-out\f[B]\f[R]
sets posting 1\[aq]s amount (like \f[V]amount1\f[R]) work exactly like the above, but should be used when the CSV has two
.IP \[bu] 2 amount fields.
sets posting 2\[aq]s amount to the same amount but with opposite sign; This is analogous to \f[V]amount-in\f[R] and \f[V]amount-out\f[R], and
and also converts it to cost if it has a cost price those tips also apply here.
.IP \[bu] 2 .IP "5." 3
can be overridden by \f[V]amount1\f[R] and/or \f[V]amount2\f[R] Remember that a \f[V]fields\f[R] list can also do assignments.
assignments. So in a fields list if you name a CSV field \[dq]amount\[dq], that
(This helps with incremental migration of old rules files to the newer counts as assigning to \f[V]amount\f[R].
syntax.) (If you don\[aq]t want that, call it something else in the fields list,
.RE like \[dq]amount_\[dq].)
.IP \[bu] 2 .IP "6." 3
\f[B]\f[VB]amount-in/-out\f[B] sets posting 1 and 2\[aq]s amounts from The above don\[aq]t handle every situation; if you need more
two CSV fields.\f[R] flexibility, use an \f[V]if\f[R] rule to set amounts conditionally.
.PD 0 See \[dq]Working with CSV > Setting amounts\[dq] below for more on this
.P and on amount-setting generally.
.PD
Assigning \f[V]amount-in\f[R] and \f[V]amount-out\f[R], with no posting
numbers, to two CSV fields reads whichever of the two values is non-zero
as the amount, and then sets the first two posting amounts as above.
.PP
We recommend using only one of these variants within a rules file,
rather than mixing them.
And remember that a \f[V]fields\f[R] list can also do assignments, so eg
naming a CSV field \[dq]amount\[dq] counts as an assignment to
\f[V]amount\f[R]; if you don\[aq]t want that, call it something else,
like \[dq]amount_\[dq].
.PP
In addition to this section, please see also the tips beginning at
\[dq]Working with CSV > Setting amounts\[dq] below.
.SS currency field .SS currency field
.PP .PP
\f[V]currency\f[R] sets a currency symbol, to be prepended to all \f[V]currency\f[R] sets a currency symbol, to be prepended to all
@ -4849,8 +4818,8 @@ https://hledger.org/cookbook.html#setups-and-workflows
https://plaintextaccounting.org -> data import/conversion https://plaintextaccounting.org -> data import/conversion
.SS Setting amounts .SS Setting amounts
.PP .PP
Continuing from amount field above, here are more tips on handling Continuing from amount field above, here are more tips for
various amount-setting situations: amount-setting:
.IP "1." 3 .IP "1." 3
\f[B]If the amount is in a single CSV field:\f[R] \f[B]If the amount is in a single CSV field:\f[R]
.PD 0 .PD 0
@ -4882,8 +4851,8 @@ if %Type deposit
.fi .fi
.RE .RE
.IP "2." 3 .IP "2." 3
\f[B]If the amount is in one of two CSV fields (eg Debit and \f[B]If the amount is in two CSV fields (such as Debit and Credit, or In
Credit):\f[R] and Out):\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
@ -4893,22 +4862,21 @@ Credit):\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
Assign the fields to \f[V]amountN-in\f[R] and \f[V]amountN-out\f[R]. Assign one field to \f[V]amountN-in\f[R] and the other to
This sets posting N\[aq]s amount to whichever of these has a non-zero \f[V]amountN-out\f[R].
value. hledger will automatically negate the \[dq]out\[dq] field, and will use
If it\[aq]s the -out value, the amount will be negated. whichever field value is non-zero as posting N\[aq]s amount.
.IP "b." 3 .IP "b." 3
\f[B]If either field is signed:\f[R] \f[B]If either field is signed:\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
Use a conditional rule to flip the sign when needed. You will probably need to override hledger\[aq]s sign for one or the
Eg below, the -out value already has a minus sign so we undo other field, as in the following example:
hledger\[aq]s automatic negating by negating once more (but only if the
field is non-empty, so that we don\[aq]t leave a minus sign by itself):
.IP .IP
.nf .nf
\f[C] \f[C]
# Negate the -out value, but only if it is not empty:
fields date, description, amount1-in, amount1-out fields date, description, amount1-in, amount1-out
if %amount1-out [1-9] if %amount1-out [1-9]
amount1-out -%amount1-out amount1-out -%amount1-out
@ -6945,116 +6913,169 @@ time, from the same or different periodic transaction rules:
See also: Budgeting and Forecasting. See also: Budgeting and Forecasting.
.SH Cost reporting .SH Cost reporting
.PP .PP
This section is about recording the cost of things, in transactions In some transactions - for example a currency conversion, or a purchase
where one commodity is exchanged for another. or sale of stock - one commodity is exchanged for another.
Eg an exchange of currency, or a stock purchase or sale. In these transactions there is a conversion rate, also called the cost
First, a quick glossary: (when buying) or selling price (when selling).
.IP \[bu] 2 In hledger docs we just say \[dq]cost\[dq], for convenience; feel free
Conversion - an exchange of one currency or commodity for another. to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling
Eg a foreign currency exchange, or a purchase or sale of stock or price\[dq] if helpful.
cryptocurrency. .SS Recording costs
.IP \[bu] 2
Conversion transaction - a transaction involving one or more
conversions.
.IP \[bu] 2
Conversion rate - the cost per unit of one commodity in the other, ie
the exchange rate.
.IP \[bu] 2
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.
Also, the \[dq]\[at]/\[at]\[at] PRICE\[dq] notation used to represent
this.
.SS -B: Convert to cost
.PP .PP
As discussed in JOURNAL > Costs, when recording a transaction you can We\[aq]ll explore several ways of recording transactions involving
also record the amount\[aq]s cost in another commodity, by adding costs.
\f[V]\[at] UNITPRICE\f[R] or \f[V]\[at]\[at] TOTALPRICE\f[R]. These are also summarised at hledger Cookbook > Cost notation.
.PP .PP
Then you can see a report with amounts converted to cost, by adding the Costs can be recorded explicitly in the journal, using the
\f[V]-B/--cost\f[R] flag. \f[V]\[at] UNITCOST\f[R] or \f[V]\[at]\[at] TOTALCOST\f[R] notation
(Mnemonic: \[dq]B\[dq] from \[dq]cost Basis\[dq], as in Ledger). described in Journal > Costs:
Eg: .PP
\f[B]Variant 1\f[R]
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135
assets:euros €100 \[at] $1.35 ; $1.35 per euro (unit cost)
\f[R]
.fi
.PP
\f[B]Variant 2\f[R]
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135
assets:euros €100 \[at]\[at] $135 ; $135 total cost
\f[R]
.fi
.PP
Typically, writing the unit cost (variant 1) is preferable; it can be
more effort, requiring more attention to decimal digits; but it reveals
the per-unit cost basis, and makes stock sales easier.
.PP
Costs can also be left implicit, and hledger will infer the cost that is
consistent with a balanced transaction:
.PP
\f[B]Variant 3\f[R]
.IP .IP
.nf .nf
\f[C] \f[C]
2022-01-01 2022-01-01
assets:dollars $-135 ; 135 dollars is exchanged for..
assets:euros €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
€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 cost 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 €100 ; for 100 euros
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal -N -B
€-100 assets:dollars # <- the dollars\[aq] selling price
€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 assets:dollars $-135
equity:conversion $135
equity:conversion €-100
assets:euros €100 assets:euros €100
\f[R] \f[R]
.fi .fi
.PP .PP
This style is more correct, but it\[aq]s also more verbose and makes Here, hledger will attach a \f[V]\[at]\[at] €100\f[R] cost to the first
cost reporting more difficult for PTA tools. amount (you can see it with \f[V]hledger print -x\f[R]).
This form looks convenient, but there are downsides:
.IP \[bu] 2
It sacrifices some error checking.
For example, if you accidentally wrote €10 instead of €100, hledger
would not be able to detect the mistake.
.IP \[bu] 2
It is sensitive to the order of postings - if they were reversed, a
different entry would be inferred and reports would be different.
.IP \[bu] 2
The per-unit cost basis is not easy to read.
.PP .PP
Happily, current hledger can read either notation, or convert one to the So generally this kind of entry is not recommended.
other when needed, so you can use the one you prefer. You can make sure you have none of these by using \f[V]-s\f[R] (strict
mode), or by running \f[V]hledger check balanced\f[R].
.SS Reporting at cost
.PP .PP
You can even use cost notation and equivalent conversion postings at the Now when you add the \f[V]-B\f[R]/\f[V]--cost\f[R] flag to reports
same time, for clarity. (\[dq]B\[dq] is from Ledger\[aq]s -B/--basis/--cost flag), any amounts
hledger will ignore the redundancy. which have been annotated with costs will be converted to their
But be sure the cost and conversion posting amounts match, or you\[aq]ll cost\[aq]s commodity (in the report output).
see a not-so-clear transaction balancing error message. Ie they will be displayed \[dq]at cost\[dq] or \[dq]at sale price\[dq].
.SS Inferring equity postings from cost
.PP .PP
With \f[V]--infer-equity\f[R], hledger detects transactions written with Some things to note:
PTA cost notation and adds equity conversion postings to them: .IP \[bu] 2
Costs are attached to specific posting amounts in specific transactions,
and once recorded they do not change.
This contrasts with market prices, which are ambient and fluctuating.
.IP \[bu] 2
Conversion to cost is performed before conversion to market value
(described below).
.SS Equity conversion postings
.PP
There is a problem with the entries above - they are not conventional
Double Entry Bookkeeping (DEB) notation, and because of the
\[dq]magical\[dq] transformation of one commodity into another, they
cause an imbalance in the Accounting Equation.
This shows up as a non-zero grand total in balance reports like
\f[V]hledger bse\f[R].
.PP
For most hledger users, this doesn\[aq]t matter in practice and can
safely be ignored !
But if you\[aq]d like to learn more, keep reading.
.PP
Conventional DEB uses an extra pair of equity postings to balance the
transaction.
Of course you can do this in hledger as well:
.PP
\f[B]Variant 4\f[R]
.IP
.nf
\f[C]
2022-01-01
assets:dollars $-135
assets:euros €100
equity:conversion $135
equity:conversion €-100
\f[R]
.fi
.PP
Now the transaction is perfectly balanced according to standard DEB, and
\f[V]hledger bse\f[R]\[aq]s total will not be disrupted.
.PP
And, hledger can still infer the cost for cost reporting, but it\[aq]s
not done by default - you must add the \f[V]--infer-costs\f[R] flag like
so:
.IP
.nf
\f[C]
$ hledger print --infer-costs
2022-01-01 one hundred euros purchased at $1.35 each
assets:dollars $-135 \[at]\[at] €100
assets:euros €100
equity:conversion $135
equity:conversion €-100
\f[R]
.fi
.IP
.nf
\f[C]
$ hledger bal --infer-costs -B
€-100 assets:dollars
€100 assets:euros
--------------------
0
\f[R]
.fi
.PP
Here are some downsides of this kind of entry:
.IP \[bu] 2
The per-unit cost basis is not easy to read.
.IP \[bu] 2
Instead of \f[V]-B\f[R] you must remember to type
\f[V]-B --infer-costs\f[R].
.IP \[bu] 2
\f[V]--infer-costs\f[R] works only where hledger can identify the two
equity:conversion postings and match them up with the two non-equity
postings.
So writing the journal entry in a particular format becomes more
important.
More on this below.
.SS Inferring equity conversion postings
.PP
Can we go in the other direction ?
Yes, if you have transactions written with the \[at]/\[at]\[at] cost
notation, hledger can infer the missing equity postings, if you add the
\f[V]--infer-equity\f[R] flag.
Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -7070,252 +7091,105 @@ $ hledger print --infer-equity
2022-01-01 2022-01-01
assets:dollars $-135 assets:dollars $-135
assets:euros €100 \[at] $1.35 assets:euros €100 \[at] $1.35
equity:conversion:$-€:€ €-100 ; generated-posting: equity:conversion:$-€:€ €-100
equity:conversion:$-€:$ $135.00 ; generated-posting: equity:conversion:$-€:$ $135.00
\f[R] \f[R]
.fi .fi
.PP .PP
The conversion account names can be changed with the conversion account The equity account names will be \[dq]equity:conversion:A-B:A\[dq] and
type declaration. \[dq]equity:conversion:A-B:B\[dq] where A is the alphabetically first
commodity symbol.
You can customise the \[dq]equity:conversion\[dq] part by declaring an
account with the \f[V]V\f[R]/\f[V]Conversion\f[R] account type.
.SS Combining costs and equity conversion postings
.PP .PP
--infer-equity is useful when when transactions have been recorded using Finally, you can use both the \[at]/\[at]\[at] cost notation and equity
cost notation, to help preserve the accounting equation and balance postings at the same time.
reports\[aq] zero total, or to produce more conventional journal entries This in theory gives the best of all worlds - preserving the accounting
for sharing with non-PTA-users. equation, revealing the per-unit cost basis, and providing more
.SS Inferring cost from equity postings flexibility in how you write the entry:
.PP .PP
The reverse operation is possible using \f[V]--infer-costs\f[R], which \f[B]Variant 5\f[R]
detects transactions written with equity conversion postings and adds
cost notation to them:
.IP .IP
.nf .nf
\f[C] \f[C]
2022-01-01 2022-01-01 one hundred euros purchased at $1.35 each
assets:dollars $-135 assets:dollars $-135
equity:conversion $135 equity:conversion $135
equity:conversion €-100 equity:conversion €-100
assets:euros €100 assets:euros €100 \[at] $1.35
\f[R] \f[R]
.fi .fi
.PP
All the other variants above can (usually) be rewritten to this final
form with:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger print --infer-costs $ hledger print -x --infer-costs --infer-equity
2022-01-01
assets:dollars $-135 \[at]\[at] €100
equity:conversion $135
equity:conversion €-100
assets:euros €100
\f[R] \f[R]
.fi .fi
.PP .PP
--infer-costs is useful when combined with -B/--cost, allowing cost Downsides:
reporting even when transactions have been recorded using equity .IP \[bu] 2
postings: This was added in hledger-1.29 and is still somewhat experimental.
.IP \[bu] 2
The precise format of the journal entry becomes more important.
If hledger can\[aq]t detect and match up the cost and equity postings,
it will give a transaction balancing error.
.IP \[bu] 2
The add command does not yet accept this kind of entry (#2056).
.IP \[bu] 2
This is the most verbose form.
.SS Requirements for detecting equity conversion postings
.PP
\f[V]--infer-costs\f[R] has certain requirements (unlike
\f[V]--infer-equity\f[R], which always works).
It will infer costs only in transactions with:
.IP \[bu] 2
Two non-equity postings, in different commodities.
Their order is significant: the cost will be added to the first of them.
.IP \[bu] 2
Two postings to equity conversion accounts, next to one another, which
balance the two non-equity postings.
This balancing is checked to the same precision (number of decimal
places) used in the conversion posting\[aq]s amount.
Equity conversion accounts are:
.RS 2
.IP \[bu] 2
any accounts declared with account type
\f[V]V\f[R]/\f[V]Conversion\f[R], or their subaccounts
.IP \[bu] 2
otherwise, accounts named \f[V]equity:conversion\f[R],
\f[V]equity:trade\f[R], or \f[V]equity:trading\f[R], or their
subaccounts.
.RE
.PP
And multiple such four-posting groups can coexist within a single
transaction.
When \f[V]--infer-costs\f[R] fails, it does not infer a cost in that
transaction, and does not raise an error (ie, it infers costs where it
can).
.PP
Reading variant 5 journal entries, combining cost notation and equity
postings, has all the same requirements.
When reading such an entry fails, hledger raises an \[dq]unbalanced
transaction\[dq] error.
.SS Infer cost and equity by default ?
.PP
Should \f[V]--infer-costs\f[R] and \f[V]--infer-equity\f[R] be enabled
by default ?
Try using them always, eg with a shell alias:
.IP .IP
.nf .nf
\f[C] \f[C]
$ hledger print --infer-costs -B alias h=\[dq]hledger --infer-equity --infer-costs\[dq]
2009-01-01
assets:dollars €-100
assets:euros €100
\f[R] \f[R]
.fi .fi
.PP .PP
Notes: and let us know what problems you find.
.PP .PP
For \f[V]--infer-costs\f[R] to work, an exchange must consist of four .SH Value reporting
postings:
.IP "1." 3
two non-equity postings
.IP "2." 3
two equity postings, next to one another
.IP "3." 3
the equity accounts must be declared, with account type
\f[V]V\f[R]/\f[V]Conversion\f[R] (or if they are not declared, they must
be named \f[V]equity:conversion\f[R], \f[V]equity:trade\f[R],
\f[V]equity:trading\f[R] or subaccounts of these)
.IP "4." 3
the equity postings\[aq] amounts must exactly match the non-equity
postings\[aq] amounts.
.PP
Multiple such exchanges can coexist within a single transaction.
.PP
When inferring cost, the order of postings matters: the cost is added to
the first of the non-equity postings involved in the exchange, in the
commodity of the last non-equity posting involved in the exchange.
If you don\[aq]t want to write your postings in the required order, you
can use explicit cost notation instead.
.PP
--infer-equity and --infer-costs can be used together, if you have a
mixture of both notations in your journal.
.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[V]hledger bal -B --infer-costs\f[R]
.IP "2." 3
Always run hledger with both flags enabled.
Eg: \f[V]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
.nf
\f[C]
2021-01-01
assets:cash -100 EUR
assets:cash 120 USD
\f[R]
.fi
.PP
hledger will assume this transaction is balanced, inferring that the
conversion rate must be 1 EUR = 1.20 USD.
You can see the inferred rate by using \f[V]hledger print -x\f[R].
.PP
Pro:
.IP \[bu] 2
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
.IP \[bu] 2
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[V]hledger check commodities\f[R].
.PP
You can prevent implicit conversions entirely, by using
\f[V]hledger check balancednoautoconversion\f[R], or
\f[V]-s/--strict\f[R].
.SS Conversion with explicit cost
.PP
You can add the conversion rate using \[at] notation:
.IP
.nf
\f[C]
2021-01-01
assets:cash -100 EUR \[at] 1.20 USD
assets:cash 120 USD
\f[R]
.fi
.PP
Now hledger will check that 100 * 1.20 = 120, and would report an error
otherwise.
.PP
Pro:
.IP \[bu] 2
Still concise
.IP \[bu] 2
Makes the conversion rate clear
.IP \[bu] 2
Provides more error checking
.PP
Con:
.IP \[bu] 2
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
appears.
This violates the accounting equation (A+L+E=0), and prevents reports
like \f[V]balancesheetequity\f[R] from showing a zero total.
.PP
The proper way to make it balance is to add a balancing posting for each
commodity, using an equity account:
.IP
.nf
\f[C]
2021-01-01
assets:cash -100 EUR
equity:conversion 100 EUR
equity:conversion -120 USD
assets:cash 120 USD
\f[R]
.fi
.PP
Pro:
.IP \[bu] 2
Preserves the accounting equation
.IP \[bu] 2
Keeps track of conversions and related gains/losses in one place
.IP \[bu] 2
Standard, works in any double entry accounting system
.PP
Con:
.IP \[bu] 2
More verbose
.IP \[bu] 2
Conversion rate is not obvious
.IP \[bu] 2
Cost reporting requires adding the --infer-costs flag
.SS Conversion with equity postings and explicit cost
.PP
Here both equity postings and \[at] notation are used together.
.IP
.nf
\f[C]
2021-01-01
assets:cash -100 EUR \[at] 1.20 USD
equity:conversion 100 EUR
equity:conversion -120 USD
assets:cash 120 USD
\f[R]
.fi
.PP
Pro:
.IP \[bu] 2
Preserves the accounting equation
.IP \[bu] 2
Keeps track of conversions and related gains/losses in one place
.IP \[bu] 2
Makes the conversion rate clear
.IP \[bu] 2
Provides more error checking
.PP
Con:
.IP \[bu] 2
Most verbose
.IP \[bu] 2
Not compatible with ledger
.SS Cost tips
.IP \[bu] 2
Recording the cost/conversion rate explicitly is good because it makes
that clear and helps detect errors.
.IP \[bu] 2
Recording equity postings is good because it is correct bookkeeping and
preserves the accounting equation.
.IP \[bu] 2
Combining these is possible.
.IP \[bu] 2
When you want to see the cost (or sale proceeds) of things, use
\f[V]-B\f[R] (short form of \f[V]--cost\f[R]).
.IP \[bu] 2
If you use conversion postings without cost notation, add
\f[V]--infer-costs\f[R] also.
.IP \[bu] 2
If you use cost notation without conversion postings, and you want to
see a balanced balance sheet or print correct journal entries, use
\f[V]--infer-equity\f[R].
.IP \[bu] 2
Conversion to cost is performed before valuation (described next).
.SH Valuation
.PP .PP
Instead of reporting amounts in their original commodity, hledger can Instead of reporting amounts in their original commodity, hledger can
convert them to cost/sale amount (using the conversion rate recorded in convert them to cost/sale amount (using the conversion rate recorded in
@ -7394,8 +7268,9 @@ If both occur on the same day, the P directive takes precedence.
.PP .PP
There is a downside: value reports can sometimes be affected in There is a downside: value reports can sometimes be affected in
confusing/undesired ways by your journal entries. confusing/undesired ways by your journal entries.
If this happens to you, read all of this Valuation section carefully, If this happens to you, read all of this Value reporting section
and try adding \f[V]--debug\f[R] or \f[V]--debug=2\f[R] to troubleshoot. carefully, and try adding \f[V]--debug\f[R] or \f[V]--debug=2\f[R] to
troubleshoot.
.PP .PP
\f[V]--infer-market-prices\f[R] can infer market prices from: \f[V]--infer-market-prices\f[R] can infer market prices from:
.IP \[bu] 2 .IP \[bu] 2
@ -9038,7 +8913,7 @@ are independent options which can both be used at once)
.IP \[bu] 2 .IP \[bu] 2
\f[V]-X COMM/--exchange COMM\f[R] : like --value=end,COMM \f[V]-X COMM/--exchange COMM\f[R] : like --value=end,COMM
.PP .PP
See Cost reporting and Valuation for more about these. See Cost reporting and Value reporting for more about these.
.SS Combining balance report types .SS Combining balance report types
.PP .PP
Most combinations of these options should produce reasonable reports, Most combinations of these options should produce reasonable reports,
@ -9501,7 +9376,7 @@ throughout the report period
possibly restricted by a period specified in the periodic transaction possibly restricted by a period specified in the periodic transaction
rule. rule.
.RE .RE
.SS Data layout .SS Balance report layout
.PP .PP
The \f[V]--layout\f[R] option affects how balance reports show The \f[V]--layout\f[R] option affects how balance reports show
multi-commodity amounts and commodity symbols, which can improve multi-commodity amounts and commodity symbols, which can improve
@ -9698,6 +9573,12 @@ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=
.fi .fi
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
Note: bare layout will sometimes display an extra row for the no-symbol
commodity, because of zero amounts (hledger treats zeroes as
commodity-less, usually).
This can break \f[V]hledger-bar\f[R] confusingly (workaround: add a
\f[V]cur:\f[R] query to exclude the no-symbol row).
.IP \[bu] 2
Tidy layout produces normalised \[dq]tidy data\[dq], where every Tidy layout produces normalised \[dq]tidy data\[dq], where every
variable has its own column and each row represents a single data point. variable has its own column and each row represents a single data point.
See See
@ -9984,9 +9865,10 @@ commands, including \f[V]check\f[R]:
\f[B]parseable\f[R] - data files are well-formed and can be successfully \f[B]parseable\f[R] - data files are well-formed and can be successfully
parsed parsed
.IP \[bu] 2 .IP \[bu] 2
\f[B]balancedwithautoconversion\f[R] - all transactions are balanced, \f[B]autobalanced\f[R] - all transactions are balanced, after converting
inferring missing amounts where necessary, and possibly converting to cost.
commodities using costs or automatically-inferred costs Missing amounts and missing costs are inferred automatically where
possible.
.IP \[bu] 2 .IP \[bu] 2
\f[B]assertions\f[R] - all balance assertions in the journal are \f[B]assertions\f[R] - all balance assertions in the journal are
passing. passing.
@ -10004,8 +9886,9 @@ declared
.IP \[bu] 2 .IP \[bu] 2
\f[B]commodities\f[R] - all commodity symbols used have been declared \f[B]commodities\f[R] - all commodity symbols used have been declared
.IP \[bu] 2 .IP \[bu] 2
\f[B]balancednoautoconversion\f[R] - transactions are balanced, possibly \f[B]balanced\f[R] - all transactions are balanced after converting to
using explicit costs but not inferred ones cost, without inferring missing costs.
If conversion costs are required, they must be explicit.
.SS Other checks .SS Other checks
.PP .PP
These checks can be run only by giving their names as arguments to These checks can be run only by giving their names as arguments to
@ -10019,7 +9902,7 @@ file
\f[B]payees\f[R] - all payees used by transactions have been declared \f[B]payees\f[R] - all payees used by transactions have been declared
.IP \[bu] 2 .IP \[bu] 2
\f[B]recentassertions\f[R] - all accounts with balance assertions have a \f[B]recentassertions\f[R] - all accounts with balance assertions have a
balance assertion no more than 7 days before their latest posting balance assertion within 7 days of their latest posting
.IP \[bu] 2 .IP \[bu] 2
\f[B]tags\f[R] - all tags used by transactions have been declared \f[B]tags\f[R] - all tags used by transactions have been declared
.IP \[bu] 2 .IP \[bu] 2
@ -10040,17 +9923,17 @@ See: Cookbook -> Scripting.
.SS More about specific checks .SS More about specific checks
.PP .PP
\f[V]hledger check recentassertions\f[R] will complain if any \f[V]hledger check recentassertions\f[R] will complain if any
balance-asserted account does not have a balance assertion within 7 days balance-asserted account has postings more than 7 days after its latest
before its latest posting. balance assertion.
This aims to prevent the situation where you are regularly updating your This aims to prevent the situation where you are regularly updating your
journal, but forgetting to check your balances against the real world, journal, but forgetting to check your balances against the real world,
then one day must dig back through months of data to find an error. then one day must dig back through months of data to find an error.
It assumes that adding a balance assertion requires/reminds you to check It assumes that adding a balance assertion requires/reminds you to check
the real-world balance. the real-world balance.
That may not be true if you auto-generate balance assertions from bank (That may not be true if you auto-generate balance assertions from bank
data; in that case, I recommend to import transactions uncleared, then data; in that case, I recommend to import transactions uncleared, and
use the manual-review-and-mark-cleared phase as a reminder to check the when you manually review and clear them, also check the latest assertion
latest assertions against real-world balances. against the real-world balance.)
.SS close .SS close
.PP .PP
(equity) (equity)
@ -10541,6 +10424,8 @@ up\[dq] to a certain date.
.PP .PP
Note deduplication (and updating of state files) can also be done by Note deduplication (and updating of state files) can also be done by
\f[V]print --new\f[R], but this is less often used. \f[V]print --new\f[R], but this is less often used.
.PP
Related: CSV > Working with CSV > Deduplicating, importing.
.SS Import testing .SS Import testing
.PP .PP
With \f[V]--dry-run\f[R], the transactions that will be imported are With \f[V]--dry-run\f[R], the transactions that will be imported are
@ -10763,8 +10648,8 @@ $ hledger print assets:cash | hledger -f- -I reg expenses:food
There are some situations where print\[aq]s output can become There are some situations where print\[aq]s output can become
unparseable: unparseable:
.IP \[bu] 2 .IP \[bu] 2
Valuation affects posting amounts but not balance assertion or balance Value reporting affects posting amounts but not balance assertion or
assignment amounts, potentially causing those to fail. balance assignment amounts, potentially causing those to fail.
.IP \[bu] 2 .IP \[bu] 2
Auto postings can generate postings with too many missing amounts. Auto postings can generate postings with too many missing amounts.
.IP \[bu] 2 .IP \[bu] 2

2012
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

689
hledger/hledger.txt
View File

@ -1,8 +1,6 @@
HLEDGER(1) hledger User Manuals HLEDGER(1) HLEDGER(1) hledger User Manuals HLEDGER(1)
NAME NAME
hledger - robust, friendly plain text accounting (CLI version) hledger - robust, friendly plain text accounting (CLI version)
@ -575,7 +573,8 @@ Output
aregister Y Y Y Y aregister Y Y Y Y
balance Y 1 Y 1 Y 1,2 Y balance Y 1 Y 1 Y 1,2 Y
balancesheet Y 1 Y 1 Y 1 Y balancesheet Y 1 Y 1 Y 1 Y
balancesheetequity Y 1 Y 1 Y 1 Y balancesheete- Y 1 Y 1 Y 1 Y
quity
cashflow Y 1 Y 1 Y 1 Y cashflow Y 1 Y 1 Y 1 Y
incomestatement Y 1 Y 1 Y 1 Y incomestatement Y 1 Y 1 Y 1 Y
print Y Y Y Y print Y Y Y Y
@ -1043,9 +1042,9 @@ Journal
balance the transaction. balance the transaction.
Be sure to note the unusual two-space delimiter between account name Be sure to note the unusual two-space delimiter between account name
and amount. This makes it easy to write account names containing spa- and amount. This makes it easy to write account names containing
ces. But if you accidentally leave only one space (or tab) before the spaces. But if you accidentally leave only one space (or tab) before
amount, the amount will be considered part of the account name. the amount, the amount will be considered part of the account name.
Account names Account names
Accounts are the main way of categorising things in hledger. As in Accounts are the main way of categorising things in hledger. As in
@ -1301,7 +1300,7 @@ Journal
assets:dollars $-135 ; for $135 assets:dollars $-135 ; for $135
Amounts can be converted to cost at report time using the -B/--cost Amounts can be converted to cost at report time using the -B/--cost
flag; this is discussed more in the COST REPORTING section. flag; this is discussed more in the Cost reporting section.
Note that the cost normally should be a positive amount, though it's Note that the cost normally should be a positive amount, though it's
not required to be. This can be a little confusing, see discussion at not required to be. This can be a little confusing, see discussion at
@ -1654,14 +1653,6 @@ Journal
rent file or end aliases. Command line equivalent: --alias rent file or end aliases. Command line equivalent: --alias
com- Ignores part of the journal file, until end of current file or Y com- Ignores part of the journal file, until end of current file or Y
ment end comment. ment end comment.
com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N
mod- all amounts in all files 2. the decimal mark for parsing mod- all amounts in all files 2. the decimal mark for parsing
ity amounts of this commodity, in the following entries until end of ity amounts of this commodity, in the following entries until end of
@ -1849,8 +1840,8 @@ Journal
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 COST RE- o V or Conversion (a subtype of Equity, for conversions (see Cost re-
PORTING).) porting).)
Here is a typical set of account type declarations: Here is a typical set of account type declarations:
@ -2236,7 +2227,7 @@ Journal
P 2010-01-01 $1.40 P 2010-01-01 $1.40
The -V, -X and --value flags use these market prices to show amount The -V, -X and --value flags use these market prices to show amount
values in another commodity. See Valuation. values in another commodity. See Value reporting.
payee directive payee directive
payee PAYEE NAME payee PAYEE NAME
@ -2535,6 +2526,11 @@ Journal
2019-01-01 2019-01-01
(a) $1 @ 2 = $1 @ 2 (a) $1 @ 2 = $1 @ 2
Balance assignments and multiple files
Balance assignments handle multiple files like balance assertions.
They see balance from other files previously included from the current
file, but not from previous sibling or parent files.
Bracketed posting dates Bracketed posting dates
For setting posting dates and secondary posting dates, Ledger's brack- For setting posting dates and secondary posting dates, Ledger's brack-
eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in
@ -2611,8 +2607,8 @@ Journal
Account aliases, if any, are applied after the parent account is Account aliases, if any, are applied after the parent account is
prepended. prepended.
Downsides: this can make your financial data less explicit, less porta- Downsides: this can make your financial data less explicit, less
ble, and less trustworthy in an audit. portable, and less trustworthy in an audit.
Y directive Y directive
Y YEAR Y YEAR
@ -2920,10 +2916,10 @@ CSV
newest-first newest-first
hledger tries to ensure that the generated transactions will be ordered hledger tries to ensure that the generated transactions will be ordered
chronologically, including intra-day transactions. Usually it can chronologically, including same-day transactions. Usually it can auto-
auto-detect how the CSV records are ordered. But if it encounters CSV detect how the CSV records are ordered. But if it encounters CSV where
where all records are on the same date, it assumes that the records are all records are on the same date, it assumes that the records are old-
oldest first. If in fact the CSV's records are normally newest first, est first. If in fact the CSV's records are normally newest first,
like: like:
2022-10-01, txn 3... 2022-10-01, txn 3...
@ -2937,18 +2933,16 @@ CSV
newest-first newest-first
intra-day-reversed intra-day-reversed
CSV records for each day are sometimes ordered in reverse compared to If CSV records within a single day are ordered opposite to the overall
the overall date order. Eg, here dates are newest first, but the record order, you can add the intra-day-reversed rule to improve the
transactions on each date are oldest first: order of journal entries. Eg, here the overall record order is newest
first, but same-day records are oldest first:
2022-10-02, txn 3... 2022-10-02, txn 3...
2022-10-02, txn 4... 2022-10-02, txn 4...
2022-10-01, txn 1... 2022-10-01, txn 1...
2022-10-01, txn 2... 2022-10-01, txn 2...
In this situation, add the intra-day-reversed rule, and hledger will
compensate, improving the order of transactions.
# transactions within each day are reversed with respect to the overall date order # transactions within each day are reversed with respect to the overall date order
intra-day-reversed intra-day-reversed
@ -3108,76 +3102,59 @@ CSV
or "income:unknown"). or "income:unknown").
amount field amount field
Amount setting can get a bit complex. Assigning to amount is suffi- There are several ways to set posting amounts from CSV, useful in dif-
cient for simple transactions, but there are four field name variants ferent situations.
you can use for different situations:
o amountN sets a specific posting's amount from one CSV field or arbi- 1. amount is the oldest and simplest. Assigning to this sets the
trary value. amount of the first and second postings. In the second posting, the
Assigning to amountN sets the amount of the Nth posting - and also amount will be negated; also, if it has a cost attached, it will be
causes that posting to be generated. N is most often 1 or 2 but can go converted to cost.
up to 99, potentially generating a 99-posting transaction. (Posting
numbers don't have to be consecutive; higher posting numbers can some-
times be useful with conditional rules, to ensure a certain ordering of
postings.)
o amountN-in/-out sets a specific posting's amount from two CSV fields. 2. amount-in and amount-out work exactly like the above, but should be
When the amount is provided as two CSV fields - "Debit"/"Credit", "De- used when the CSV has two amount fields (such as "Debit" and
posit"/"Withdrawal", "Money In"/"Money Out" or similar - assign those "Credit", or "Inflow" and "Outflow"). Whichever field has a non-
fields to amountN-in and amountN-out respectively (or possibly the zero value will be used as the amount of the first and second post-
other way round, depending on signs). This will set the Nth posting's ings. Here are some tips to avoid confusion:
amount to whichever of the two CSV field values is non-zero. Some
notes:
o Don't mix amountN and amountN-in/-out. When you have one CSV o It's not "amount-in for posting 1 and amount-out for posting 2",
amount field, use amountN. When you have two CSV amount fields, it is "extract a single amount from the amount-in or amount-out
use amountN-in/amountN-out. field, and use that for posting 1 and (negated) for posting 2".
o amountN-in and amountN-out are always used together, as a pair. o Don't use both amount and amount-in/amount-out in the same rules
Assign to both of them. file; choose based on whether the amount is in a single CSV field
or spread across two fields.
o They do not generate two separate postings; rather, they generate o In each record, at most one of the two CSV fields should contain
the Nth posting's single amount, from the value found in one or a non-zero amount; the other field must contain a zero or noth-
other of the two CSV fields. ing.
o In each record, at least one of the two CSV fields must contain a o hledger assumes both CSV fields contain unsigned numbers, and it
zero amount or be empty. automatically negates the amount-out values.
o hledger assumes the two CSV fields contain unsigned numbers, and it o If the data doesn't fit these requirements, you'll probably need
will automatically negate the -out amount. an if rule (see below).
o This variant can be convenient, but it doesn't handle every two- 3. amountN (where N is a number from 1 to 99) sets the amount of only a
amount-field situation; if you need more flexibility, use an if single posting: the Nth posting in the transaction. You'll usually
rule (see "Setting amounts" below). need at least two such assignments to make a balanced transaction.
You can also generate more than two postings, to represent more com-
plex transactions. The posting numbers don't have to be consecu-
tive; with if rules, higher posting numbers can be useful to ensure
a certain order of postings.
The other two variants are older and considered legacy syntax, but can 4. amountN-in and amountN-out work exactly like the above, but should
still be convenient sometimes: be used when the CSV has two amount fields. This is analogous to
amount-in and amount-out, and those tips also apply here.
o amount sets posting 1 and 2's amounts from one CSV field or value. 5. Remember that a fields list can also do assignments. So in a fields
Assigning to amount, with no posting number, list if you name a CSV field "amount", that counts as assigning to
amount. (If you don't want that, call it something else in the
fields list, like "amount_".)
o sets posting 1's amount (like amount1) 6. The above don't handle every situation; if you need more flexibil-
ity, use an if rule to set amounts conditionally. See "Working with
o sets posting 2's amount to the same amount but with opposite sign; CSV > Setting amounts" below for more on this and on amount-setting
and also converts it to cost if it has a cost price generally.
o can be overridden by amount1 and/or amount2 assignments. (This
helps with incremental migration of old rules files to the newer
syntax.)
o amount-in/-out sets posting 1 and 2's amounts from two CSV fields.
Assigning amount-in and amount-out, with no posting numbers, to two CSV
fields reads whichever of the two values is non-zero as the amount, and
then sets the first two posting amounts as above.
We recommend using only one of these variants within a rules file,
rather than mixing them. And remember that a fields list can also do
assignments, so eg naming a CSV field "amount" counts as an assignment
to amount; if you don't want that, call it something else, like
"amount_".
In addition to this section, please see also the tips beginning at
"Working with CSV > Setting amounts" below.
currency field currency field
currency sets a currency symbol, to be prepended to all postings' currency sets a currency symbol, to be prepended to all postings'
@ -3496,8 +3473,8 @@ CSV
o https://plaintextaccounting.org -> data import/conversion o https://plaintextaccounting.org -> data import/conversion
Setting amounts Setting amounts
Continuing from amount field above, here are more tips on handling var- Continuing from amount field above, here are more tips for amount-set-
ious amount-setting situations: ting:
1. If the amount is in a single CSV field: 1. If the amount is in a single CSV field:
a. If its sign indicates direction of flow: a. If its sign indicates direction of flow:
@ -3513,18 +3490,18 @@ CSV
if %Type deposit if %Type deposit
amount1 %Amount amount1 %Amount
2. If the amount is in one of two CSV fields (eg Debit and Credit): 2. If the amount is in two CSV fields (such as Debit and Credit, or In
and Out):
a. If both fields are unsigned: a. If both fields are unsigned:
Assign the fields to amountN-in and amountN-out. This sets posting Assign one field to amountN-in and the other to amountN-out.
N's amount to whichever of these has a non-zero value. If it's the hledger will automatically negate the "out" field, and will use
-out value, the amount will be negated. whichever field value is non-zero as posting N's amount.
b. If either field is signed: b. If either field is signed:
Use a conditional rule to flip the sign when needed. Eg below, the You will probably need to override hledger's sign for one or the
-out value already has a minus sign so we undo hledger's automatic other field, as in the following example:
negating by negating once more (but only if the field is non-empty,
so that we don't leave a minus sign by itself):
# Negate the -out value, but only if it is not empty:
fields date, description, amount1-in, amount1-out fields date, description, amount1-in, amount1-out
if %amount1-out [1-9] if %amount1-out [1-9]
amount1-out -%amount1-out amount1-out -%amount1-out
@ -4244,9 +4221,6 @@ Time periods
october, oct start of month in current year october, oct start of month in current year
yesterday, today, tomor- -1, 0, 1 days from today yesterday, today, tomor- -1, 0, 1 days from today
row row
last/this/next -1, 0, 1 periods from the current period last/this/next -1, 0, 1 periods from the current period
day/week/month/quar- day/week/month/quar-
ter/year ter/year
@ -4326,9 +4300,9 @@ Time periods
-p "from 2009/1/1 to 2009/4/1" -p "from 2009/1/1 to 2009/4/1"
Several keywords like "from" and "to" are supported for readability; Several keywords like "from" and "to" are supported for readability;
these are optional. "to" can also be written as ".." or "-". The spa- these are optional. "to" can also be written as ".." or "-". The
ces are also optional, as long as you don't run two dates together. So spaces are also optional, as long as you don't run two dates together.
the following are equivalent to the above: So the following are equivalent to the above:
-p "2009/1/1 2009/4/1" -p "2009/1/1 2009/4/1"
-p2009/1/1to2009/4/1 -p2009/1/1to2009/4/1
@ -4925,89 +4899,132 @@ Budgeting
See also: Budgeting and Forecasting. See also: Budgeting and Forecasting.
Cost reporting Cost reporting
This section is about recording the cost of things, in transactions In some transactions - for example a currency conversion, or a purchase
where one commodity is exchanged for another. Eg an exchange of cur- or sale of stock - one commodity is exchanged for another. In these
rency, or a stock purchase or sale. First, a quick glossary: transactions there is a conversion rate, also called the cost (when
buying) or selling price (when selling). In hledger docs we just say
"cost", for convenience; feel free to mentally translate to "conversion
rate" or "selling price" if helpful.
o Conversion - an exchange of one currency or commodity for another. Recording costs
Eg a foreign currency exchange, or a purchase or sale of stock or We'll explore several ways of recording transactions involving costs.
cryptocurrency. These are also summarised at hledger Cookbook > Cost notation.
o Conversion transaction - a transaction involving one or more conver- Costs can be recorded explicitly in the journal, using the @ UNITCOST
sions. or @@ TOTALCOST notation described in Journal > Costs:
o Conversion rate - the cost per unit of one commodity in the other, ie Variant 1
the exchange rate.
2022-01-01
o Cost - how much of one commodity was paid to acquire the other. And assets:dollars $-135
more generally, in hledger docs: the amount exchanged in the "sec- assets:euros 100 @ $1.35 ; $1.35 per euro (unit cost)
ondary" commodity (usually your base currency), whether in a purchase
or a sale, and whether expressed per unit or in total. Also, the Variant 2
"@/@@ PRICE" notation used to represent this.
2022-01-01
-B: Convert to cost assets:dollars $-135
As discussed in JOURNAL > Costs, when recording a transaction you can assets:euros 100 @@ $135 ; $135 total cost
also record the amount's cost in another commodity, by adding @ UNIT-
PRICE or @@ TOTALPRICE. Typically, writing the unit cost (variant 1) is preferable; it can be
more effort, requiring more attention to decimal digits; but it reveals
Then you can see a report with amounts converted to cost, by adding the the per-unit cost basis, and makes stock sales easier.
-B/--cost flag. (Mnemonic: "B" from "cost Basis", as in Ledger). Eg:
Costs can also be left implicit, and hledger will infer the cost that
is consistent with a balanced transaction:
Variant 3
2022-01-01 2022-01-01
assets:dollars $-135 ; 135 dollars is exchanged for..
assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each
$ hledger bal -N
$-135 assets:dollars
100 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 cost is inferred: the
inferred price will be in the commodity of the last amount. So if ex-
ample 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 100 ; for 100 euros
$ hledger bal -N -B
-100 assets:dollars # <- the dollars' selling price
100 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 assets:dollars $-135
equity:conversion $135
equity:conversion -100
assets:euros 100 assets:euros 100
This style is more correct, but it's also more verbose and makes cost Here, hledger will attach a @@ 100 cost to the first amount (you can
reporting more difficult for PTA tools. see it with hledger print -x). This form looks convenient, but there
are downsides:
Happily, current hledger can read either notation, or convert one to o It sacrifices some error checking. For example, if you accidentally
the other when needed, so you can use the one you prefer. wrote 10 instead of 100, hledger would not be able to detect the mis-
take.
You can even use cost notation and equivalent conversion postings at o It is sensitive to the order of postings - if they were reversed, a
the same time, for clarity. hledger will ignore the redundancy. But different entry would be inferred and reports would be different.
be sure the cost and conversion posting amounts match, or you'll see a
not-so-clear transaction balancing error message.
Inferring equity postings from cost o The per-unit cost basis is not easy to read.
With --infer-equity, hledger detects transactions written with PTA cost
notation and adds equity conversion postings to them: So generally this kind of entry is not recommended. You can make sure
you have none of these by using -s (strict mode), or by running hledger
check balanced.
Reporting at cost
Now when you add the -B/--cost flag to reports ("B" is from Ledger's
-B/--basis/--cost flag), any amounts which have been annotated with
costs will be converted to their cost's commodity (in the report out-
put). Ie they will be displayed "at cost" or "at sale price".
Some things to note:
o Costs are attached to specific posting amounts in specific transac-
tions, and once recorded they do not change. This contrasts with
market prices, which are ambient and fluctuating.
o Conversion to cost is performed before conversion to market value
(described below).
Equity conversion postings
There is a problem with the entries above - they are not conventional
Double Entry Bookkeeping (DEB) notation, and because of the "magical"
transformation of one commodity into another, they cause an imbalance
in the Accounting Equation. This shows up as a non-zero grand total in
balance reports like hledger bse.
For most hledger users, this doesn't matter in practice and can safely
be ignored ! But if you'd like to learn more, keep reading.
Conventional DEB uses an extra pair of equity postings to balance the
transaction. Of course you can do this in hledger as well:
Variant 4
2022-01-01
assets:dollars $-135
assets:euros 100
equity:conversion $135
equity:conversion -100
Now the transaction is perfectly balanced according to standard DEB,
and hledger bse's total will not be disrupted.
And, hledger can still infer the cost for cost reporting, but it's not
done by default - you must add the --infer-costs flag like so:
$ hledger print --infer-costs
2022-01-01 one hundred euros purchased at $1.35 each
assets:dollars $-135 @@ 100
assets:euros 100
equity:conversion $135
equity:conversion -100
$ hledger bal --infer-costs -B
-100 assets:dollars
100 assets:euros
--------------------
0
Here are some downsides of this kind of entry:
o The per-unit cost basis is not easy to read.
o Instead of -B you must remember to type -B --infer-costs.
o --infer-costs works only where hledger can identify the two eq-
uity:conversion postings and match them up with the two non-equity
postings. So writing the journal entry in a particular format be-
comes more important. More on this below.
Inferring equity conversion postings
Can we go in the other direction ? Yes, if you have transactions writ-
ten with the @/@@ cost notation, hledger can infer the missing equity
postings, if you add the --infer-equity flag. Eg:
2022-01-01 2022-01-01
assets:dollars -$135 assets:dollars -$135
@ -5017,219 +5034,81 @@ Cost reporting
2022-01-01 2022-01-01
assets:dollars $-135 assets:dollars $-135
assets:euros 100 @ $1.35 assets:euros 100 @ $1.35
equity:conversion:$-: -100 ; generated-posting: equity:conversion:$-: -100
equity:conversion:$-:$ $135.00 ; generated-posting: equity:conversion:$-:$ $135.00
The conversion account names can be changed with the conversion account The equity account names will be "equity:conversion:A-B:A" and "eq-
type declaration. uity:conversion:A-B:B" where A is the alphabetically first commodity
symbol. You can customise the "equity:conversion" part by declaring an
account with the V/Conversion account type.
--infer-equity is useful when when transactions have been recorded us- Combining costs and equity conversion postings
ing cost notation, to help preserve the accounting equation and balance Finally, you can use both the @/@@ cost notation and equity postings at
reports' zero total, or to produce more conventional journal entries the same time. This in theory gives the best of all worlds - preserv-
for sharing with non-PTA-users. ing the accounting equation, revealing the per-unit cost basis, and
providing more flexibility in how you write the entry:
Inferring cost from equity postings Variant 5
The reverse operation is possible using --infer-costs, which detects
transactions written with equity conversion postings and adds cost no-
tation to them:
2022-01-01 2022-01-01 one hundred euros purchased at $1.35 each
assets:dollars $-135 assets:dollars $-135
equity:conversion $135 equity:conversion $135
equity:conversion -100 equity:conversion -100
assets:euros 100 assets:euros 100 @ $1.35
$ hledger print --infer-costs All the other variants above can (usually) be rewritten to this final
2022-01-01 form with:
assets:dollars $-135 @@ 100
equity:conversion $135
equity:conversion -100
assets:euros 100
--infer-costs is useful when combined with -B/--cost, allowing cost re- $ hledger print -x --infer-costs --infer-equity
porting even when transactions have been recorded using equity post-
ings:
$ hledger print --infer-costs -B Downsides:
2009-01-01
assets:dollars -100
assets:euros 100
Notes: o This was added in hledger-1.29 and is still somewhat experimental.
For --infer-costs to work, an exchange must consist of four postings: o The precise format of the journal entry becomes more important. If
hledger can't detect and match up the cost and equity postings, it
will give a transaction balancing error.
1. two non-equity postings o The add command does not yet accept this kind of entry (#2056).
2. two equity postings, next to one another o This is the most verbose form.
3. the equity accounts must be declared, with account type V/Conversion Requirements for detecting equity conversion postings
(or if they are not declared, they must be named equity:conversion, --infer-costs has certain requirements (unlike --infer-equity, which
equity:trade, equity:trading or subaccounts of these) always works). It will infer costs only in transactions with:
4. the equity postings' amounts must exactly match the non-equity post- o Two non-equity postings, in different commodities. Their order is
ings' amounts. significant: the cost will be added to the first of them.
Multiple such exchanges can coexist within a single transaction. o Two postings to equity conversion accounts, next to one another,
which balance the two non-equity postings. This balancing is checked
to the same precision (number of decimal places) used in the conver-
sion posting's amount. Equity conversion accounts are:
When inferring cost, the order of postings matters: the cost is added o any accounts declared with account type V/Conversion, or their sub-
to the first of the non-equity postings involved in the exchange, in accounts
the commodity of the last non-equity posting involved in the exchange.
If you don't want to write your postings in the required order, you can
use explicit cost notation instead.
--infer-equity and --infer-costs can be used together, if you have a o otherwise, accounts named equity:conversion, equity:trade, or eq-
mixture of both notations in your journal. uity:trading, or their subaccounts.
When to infer cost/equity And multiple such four-posting groups can coexist within a single
Inferring equity postings or costs is still fairly new, so not enabled transaction. When --infer-costs fails, it does not infer a cost in
by default. We're not sure yet if that should change. Here are two that transaction, and does not raise an error (ie, it infers costs
suggestions to try, experience reports welcome: where it can).
1. When you use -B, always use --infer-costs as well. Eg: hledger bal Reading variant 5 journal entries, combining cost notation and equity
-B --infer-costs postings, has all the same requirements. When reading such an entry
fails, hledger raises an "unbalanced transaction" error.
2. Always run hledger with both flags enabled. Eg: alias hl="hledger Infer cost and equity by default ?
--infer-equity --infer-costs" Should --infer-costs and --infer-equity be enabled by default ? Try
using them always, eg with a shell alias:
How to record conversions alias h="hledger --infer-equity --infer-costs"
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 and let us know what problems you find.
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 ac-
count:
2021-01-01 Value reporting
assets:cash -100 EUR
assets:cash 120 USD
hledger will assume this transaction is balanced, inferring that the
conversion rate must be 1 EUR = 1.20 USD. You can see the inferred
rate by using hledger print -x.
Pro:
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 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
balancednoautoconversion, or -s/--strict.
Conversion with explicit cost
You can add the conversion rate using @ notation:
2021-01-01
assets:cash -100 EUR @ 1.20 USD
assets:cash 120 USD
Now hledger will check that 100 * 1.20 = 120, and would report an error
otherwise.
Pro:
o Still concise
o Makes the conversion rate clear
o Provides more error checking
Con:
o Disturbs the accounting equation, unless you add the --infer-equity
flag
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 ap-
pears. This violates the accounting equation (A+L+E=0), and prevents
reports like balancesheetequity from showing a zero total.
The proper way to make it balance is to add a balancing posting for
each commodity, using an equity account:
2021-01-01
assets:cash -100 EUR
equity:conversion 100 EUR
equity:conversion -120 USD
assets:cash 120 USD
Pro:
o Preserves the accounting equation
o Keeps track of conversions and related gains/losses in one place
o Standard, works in any double entry accounting system
Con:
o More verbose
o Conversion rate is not obvious
o Cost reporting requires adding the --infer-costs flag
Conversion with equity postings and explicit cost
Here both equity postings and @ notation are used together.
2021-01-01
assets:cash -100 EUR @ 1.20 USD
equity:conversion 100 EUR
equity:conversion -120 USD
assets:cash 120 USD
Pro:
o Preserves the accounting equation
o Keeps track of conversions and related gains/losses in one place
o Makes the conversion rate clear
o Provides more error checking
Con:
o Most verbose
o Not compatible with ledger
Cost tips
o Recording the cost/conversion rate explicitly is good because it
makes that clear and helps detect errors.
o Recording equity postings is good because it is correct bookkeeping
and preserves the accounting equation.
o Combining these is possible.
o When you want to see the cost (or sale proceeds) of things, use -B
(short form of --cost).
o If you use conversion postings without cost notation, add --infer-
costs also.
o If you use cost notation without conversion postings, and you want to
see a balanced balance sheet or print correct journal entries, use
--infer-equity.
o Conversion to cost is performed before valuation (described next).
Valuation
Instead of reporting amounts in their original commodity, hledger can Instead of reporting amounts in their original commodity, hledger can
convert them to cost/sale amount (using the conversion rate recorded in convert them to cost/sale amount (using the conversion rate recorded in
the transaction), and/or to market value (using some market price on a the transaction), and/or to market value (using some market price on a
@ -5301,8 +5180,8 @@ Valuation
There is a downside: value reports can sometimes be affected in confus- There is a downside: value reports can sometimes be affected in confus-
ing/undesired ways by your journal entries. If this happens to you, ing/undesired ways by your journal entries. If this happens to you,
read all of this Valuation section carefully, and try adding --debug or read all of this Value reporting section carefully, and try adding
--debug=2 to troubleshoot. --debug or --debug=2 to troubleshoot.
--infer-market-prices can infer market prices from: --infer-market-prices can infer market prices from:
@ -5626,12 +5505,6 @@ Valuation
posting cost value at re- value at posting value at re- value at posting cost value at re- value at posting value at re- value at
amounts port or date port or DATE/today amounts port or date port or DATE/today
journal end journal end journal end journal end
summary summarised value at pe- sum of postings value at pe- value at summary summarised value at pe- sum of postings value at pe- value at
posting cost riod ends in interval, val- riod ends DATE/today posting cost riod ends in interval, val- riod ends DATE/today
amounts ued at interval amounts ued at interval
@ -6328,11 +6201,11 @@ PART 4: COMMANDS
Sorting by amount Sorting by amount
With -S/--sort-amount, accounts with the largest (most positive) bal- With -S/--sort-amount, accounts with the largest (most positive) bal-
ances are shown first. Eg: hledger bal expenses -MAS shows your big- ances are shown first. Eg: hledger bal expenses -MAS shows your
gest averaged monthly expenses first. When more than one commodity is biggest averaged monthly expenses first. When more than one commodity
present, they will be sorted by the alphabetically earliest commodity is present, they will be sorted by the alphabetically earliest commod-
first, and then by subsequent commodities (if an amount is missing a ity first, and then by subsequent commodities (if an amount is missing
commodity, it is treated as 0). a commodity, it is treated as 0).
Revenues and liability balances are typically negative, however, so -S Revenues and liability balances are typically negative, however, so -S
shows these in reverse order. To work around this, you can add --in- shows these in reverse order. To work around this, you can add --in-
@ -6528,7 +6401,7 @@ PART 4: COMMANDS
o -X COMM/--exchange COMM : like --value=end,COMM o -X COMM/--exchange COMM : like --value=end,COMM
See Cost reporting and Valuation for more about these. See Cost reporting and Value reporting for more about these.
Combining balance report types Combining balance report types
Most combinations of these options should produce reasonable reports, Most combinations of these options should produce reasonable reports,
@ -6884,7 +6757,7 @@ PART 4: COMMANDS
o possibly restricted by a period specified in the periodic transac- o possibly restricted by a period specified in the periodic transac-
tion rule. tion rule.
Data layout Balance report layout
The --layout option affects how balance reports show multi-commodity The --layout option affects how balance reports show multi-commodity
amounts and commodity symbols, which can improve readability. It can amounts and commodity symbols, which can improve readability. It can
also normalise the data for easy consumption by other programs. It has also normalise the data for easy consumption by other programs. It has
@ -6992,6 +6865,11 @@ PART 4: COMMANDS
"total","VEA","36.00" "total","VEA","36.00"
"total","VHT","294.00" "total","VHT","294.00"
o Note: bare layout will sometimes display an extra row for the no-sym-
bol commodity, because of zero amounts (hledger treats zeroes as com-
modity-less, usually). This can break hledger-bar confusingly
(workaround: add a cur: query to exclude the no-symbol row).
o Tidy layout produces normalised "tidy data", where every variable has o Tidy layout produces normalised "tidy data", where every variable has
its own column and each row represents a single data point. See its own column and each row represents a single data point. See
https://cran.r-project.org/web/packages/tidyr/vignettes/tidy- https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-
@ -7217,9 +7095,9 @@ PART 4: COMMANDS
o parseable - data files are well-formed and can be successfully parsed o parseable - data files are well-formed and can be successfully parsed
o balancedwithautoconversion - all transactions are balanced, inferring o autobalanced - all transactions are balanced, after converting to
missing amounts where necessary, and possibly converting commodities cost. Missing amounts and missing costs are inferred automatically
using costs or automatically-inferred costs where possible.
o assertions - all balance assertions in the journal are passing. o assertions - all balance assertions in the journal are passing.
(This check can be disabled with -I/--ignore-assertions.) (This check can be disabled with -I/--ignore-assertions.)
@ -7233,8 +7111,9 @@ PART 4: COMMANDS
o commodities - all commodity symbols used have been declared o commodities - all commodity symbols used have been declared
o balancednoautoconversion - transactions are balanced, possibly using o balanced - all transactions are balanced after converting to cost,
explicit costs but not inferred ones without inferring missing costs. If conversion costs are required,
they must be explicit.
Other checks Other checks
These checks can be run only by giving their names as arguments to These checks can be run only by giving their names as arguments to
@ -7246,7 +7125,7 @@ PART 4: COMMANDS
o payees - all payees used by transactions have been declared o payees - all payees used by transactions have been declared
o recentassertions - all accounts with balance assertions have a bal- o recentassertions - all accounts with balance assertions have a bal-
ance assertion no more than 7 days before their latest posting ance assertion within 7 days of their latest posting
o tags - all tags used by transactions have been declared o tags - all tags used by transactions have been declared
@ -7267,16 +7146,16 @@ PART 4: COMMANDS
More about specific checks More about specific checks
hledger check recentassertions will complain if any balance-asserted hledger check recentassertions will complain if any balance-asserted
account does not have a balance assertion within 7 days before its lat- account has postings more than 7 days after its latest balance asser-
est posting. This aims to prevent the situation where you are regu- tion. This aims to prevent the situation where you are regularly up-
larly updating your journal, but forgetting to check your balances dating your journal, but forgetting to check your balances against the
against the real world, then one day must dig back through months of real world, then one day must dig back through months of data to find
data to find an error. It assumes that adding a balance assertion re- an error. It assumes that adding a balance assertion requires/reminds
quires/reminds you to check the real-world balance. That may not be you to check the real-world balance. (That may not be true if you
true if you auto-generate balance assertions from bank data; in that auto-generate balance assertions from bank data; in that case, I recom-
case, I recommend to import transactions uncleared, then use the man- mend to import transactions uncleared, and when you manually review and
ual-review-and-mark-cleared phase as a reminder to check the latest as- clear them, also check the latest assertion against the real-world bal-
sertions against real-world balances. ance.)
close close
(equity) (equity)
@ -7653,8 +7532,8 @@ PART 4: COMMANDS
ing a hidden ".latest" state file in the same directory. Eg when read- ing a hidden ".latest" state file in the same directory. Eg when read-
ing finance/bank.csv, it will look for and update the finance/.lat- ing finance/bank.csv, it will look for and update the finance/.lat-
est.bank.csv state file. The format is simple: one or more lines con- est.bank.csv state file. The format is simple: one or more lines con-
taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- taining the same ISO-format date (YYYY-MM-DD), meaning "I have
cessed transactions up to this date, and this many of them on that processed transactions up to this date, and this many of them on that
date." Normally you won't see or manipulate these state files yourself. date." Normally you won't see or manipulate these state files yourself.
But if needed, you can delete them to reset the state (making all But if needed, you can delete them to reset the state (making all
transactions "new"), or you can construct them to "catch up" to a cer- transactions "new"), or you can construct them to "catch up" to a cer-
@ -7663,6 +7542,8 @@ PART 4: COMMANDS
Note deduplication (and updating of state files) can also be done by Note deduplication (and updating of state files) can also be done by
print --new, but this is less often used. print --new, but this is less often used.
Related: CSV > Working with CSV > Deduplicating, importing.
Import testing Import testing
With --dry-run, the transactions that will be imported are printed to With --dry-run, the transactions that will be imported are printed to
the terminal, without updating your journal or state files. The output the terminal, without updating your journal or state files. The output
@ -7839,8 +7720,8 @@ PART 4: COMMANDS
There are some situations where print's output can become unparseable: There are some situations where print's output can become unparseable:
o Valuation affects posting amounts but not balance assertion or bal- o Value reporting affects posting amounts but not balance assertion or
ance assignment amounts, potentially causing those to fail. balance assignment amounts, potentially causing those to fail.
o Auto postings can generate postings with too many missing amounts. o Auto postings can generate postings with too many missing amounts.
@ -8426,8 +8307,8 @@ PART 5: COMMON TASKS
$ hledger help --help # find out more about the help command $ hledger help --help # find out more about the help command
To view manuals and introductory docs on the web, visit To view manuals and introductory docs on the web, visit
https://hledger.org. Chat and mail list support and discussion ar- https://hledger.org. Chat and mail list support and discussion
chives can be found at https://hledger.org/support. archives can be found at https://hledger.org/support.
Constructing command lines Constructing command lines
hledger has a flexible command line interface. We strive to keep it hledger has a flexible command line interface. We strive to keep it
@ -8896,6 +8777,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.30.99 August 2023 HLEDGER(1)
hledger-1.30.99 June 2023 HLEDGER(1)