full-fledged-hledger: a tutorial for a personal finance setup that has to survive real life

A tutorial published as a series of complete states

Full-Fledged Hledger is a tutorial on setting up hledger, and the repository is unusual because the tutorial and the code are the same thing. The top level is a set of numbered directories, from 01-getting-started through 02-getting-data-in, 03-getting-full-history, 04-adding-more-accounts, 05-creating-csv-import-rules, 06-maintaining-lots-of-csv-rules, 07-investments-easy-approach, 08-mortgage, 09-remortgage, 10-foreign-currency, 11-sorting-unknowns, 12-file-specific-rules, 13-tax-returns, 14-speeding-up, 15-manual-lots and 16-fetching-prices, plus two late additions named z98-budgeting and z99-paypal. Each numbered directory is self-contained and includes all the code and source files from the directories before it. The README is explicit about the rule: you pick a starting point that suits you, clone it, run export.sh, and start populating your journals. The audience is a hledger user whose personal finance setup has grown messy, and who would rather read how someone else solved it than invent a structure.

What the setup actually produces

The list of outcomes is what makes the tutorial worth reading. You get ledger files split by year, multi-source CSV imports with a CSV first workflow where the CSV files are treated as the source of truth, a wide range of auto-generated reports, a single script to update all reports when any source file changes, and what the author calls full freedom to evolve and refactor your journals as you see fit. The CSV-first idea is the one worth pausing on, because it inverts the usual relationship. Instead of importing a bank CSV once and then editing the resulting journal by hand, the CSV stays canonical and the journals are generated from it, which means a corrected import can be re-run without losing manual work. The trade is that your hand-written transactions have to live somewhere else, and the tutorial spends a whole chapter on sorting unknown postings, which is the inevitable result of a bank statement that contains a merchant you have not categorised yet.

The scale the author is working at

The README includes a size report from hledger stats as of 2026, and it is the most useful number in the document because it calibrates what this tutorial is actually for. The setup contains 550 journal files, of which 502 are autogenerated, covering 8100 days of data, 37000 transactions, 14200 payees and descriptions, 417 accounts with a maximum depth of 6, and 21 commodities. The author says the whole thing takes about a minute to regenerate from scratch, and that because the build system only rebuilds what is necessary, a typical update takes about 5 seconds. That is a large personal finance history built by someone who has been at it for 14 years, going through several different approaches, and the README says so: this is the result of that journey, complete with how, why and lessons learned. The practical reading is that the tutorial is aimed at people with years of data, not at someone with one bank account and a start.

The wiki is the tutorial, the directories are the worked examples

The README is emphatic that new users should read the wiki, at least the Getting started page, and it prints the full table of contents so you can see the shape of the tutorial. The chapters run from key principles and practices through getting started, getting data in, getting the full history of an account, adding more accounts, creating and then maintaining CSV import rules, investments, mortgages, remortgage, foreign currency, sorting expenses:unknown, file-specific rules, tax returns, speeding things up, tracking commodity lots manually, fetching prices automatically, and a changelog. Two entries in that list are the ones that show the depth. Manual lot tracking exists because the automatic price fetching does not cover every case, and the changelog means the tutorial keeps up with hledger itself. The repository also carries a diffs/ directory, and the README points at it, saying you can look at the diffs between directories to mix and match features as you see fit. That is the mechanism that makes the whole design workable.

The dependency stack, and the Docker image that removes it

The README anticipates the obvious objection with a section headed about not wanting to install all these dependencies, and the answer is a container. There is a Docker image, dastapov/full-fledged-hledger, and the instruction is to clone the repo, run ./docker.sh, and you are set. The Dockerfile shows what that image actually contains. The builder stage is based on haskell:9.10.3-bookworm with git, python3 and python3-venv installed, a Python virtual environment at /usr/app/venv, and pricehist cloned from GitLab and pip installed, plus skim installed from its release script and miller unpacked from its release tarball.

FROM haskell:9.10.3-bookworm as builder

WORKDIR /usr/app

The final stage is haskell:9.10.3-slim-bookworm with the hledger binaries copied in from a separate dastapov/hledger image at version 1.51.2, the virtual environment and the skim binary copied across, and the export.hs script precompiled with stack so the Shake build does not pay for compilation on every run.

FROM haskell:9.10.3-slim-bookworm

ENV RESOLVER lts-24.33

COPY --from=dastapov/hledger:1.51.2 /usr/bin/hledger* /usr/bin/

The runtime packages are less, patchutils, gawk, csvtool, fzf, ripgrep, parallel and python3, and a non-root hledger user is created with a volume declared at /full-fledged-hledger for the data directory. The presence of fzf, ripgrep and csvtool is a hint about how the import rules are inspected and maintained.

Where this setup is the wrong choice

There are three limits, and the first is the one the README states outright. This is a personal finance setup, not a tool, and the repository contains sample journals and helper scripts rather than something you install and configure. You are expected to assemble a system from the pieces you want, and the author explicitly says you can feel free to ignore all the scripts at the top level of the repo, since they are there to help maintain the project rather than being part of the hledger setup. The second is that the whole thing is Haskell and shell, so a small change to a rule means editing an export.hs script and rebuilding, and the tutorial assumes you are comfortable with both. The third is the assumption of a long history, since the author's own data set is 8100 days old and the year-split journal layout is designed for that scale. The alternative worth naming is hledger-flow, which the README itself points to and describes as a project where all the automation code is contained in a single binary, which is a different trade, less customisable but far less to maintain. And if your accounting is not hledger at all, the author claims the approach should be easily adaptable to ledger or beancount, though that adaptation is left to you.

Maintenance, licensing and the Haskell build

The repository is BSD-3-Clause licensed, which is permissive and unremarkable for a tutorial, and the last push was on 2026-10-22. The tagged releases show a burst of activity in October 2024, with v1.14 for speeding up report generation, v1.15 for manual lot tracking and v1.16 for automatic price fetching all published on the same day, 2024-10-10, and the wiki changelog tracks the same progression. That release pattern is worth reading as a signal, because the last versions line up with the later numbered directories: v1.14 for speeding things up, v1.15 for manual lot tracking and v1.16 for fetching prices. The build system is Shake, the Haskell build tool, driven by stack with a resolver pinned in the Dockerfile, and the export.hs script is precompiled into the image so that the rebuild is fast. The Makefile-adjacent scripts at the root, build.sh, reexport.sh, cleanexport.sh, chapters.sh and the diff tools updatediffs.sh, propagatediff.sh and filterdiff.sh, are the maintenance machinery, which is exactly the part the README tells you to ignore.

Editorial conclusion

Adopt full-fledged-hledger if you use hledger and want a proven structure for year-split journals, CSV imports and generated reports rather than designing one yourself, and if you can read Haskell and shell. Do not adopt it as a ready-made system, because it is a set of example states you have to assemble yourself, and the author says plainly that you can ignore any part of it. Verify first that the state you pick matches the ledger you already have, since each directory is a complete setup and mixing features means reading the diffs directory.

Frequently asked questions

Official sources

1. adept/full-fledged-hledger on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases