Hacking Your Finances
for Fun and Profit

Matthew Turland

What is Ledger?

• Command-line double-entry accouting system written in C
• Open source under the New BSD license
• Works on several Linux flavors, Windows, and MacOS X
• Hosted on GitHub
• http://ledger-cli.org

Why Ledger?

• Read-only: reports on your data, never modifies it
• Currency-agnostic: supports arbitrary currencies and currency conversions
• International: UTF-8, US and European decimal formats, ISO dates
• Supports budgeting, forecasting, capital gains tracking, and more
• Vim support: filetype, syntax, and useful commands

Ledger Terminology

Journal

A file that contains Ledger data — mostly transactions, but also control directives, comments, and other stuff.

Account

A category, usually arranged within a hierarchy, that accumulates quantities. Common top-level categories include Equity, Assets, Liabilities, Expenses, and Income.

Posting

Accumulation of a quantity by a single account.

Transaction

A financial event entered into a journal, such as depositing a paycheck. Comprised of two or more postings that balance out to zero.

The Ledger Format

; Comment
Date Description
    Account1                   Amount1
    Account2                   Amount2
    AccountN

Transaction Examples

2006/10/15 McDonald's
    Expenses:Dining            $5.36
    Assets:Checking

2006/10/15 Exxon
    Expenses:Auto:Gas         $15.00
    Expenses:Cigarettes        $4.80
    Liabilities:MasterCard

; repeat ad nauseam

The Register

$ ledger reg checking -f stan.txt
08-Jan-01 Opening Balances      Assets:Checking            $1550.00     $1550.00
08-Jan-01 New Seasons           Assets:Checking             $-60.91     $1489.09
08-Jan-01 Panda Express         Assets:Checking              $-7.24     $1481.85
08-Jan-02 Sizzle Pie            Assets:Checking              $-7.38     $1474.47
08-Jan-03 Kettleman Bagels      Assets:Checking              $-7.60     $1466.87
08-Jan-03 Mio Sushi             Assets:Checking              $-5.76     $1461.11
08-Jan-03 Eddie's Flat Iron P.. Assets:Checking             $-22.26     $1438.85
08-Jan-04 Food Carts            Assets:Checking              $-7.24     $1431.61
08-Jan-05 Burnside Brewery      Assets:Checking             $-11.76     $1419.85
08-Jan-05 Tastebud              Assets:Checking             $-42.13     $1377.72
08-Jan-07 Salary                Assets:Checking            $1084.00     $2461.72
08-Jan-08 Safeway               Assets:Checking             $-64.76     $2396.96
08-Jan-08 Netflix               Assets:Checking              $-9.99     $2386.97
08-Jan-08 Car Payment           Assets:Checking            $-464.70     $1922.27
08-Jan-08 Student Loan Payment  Assets:Checking            $-199.06     $1723.21
08-Jan-09 Taco Del Mar          Assets:Checking             $-10.25     $1712.96
08-Jan-09 Burnside Brewery      Assets:Checking              $-6.19     $1706.77
08-Jan-10 Kettleman Bagels      Assets:Checking              $-7.67     $1699.10
08-Jan-11 Panda Express         Assets:Checking              $-9.64     $1689.46
08-Jan-11 Papa Hayden           Assets:Checking             $-21.39     $1668.07
...

Balance

$ ledger bal expenses -f stan.txt 
          $157874.79  Expenses
            $5212.85    Entertainment
           $21526.95    Food
            $1377.36      Breakfast
            $3174.59      Dinner
           $11171.71      Groceries
            $5803.29      Lunch
            $8568.00    Insurance
            $3948.00      Car
            $4620.00      Medical
           $5136.40    Interest
            $4618.79      Car
             $517.61      Student
           $33600.00    Rent
...
--------------------
                   0

XML

$ ledger xml -f stan.txt 
...
<transaction state="cleared">
  <date>2008/01/01</date>
  <payee>Opening Balances</payee>
  <posting state="cleared">
    <account ref="0000000000f3d600">
      <name>Liabilities:Loans:Student</name>
    </account>
    <post-amount>
      <amount>
        <commodity flags="P">
          <symbol>$</symbol>
        </commodity>
        <quantity>-25300</quantity>
      </amount>
    </post-amount>
    <total>
      <amount>
        <commodity flags="P">
          <symbol>$</symbol>
        </commodity>
        <quantity>-25300</quantity>
      </amount>
    </total>
  </posting>
  <!-- ... -->
</transaction>

Useful Options

• --begin, --end: limit date range
• -w: wide view, good for seeing long transaction descriptions and account names
• -W, -M: weekly and monthly summaries
• This is just the tip of the iceberg; see the manual for more

Custom Reports

• XML -> PHP script -> CSV file with monthly expenses to date by account
• Useful, but not very visual

           January       ... December       Total
Account1   JanuaryAmount ... DecemberAmount Account1Total
...
AccountN
Total      JanuaryTotal  ... DecemberTotal  GrandTotal

Ledger Stats

• Requires PHP 5.3.0+ and ledger 3.0.0
• Enables you to search transactions by account, date, and amount
• Implements a plugin system to allow action to be taken on the results
• Stock plugins display charts to visualize the results
• Rough prototype, but fairly functional
• Hosted on GitHub
• Demo time!

Discussion

• Questions?
• Comments?
• Concerns?
• Thank you!