This is about hledger1.99 preview. Can be considered either a bug or a documentation issue.
After migrating to the new lot tracking syntax I was surprised to see hledger balance --gain show non-zero values for an investment account where the current balance was 0. The documentation describes the flag as "show the unrealised capital gain/loss, (the current valued balance minus each amount's original cost)" while in this case all the gains were already realised.
Old approach
Before migrating to lots, I used the same @ price for the buy and sale operations, compensating the change in value using an income:gains account. Like so:
P 2025-01-01 AAPL 0.5e
P 2025-02-01 AAPL 2e
P 2025-03-01 AAPL 5e
2025-01-01 | Stock purchase: AAPL
investments:stock:AAPL 200AAPL @ 0.5e
assets:checking -100e
2025-03-15 | Stock sale: AAPL
investments:stock:AAPL -200AAPL @ 0.5e
assets:checking 1000e
income:gains -900e
With such journal, balance --gain shows only the unrealised gain on the AAPL I held. After selling them, the value is 0.
$ hledger balance --gain bal -f oldstyle.journal -M -H aapl --transpose
Historical gain in 2025Q1, valued at period ends:
|| investments:stock:AAPL |
============++========================+========
2025-01-31 || 0 | 0
2025-02-28 || 300.0e | 300.0e
2025-03-31 || 0 | 0
New approach
To adapt to hledger 2, I moved to setting the @ price according to the sale price:
account income:gains ; type:G
P 2025-01-01 AAPL 0.5e
P 2025-02-01 AAPL 2e
P 2025-03-01 AAPL 5e
2025-01-01 | Stock purchase: AAPL
investments:stock:AAPL 200AAPL {0.5e} @ 0.5e
assets:checking -100e
2025-03-15 | Stock sale: AAPL
investments:stock:AAPL -200AAPL {0.5e} @ 5e
assets:checking 1000e
income:gains -900e
As a result, hledger balance keeps showing positive --gain even after the balance of AAPL is 0:
$ hledger-lots balance bal -f hledger.journal -M -H aapl --transpose -e 2025-5 --gain
Historical gain in 2025-01-01..2025-04-30, valued at period ends:
|| investments:stock:AAPL |
============++========================+========
2025-01-31 || 0 | 0
2025-02-28 || 300.0e | 300.0e
2025-03-31 || 900.0e | 900.0e
2025-04-30 || 900.0e | 900.0e
$ hledger-lots balance bal -f hledger.journal -M -H aapl --transpose -e 2025-5
Ending balances (historical) in 2025-01-01..2025-04-30:
|| investments:stock:AAPL |
============++========================+=========
2025-01-31 || 200AAPL | 200AAPL
2025-02-28 || 200AAPL | 200AAPL
2025-03-31 || 0 | 0
2025-04-30 || 0 | 0
Expected behavior
I understand that this is because --gain simply calculates the balance at @ costs, which ends up higher balance than the price basis. However, that is unexpected behavior for a command documented as showing "unrealised gains". And if that is the intended behavior for --gain , I'd like to have another command (or a tip on how to invoke an existing one to achieve this) to get the unrealized gain of currently held investments.
Version
hledger 1.99-g1f21f5001-20260331, linux-x86_64
$ hledger-lots setup
Checking your hledger setup..
Legend: good, neutral, unknown, warning
hledger
* is running on linux 6.6.87.2-microsoft-standard-WSL2 on x86_64
* is built with a supported compiler/RTS yes ghc 9.14.1, using threaded RTS
* is a native binary for this machine ? yes x86_64
* is a released version ? no hledger 1.99-g1f21f5001-20260331, linux-x86_64
* is up to date ? checking latest... yes latest is 1.52, 1.99 is installed
* is installed in PATH (this version) ? no
A different hledger version was found in PATH: hledger 1.52, linux-x86_64
at: /usr/local/bin/hledger
Some of this info may not apply to that hledger version. Continuing anyway..
* has a system text encoding configured ? yes UTF-8, data files must use this encoding
* has a user config file ? no
* has a local config file ? no
This is about hledger1.99 preview. Can be considered either a bug or a documentation issue.
After migrating to the new lot tracking syntax I was surprised to see
hledger balance --gainshow non-zero values for an investment account where the current balance was 0. The documentation describes the flag as "show the unrealised capital gain/loss, (the current valued balance minus each amount's original cost)" while in this case all the gains were already realised.Old approach
Before migrating to lots, I used the same
@ pricefor the buy and sale operations, compensating the change in value using anincome:gainsaccount. Like so:With such journal,
balance --gainshows only the unrealised gain on the AAPL I held. After selling them, the value is 0.New approach
To adapt to hledger 2, I moved to setting the
@ priceaccording to the sale price:As a result, hledger balance keeps showing positive
--gaineven after the balance of AAPL is 0:Expected behavior
I understand that this is because
--gainsimply calculates the balance at@costs, which ends up higher balance than the price basis. However, that is unexpected behavior for a command documented as showing "unrealised gains". And if that is the intended behavior for--gain, I'd like to have another command (or a tip on how to invoke an existing one to achieve this) to get the unrealized gain of currently held investments.Version
hledger 1.99-g1f21f5001-20260331, linux-x86_64