simonmichael/hledger 1.99.1

on GitHub

(2.0 preview 1)

Automated lot tracking and capital gains calculation, improvements to print's beancount output, and a new policy for AI-assisted development.

hledger 1.99.1

Breaking changes

• This 2.0 preview is the first hledger release to explore AI-assisted development.
  Please check out the evolving AI policy/FAQ: https://hledger.org/AI.md.
  There's also a new "AI usage" section below.

• hledger now recognises certain transactions as lot disposals;
  and in these, postings to accounts with the Gain type (declared or auto-detected)
  are excluded from normal transaction balancing.
  This means it's possible for existing journal entries to be rejected.
  Eg, this entry (though nonsensical and unlikely) is ok in hledger 1.x but an error in 2.x:

  2026-02-01 sell stock
      assets:stocks      -1 AAA {$50} @ $60
      assets:cash       $50
      revenue:gains     $10
  

  hledger 2.x recognises the assets:stocks posting as a lot disposal,
  and revenue:gains as a Gain account,
  so it excludes the $10 from transaction balancing,
  and then fails to balance the $-60 and $50.
  To fix it you could: rename the revenue:gains to something else,
  or explicitly declare it as type R (Revenue) instead of G (Gain),
  or omit the $10 amount (allowing hledger to infer it).

  Here's a more realistic entry for 2.x, to explain the two balancing steps:

  2026-02-01 sell stock
      assets:stocks      -1 AAA {$50} @ $60
      assets:cash       $60
      revenue:gains    $-10
  

  By default, 2.x will check just the $-60 and $60 (transaction balancing).
  And in lots mode, it will also check the $-50, $60, and $-10 (disposal balancing).

• Posting's ptype field has been renamed to preal (and PostingType to PostingRealness),
  to avoid confusion with the new ptype tag. This changes JSON output.

Features

• hledger now understands, and prints, a Beancount-like cost basis syntax:
  {DATE, "LABEL", COST}, with the parts in that order, all optional.
  Ledger-compatible {COST} [DATE] (NOTE) syntax is also accepted,
  and can be printed using print's new ledger output format.

• Lot-related postings are detected,
  from a {COSTBASIS} annotation, or a :{LOTNAME} subaccount,
  or a lots tag on their account or commodity, or in a few other ways.
  Their type (acquire, dispose, transfer-from, transfer-to, gain) is saved
  in a hidden _ptype posting tag; or with --verbose-tags, in a visible ptype tag.
  (For examples, see hledger print --verbose-tags -f examples/lots/lot-entries.journal)

• Transacted cost (@) is inferred from cost basis ({}) if needed,
  and vice versa. So writing either one is often sufficient.

• Internally, every lot has its own subaccount.
  These can be left implicit, or recorded explicitly.

  A new --lots flag enables "lots mode", which calculates and checks lot movements,
  and makes lot subaccounts visible in reports.

• Lot identities and balances are tracked across transactions and accounts
  (and between year files, with close --clopen --lots).
  Wrong or ambiguous lot movements are reported.

• The reduction method (booking method) for transfers and disposals
  can be configured per account or per commodity, using the lots tag.
  Per-account FIFO, LIFO, HIFO, AVERAGE
  and globally-scoped FIFOALL, LIFOALL, HIFOALL, AVERAGEALL methods are supported.

• Disposals automatically calculate or check capital gain/loss,
  which can be left implicit or recorded explicitly.
  Transaction balancing behaviour has been updated to allow this (see Breaking Changes above).

• The check command has a new lots check,
  which is another way to validate lot movements.
  Eg to run the usual strict checks and also the lot checks: hledger check -s lots.
  Also check accounts now ignores lot subaccounts.

Fixes

• print now preserves empty {} cost basis annotations.

Improvements

• commodities now supports tag: queries, eg hledger commodities tag:lots.

• print's beancount output has been improved:

  • it converts single-letter commodity symbols
  • it converts the no-symbol commodity (to "CC")
  • it converts a top-level "revenue" or "revenues" account to "Income"
  • it converts balance assignments to explicit amounts
  • it converts market prices
  • it sets booking methods based on accounts' lots tag value
  • it generates a (commented) tolerance option
  • it handles account and commodity tags better
  • it shows cost basis before transacted cost, as Beancount requires.

Docs

• Cost basis / Lot syntax: updated
• Lot reporting: added
• Lot postings with balance assertions: added
• Reporting concepts > Detecting special postings: added

Examples

• lot-entries.journal: sample journal entries involving lots
• hledger.conf: how to hide explicit lots

AI usage

This 2.0 preview is the first hledger release to explore AI-assisted development.
There is an AI policy document/FAQ: https://hledger.org/AI.md

In this release, I used claude models to help me design, plan, implement, test, debug and document the lot tracking and capital gains features.
Mostly opus 4.6, plus some experimentation with the cheaper models and the more expensive modes.
Each commit is relatively small and clear and was reviewed and tested by me.

