https://lock.cmpxchg8b.com/ledger.html

Ledger.

Tavis Ormandy

$Id: f0cc50a6fc6a5dd652c2b96ca9c1779f763fd6b1 $

  * Intro
  * Getting Started
  * Examples
  * Advice

Intro

One of my new years resolutions was to commit to using ledger - a
commandline accounting tool. Ledger is a bit like Quicken, GnuCash or
Mint, but for UNIX nerds.

    Note: No relation to the cr*pto product with the same name.

It's coming up to the end of the year, and this was one of the few
resolutions I actually managed to keep!

I think you can probably accomplish everything ledger can do with
other personal finance software. The reason you would choose ledger
is that you're sold on the efficiency and scriptability of the
commandline, along with the grep, editor and revision control
friendly file format.

If that sounds interesting, go take a look at the docs to learn more!

The TL;DR is that I'm hooked, and will keep using it.

Getting Started

It's not easy to get started with ledger, and you're probably going
to have some uncommon financial arrangements that the documentation
didn't cover exactly. It could be anything, maybe something mundane
like you split the utilities with a partner, but you're the one who
pays the bill?^1

These things are easy to handle once you're familiar with ledger
concepts, but as nobody has the exact same arrangements as you, it's
not always a copy-and-paste situation.

This is where ledger's flexibility can be a curse - the answer to
questions like "How do I handle ...?" tends to be "However you like!".
Cool, but you're not going to have any opinions formed yet, so how do
you know what you like?

I don't really have a good solution - I think you just have to wing
it until you're proficient, then go back and fix any naive mistakes
you made 

Another problem is that you need a few months worth of data before
you can fairly evaluate if you find it useful or not. That's a big
commitment to something that you're not sure you're actually going to
enjoy!

After you've finally built up some data... your reward is having to
learn the query syntax so you can actually do something useful with
it... and that's when you'll realize you didn't organize things
optimally, and have to go back and edit the last few months of data!


Now that I've scared everyone off, I can tell you I don't regret that
effort - ledger is great! You know that feeling when you find a
solution that just feels "correct"? Well, ledger gives me that
feeling.

Examples

So, what exactly does ledger look like? Well, there is no user
interface, it's a commandline tool to query your finances.

    Note: If you want graphs, you pipe the output into gnuplot, like
    this. If you're a stats nerd, you might prefer ledger-plots.

You can automatically import transactions from whatever format your
bank provides, but I prefer to enter some transactions manually. I
use vim's colorcolumn feature to make margins and keep everything
neatly aligned.

Once you've got importing and editing working smoothly, you can start
answering questions about your finances.

  * How much have I spent this month?

$ ledger bal --period "this month" ^Expenses:

  * How much did I spend on gas each month this year?

$ ledger reg --period "this year" --monthly ^Expenses:Auto:Gas

  * What is my current networth?

$ ledger bal --depth 1 --market ^Assets: ^Liabilities:

  * How much have my investments grown?

$ ledger bal --gain ^Assets:Brokerage

  * Okay, but what about my investment in stock FOOBAR specifically?

$ ledger bal --gain --limit 'commodity == "FOOBAR"' ^Assets:Brokerage

  * Okay, but how much of that is long term capital gains?

$ ledger bal --gain --limit 'commodity == "FOOBAR"' --limit 'lot_date(amount) < [365 days ago]' ^Assets:Brokerage

  * How much did I spend at McDonalds in June?

$ ledger bal --period "this june" ^Expenses: and @McDonalds

  * How much do I spend each month on average in total?

$ ledger reg --period "this year" --average --monthly --depth 1 ^Expenses:

  * Where is that money going, but only show me the categories I
    spend more than $20 on?

$ ledger bal --period "last 12 months" --amount "amount / 12" --display 'top_amount(amount) > 20' ^Expenses:

  * Did I earn enough credit card rewards to justify the fees, or
    should I cancel them?

$ ledger reg --period "this year" --subtotal --related ^Income:Reward

  * Show me all the donations I made that I can deduct on my taxes?

$ ledger reg --period "this year" %deductible

These are just some random examples, there are also budgeting and
forecasting tools. It's flexible enough that people use it for
tracking billable hours, inventory and so on.

Naturally, it handles multiple currencies, arbitrary commodities, and
you can track them as precisely (or coarsely) as you like.

Advice

This post is really just encouraging anyone considering getting
started to take the leap if you were thinking about getting started
in the new year!

---------------------------------------------------------------------

 1. fyi, you could probably record that like this:

    ; Pay the power bill, John owes me half
    2023/10/1 * Power Company
       Expenses:Utilities:Power    $50
       Assets:Receivables:John     $50
       Assets:Checking            -$100
    ; John reimbursed me.
    2023/10/2 * John Doe  ; Flatmate
       Assets:Checking             $50
       Assets:Receivables:John    -$50

    ...but maybe you want to record it like this:

    ; Pay the power bill, John owes me half
    2023/10/1 * Power Company
       Expenses:Utilities:Power    $100
       Assets:Checking             $100
    ; John reimbursed me his half.
    2023/10/2 * John Doe  ; Flatmate
       Assets:Checking             $50
       Expenses:Utilities:Power   -$50 ; [=2023/10/1]

    There is not always one right answer!-[?]

HOME * ABOUT * CONTACT