hledger-flow

File your bank statements. Rebuild your ledger from them, any time.

hledger-flow keeps each statement in a folder for its owner, bank, account and year. It converts every statement with hledger’s CSV rules and includes the results in one all-years.journal. Improve a rule, import again, and years of transactions are reclassified. git diff shows exactly what changed.

Read the quick start
brew install ferntrail/tap/hledger-flow
  1. 1-in/2025/2025-03.csv 
    2025-03-14,City Rail monthly pass,-62.50
  2. import/mybank.rules 
    fields date, description, amount
account1 assets:john:mybank:checking

if City Rail
  account2 expenses:transport
  3. 3-journal/2025/2025-03.journal 
    2025-03-14 City Rail monthly pass
    assets:john:mybank:checking         $-62.50
    expenses:transport                   $62.50
  4. all-years.journal, read via LEDGER_FILE 
    include import/all-years.journal
  include 2025-include.journal
    one per owner, bank and account
      include 3-journal/2025/2025-03.journal
  5. hledger bal expenses 
           $4.80  expenses:misc
      $62.50  expenses:transport
--------------------
      $67.30
One line of a March statement, from the downloaded CSV through the generated includes to a report.

A folder for every statement

The folders tell hledger-flow who owns an account, where it’s held and which year a statement covers. You add the statements, rules and manual journals. hledger-flow writes the rest, so you can delete every generated file and get the same ledger back.

Ink marks the files you write. Pencil marks generated files.

Change a rule, rebuild every year

City Rail purchases have been landing in expenses:misc. Add a rule to import/mybank.rules and run hledger-flow import. Every statement that uses those rules is converted again, in every year you’ve imported.

import/mybank.rules
 if Salary
   account2 income:salary
+
+if City Rail
+  account2 expenses:transport
git diff -- import/
 2025-03-14 City Rail monthly pass
     assets:john:mybank:checking         $-62.50
-    expenses:misc                        $62.50
+    expenses:transport                   $62.50

Handwritten transactions live in manual journals, so a rebuild never touches them.

hledger-flow or plain hledger?

All three read your statements with the same hledger rules files. They differ in which file is your record, and in what happens when you improve a rule.

hledger import

The journal is your record.

Each import converts only the transactions it hasn’t seen before and appends them to your journal. From then on they’re yours to edit, split or annotate by hand. A better rule affects future imports only. Overlapping downloads such as “the last 90 days” are fine, so it suits frequent, small downloads. See hledger’s import guide.

Include the CSV

The CSV is your record, converted on every read.

Write include checking.csv in your journal, with checking.csv.rules beside it. hledger converts the CSV whenever it reads the journal. There are no generated files, and a rule change applies to your whole history at once. You fix transactions in the rules, not by hand. It suits a few large, regular files whose rules keep changing. See hledger’s include directive.

hledger-flow

The statements are your record. The journals are build output.

Every statement stays as your bank issued it, filed by owner, account and year, so years later, in a tax audit say, you can show where each transaction came from. Change your mind about a category, edit one rules file, and every journal in every year is regenerated the same way, with no search-and-replace through old entries. The journals are written out, so git diff shows what each change did before you commit. Statements mustn’t overlap, because each is converted on its own.

In short: if you’d rather edit transactions than rules, use hledger import. If you have a few CSV files and want the fewest moving parts, include them. Choose hledger-flow when your statements are records to keep for years, and you want to reclassify, add detail or adopt a bank’s new format at any time, with every year staying consistent and every change open to review.

Install

Homebrew macOS, Linux
brew install ferntrail/tap/hledger-flow
Release download Windows, macOS, Linux
Choose the archive for your system
From source Any platform with Stack
stack install from a checkout

Then follow the quick start to import your first statement, or the tutorial for the whole story.