Approx. estimated claude token use (in+out), and cost, for the lots work in this release:

• 2026-01: 133Mt, $85
• 2026-02: 598Mt, $551
• 2026-03: 299Mt, $256
• Total: ~1Gt, ~$900

Approx. human dev time: ~150h, market value ~$10k-30k

hledger-ui 1.99.1

• Uses hledger 1.99.1

hledger-web 1.99.1

Breaking changes

• Posting's ptype field has been renamed to preal (and PostingType to PostingRealness),
  to avoid confusion with the new ptype tag. This changes JSON output.

Fixes

• Uses hledger 1.99.1

• Require yesod-static <1.6.1.1 to avoid a build breakage with cabal
  (psibi/crypton-conduit#3).

project changes 1.99.1

Doc updates

• site: upgrade to latest mdbook
• site: move pages' tables of contents to sidebar
• AI: new project AI policy doc, with links and discussion notes
• IMPACT: new project "external impacts" doc
• README(hledger2 branch): describe the 2.x branch and plans
• REGRESSIONS
• SPEC-lots: specification for lot-related functionality, lot subaccount parsing technique, balance assertions
• SPEC-finalising: retroactive specification for journal finalising
• SPEC-print: document some print behaviours as a specification
• SPEC-special-postings: document patterns of postings recognised by hledger
• PLAN-lots: planning and design notes from implementing SPEC-lots

Infrastructure/tools

• Shake: fix build error with GHC 9.12.2 by using newer shake
• just devtag-push renamed to just devver
• stack configs: 9.14 made default, 9.12 made non-default, both cleaned up and bumped

credits 1.99.1

Simon Michael,
Juliano Solanho.

For all install options, see hledger.org: Install.
You can install hledger from most package managers (but check for a green badge indicating it's up to date).
Or you can build it from source yourself.

Or you can install up to date binaries from this page, by following the appropriate instructions below.
If you find problems with these instructions, please let us know.

If you have eget, that's a convenient way to download the right binaries for your machine:

eget simonmichael/hledger --all

Otherwise:

At the command line:

curl -fLOC- https://github.com/simonmichael/hledger/releases/download/1.99.1/hledger-linux-x64.tar.gz | tar -xzv -f- -C/usr/local/bin hledger hledger-ui hledger-web
hledger --version; hledger-ui --version; hledger-web --version    # should show 1.99.1

In a terminal window (don't download the binaries with your web browser, they won't get authorised):

On ARM macs:

curl -fLOC- https://github.com/simonmichael/hledger/releases/download/1.99.1/hledger-mac-arm64.tar.gz | tar -xzv -f- -C/usr/local/bin hledger hledger-ui hledger-web
hledger --version; hledger-ui --version; hledger-web --version    # should show 1.99.1

On Intel macs:

curl -fLOC- https://github.com/simonmichael/hledger/releases/download/1.99.1/hledger-mac-x64.tar.gz | tar -xzv -f- -C/usr/local/bin hledger hledger-ui hledger-web
hledger --version; hledger-ui --version; hledger-web --version    # should show 1.99.1

In a powershell window (press WINDOWS-R, powershell, ENTER):

cd ~
curl https://github.com/simonmichael/hledger/releases/download/2.0pre1/hledger-windows-x64.zip -OutFile hledger-windows-x64.zip
Expand-Archive hledger-windows-x64.zip -Force -DestinationPath AppData\Roaming\local\bin
hledger --version; hledger-ui --version; hledger-web --version    # should show 1.99.1

These instructions have not been tested recently, please let us know if they work for you:

• click hledger-windows-x64.zip below
• choose Open with Windows Explorer, OK
• click Extract all files
• choose a destination folder - ideally one that appears in echo %PATH%, like C:\Windows (though that one will require administrator permission); otherwise, your home directory (C:\Users\YOURNAME)
• check "Show extracted files when complete"
• click Extract, wait for the destination folder to open
• find the hledger, hledger-web icons (if you extracted to \Windows, you'll need to scroll down)
• for each icon: double-click, uncheck "Always ask before opening this file", click Run
• close those Explorer windows
• open a command window (press Windows-r, type CMD, press enter)
• hledger --version; hledger-ui --version; hledger-web --version should show 1.99.1
• echo # >> .hledger.journal to ensure a default journal file exists. (Important: the doubled >> is needed to avoid overwriting existing data.)

Problems:

• Starting hledger by double-clicking its icon won't work because it needs arguments; run it from the command window instead.
• Starting hledger-web by double-clicking its icon may fail eg because Explorer's command window is too small;
  configure that to be larger, or run hledger-web from a command window instead.
• hledger or hledger-web may fail to run if there is not enough memory available.

Next steps

Once installed, run hledger, and perhaps read hledger.org: Quick start.