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

;doc: transaction balancing: doc rewrite [#2402]

Browse Source
This commit is contained in:
Simon Michael 2025-06-11 08:09:28 -10:00
parent de4d637def
commit 868d535f3f
1 changed files with 15 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
hledger/hledger.m4.md
View File

@ -1836,27 +1836,25 @@ Especially when it involves costs, which often are not exact, because of repeati
In each commodity, hledger sums the transaction's posting amounts, after converting any with costs; In each commodity, hledger sums the transaction's posting amounts, after converting any with costs;
then it checks if that sum is zero, when rounded to a suitable number of decimal digits - which we call the *balancing precision*. then it checks if that sum is zero, when rounded to a suitable number of decimal digits - which we call the *balancing precision*.
Note, this changed with hledger 1.44. Since version 1.44, hledger infers balancing precision in each transaction from the amounts in that transaction's journal entry (like Ledger).
Older hledger versions reused display precision as balancing precision, which causes problems (over-reliance on commodity directives; fragility; see issue #2402). Ie, when checking the balance of commodity A, it uses the highest decimal precision seen for A in the journal entry (excluding cost amounts).
Since 1.44, hledger infers balancing precision in each transaction just from the amounts in that transaction. This makes transaction balancing robust; any imbalances must be visibly accounted for in the journal entry,
Eg when checking the balance of commodity A, it uses the highest decimal precision seen for A in that transaction's journal entry (excluding cost amounts). display precision can be freely increased with `-c`, and compatibility with Ledger and Beancount journals is good.
This makes transaction balancing more robust,
and improves our ability to read journals exported from Ledger and Beancount, and vice versa.
<!-- It requires that every imbalance must be accounted for visibly in the journal entry. -->
Unfortunately it can also reject some journal entries that worked with older hledger. Note that hledger versions before 1.44 worked differently: they allowed display precision to override the balancing precision.
This might also happen when converting CSV files. This masked small imbalances and caused fragility (see issue #2402).
If you hit this problem, here's how to fix it: As a result, some journal entries (or CSV rules) that worked with hledger <1.44, are now rejected with an "unbalanced transaction" error.
If you hit this problem, it's easy to fix:
- You can add `--txn-balancing=old` to the command, or to your `~/.hledger.conf` file. - You can restore the old behaviour, by adding `--txn-balancing=old` to the command or to your `~/.hledger.conf` file.
This restores the pre-1.44 behaviour, allowing you to keep using old journals unchanged. This lets you keep using old journals unchanged, though without the above benefits.
- Or you can fix the problem entries. - Or you can fix the problem entries (recommended).
There are three common ways; use whichever seems easiest/best: There are three ways, use whichever seems best:
1. make cost amounts more precise (eg adding more decimal digits) 1. make cost amounts more precise (add more/better decimal digits)
2. or make non-cost amounts less precise (removing unnecessary decimal digits that are raising the precision) 2. or make non-cost amounts less precise (remove unnecessary decimal digits that are raising the precision)
3. or add one amountless posting to absorb the imbalance (eg to "expenses:rounding"). 3. or add a posting to absorb the imbalance (eg "expenses:rounding". Remember that one posting may [omit the amount](#postings); that's convenient here.)
## Tags ## Tags