Home

"Full-fledged Hledger" Tutorial

Full-Fledged Hledger is a tutorial on how to setup up hledger to get:

• data split into files by year
• multi-source CSV imports
• range of auto-generated reports
• single script to update all reports when any source file change
• full freedom to evolve and refactor your journals as you see fit
• and more

What is included?

A set of sample journals and helper scripts that I use together with hledger for tracking personal finances and budgeting. It should be easily adaptable to other command-line accounting tools (ledger, beancount, ...).

I went through several different approaches over the course of 10 years, and this is the end result of that journey, complete with "how", "why" and lessons learned.

What do I need to run it?

Scripts and files here assume Linux-like environment with Haskell (in particular, you will need runhaskell and stack) and textutils/shellutils available. I have not tested them on Mac OS or Windows. I expect Mac OS to mostly work and Windows users can use Docker (see below).

Automation is done using shake build system, which would be automatically installed first time you run report generation script.

Docker

Windows users or those unwilling to set up stack can follow the tutorial with the help of docker image.

After cloning the repo, run ./docker.sh, which will mount current directory inside docker image that contains all the necessary software and start up shell there.

Goals

I wanted a setup that would satisfy three major requirements:

• Tracking expenses should take as little time, effort and manual work as possible.

• It should be easy to work towards eventual consistency. Large and daunting tasks (like "I will process 10 years of paper mortgage statements" or "I want to import 5 years of paypal payments") should not require one big push and perfect planning to finish them. Instead I should be able to do them bit by little bit, leaving things half-done, and picking them up later with little (mental) effort. Eventually my records would be perfect and consistent.

• Ability to refactor is a must. This is the natural extension of the previous point. I want to be able to go back and change the way I am doing things, with as little effort as possible and without fear of irrevocably breaking things.

I believe that have a setup that allows you to do all that, and more.

Structure

It is relatively easy to describe what I am doing, but it is harder to describe why. The easiest way to answer all the why questions is to illustrate how one can grow a setup from scratch, gradually introducing problems and solutions.

This repository contains a number of directories (01-getting-started, 02-getting-data-in, ...) that represent evolution of the setup, starting from the bare minimum and adding one new feature at a time. This allows you to choose the starting point that is more suitable for you or compare/diff various setups and see what exactly has been changed at every step : diffs between the steps are in the diffs directory.

Suggested reading order

If you are fairly experienced with ledger, hledger, beancount or any other plain-text accounting tool, you might want to quickly check out key principles and practices to see how things are laid out and then head directly to the most featureful (most-highly-numbered) directory and take a look around to see how everything is done. Run ./export.sh to generate all reports and see what is being processed and how. If things don't make sense, start at the beginning, and proceed in the order displayed on the sidebar.