Getting started

Associated directory: 01-getting-started

I assume that you want to keep track of your finances with hledger. You have read hledger basics tutorial and hledger accounting concepts, and you know the difference between "assets", "liabilities", "equity", "income" and "expenses".

However, it is hard to begin: which accounts one should create and maintain? How to deal with multiple years and multiple banks? What if you later decide to change something?

Let's get started with an empty journal.

Look into 01-getting-started, where you will find a completely empty journal for the current year (at the time of writing - 2017) and a couple of export scripts. Check that the current year is properly reflected at the top of ./export/export.hs:

--
-- Range of years to report. You would typically want all the years you have data for.
--
defaultFirstYear   = 2017 :: Int
defaultCurrentYear = 2017

What is this export.sh thing?

Script export.sh is a one-liner that invokes export/export.hs, where the real magic lies. That file uses shake - build system written in Haskell - to automate all conversion and report generation tasks. Entire contents of export/export.hs is build rules with small amount of customizeable information at the top -- like current year and list of reports you want to generate.

Shake was chosen mainly for its ability to handle complex dependencies easily. It allows you to write code that discovers file dependencies dynamically, while Shake runs -- something that make, for example, would require a separate make depend step for, and extra files to keep track of dependencies.

Lets run it!

Now run ./export.sh, and a bunch of files would be generated in ./export:

export
├── 2017-all.journal           - a list of all transactions for the year, to simplify review
│                                and double-checking
├── 2017-balance-sheet.txt     - balance sheet for the end of the year, showing your assets
│                                and liabilities
├── 2017-cash-flow.txt         - cash flow report for the year
├── 2017-income-expenses.txt   - income and expense report for the year
└── export.hs                  - Shake build script that describes how these reports
                                 are generated

As explained earlier, general idea is to keep these files under version control so that whenever you want to change anything in your setup it would be easy to see what exactly was affected by asking version control system for diffs versus the previously saved version of these reports.

As you can see, your current journal is empty and reports reflect this - they would show that various totals are zero and pretty much nothing else. Commit all of them into the version control system of your choice.

Gradually adding more details

In the previous section I've mentioned that one of the key principles would be "adding more details over time". At the moment we have no data whatsoever - what would be the minimal first step that could already give us some taste of how tracking your finances could be useful for you?

What is the absolute minimum of financial tracking you can do? It would probably be taking note of your account balance now and then.

You can start with your main account. Normally it would be the account that you use to fund most of your day-to-day expenses. It is probably a "checking" (or "current", or "debit") card account at the bank of your choice. If you have several of them -- just pick one for now, we will deal with the rest shortly.

To begin, you look at the current balance ($1230) in that account and record in in your journal:

$ hledger print -f all.journal 'desc:opening'

2017-01-01 opening balances
    assets:Lloyds:current                   = £100.00
    equity:opening balances

From this point onward, you can start recording your balances monthly:

$ hledger print -f 2017.journal 'desc:End-of-month' | sed -e '/income/d; s/expenses:unknown/unclear/g'

2017-01-31 End-of-month balance
    assets:Lloyds:current                 = £840.61
    unclear

2017-02-28 End-of-month balance
    assets:Lloyds:current                 = £1626.75
    unclear

2017-03-31 End-of-month balance
    assets:Lloyds:current                 = £2618.31
    unclear

2017-04-30 End-of-month balance
    assets:Lloyds:current                 = £3322.48
    unclear

2017-05-31 End-of-month balance
    assets:Lloyds:current                 = £4058.83
    unclear

As you can see, I am balancing these transactions against account called unclear, as at this level of detail it is not clear why the balance is changing -- perhaps you are earning money, but most likely you are spending them as well, and it is not clear what your income and expenses are.

Even with this minimum amount of data you can look at trends such as your average or total spending for the year to day:

$ hledger print -f 2017.journal 'desc:End-of-month' | sed -e '/income/d; s/expenses:unknown/unclear/g' | hledger balance -f - -MAT

Balance changes in 2017-01-01..2017-05-31:

                       ||      Jan       Feb       Mar       Apr       May      Total   Average 
=======================++=======================================================================
 assets:Lloyds:current ||  £840.61   £786.14   £991.56   £704.17   £736.35   £4058.83   £811.77 
 unclear               || £-840.61  £-786.14  £-991.56  £-704.17  £-736.35  £-4058.83  £-811.77 
-----------------------++-----------------------------------------------------------------------
                       ||        0         0         0         0         0          0         0 

This might be usefulalready, but I propose to immediately take it one step further. Let's say that when you record end-of-month account balance, you are also recording the salary from your payslip, like this:

$ hledger print -f 2017.journal 'desc:End-of-month'

2017-01-31 End-of-month balance
    assets:Lloyds:current                 = £840.61
    income:employer              £-800.11
    expenses:unknown

2017-02-28 End-of-month balance
    assets:Lloyds:current                 = £1626.75
    income:employer              £-900.22
    expenses:unknown

2017-03-31 End-of-month balance
    assets:Lloyds:current                 = £2618.31
    income:employer             £-1093.72
    expenses:unknown

2017-04-30 End-of-month balance
    assets:Lloyds:current                 = £3322.48
    income:employer              £-800.72
    expenses:unknown

2017-05-31 End-of-month balance
    assets:Lloyds:current                 = £4058.83
    income:employer              £-903.52
    expenses:unknown

Hledger could now do some (trivial) math to balance these transactions which will effectively compute your total spending for given month from the income and final balance:

$ hledger incomestatement -f 2017.journal -MAT

Monthly Income Statement 2017-01-01..2017-05-31

                  ||     Jan      Feb       Mar      Apr      May     Total  Average 
==================++=================================================================
 Revenues         ||                                                                 
------------------++-----------------------------------------------------------------
 income:employer  || £800.11  £900.22  £1093.72  £800.72  £903.52  £4498.29  £899.66 
------------------++-----------------------------------------------------------------
                  || £800.11  £900.22  £1093.72  £800.72  £903.52  £4498.29  £899.66 
==================++=================================================================
 Expenses         ||                                                                 
------------------++-----------------------------------------------------------------
 expenses:unknown ||  £59.50  £114.08   £102.16   £96.55  £167.17   £539.46  £107.89 
------------------++-----------------------------------------------------------------
                  ||  £59.50  £114.08   £102.16   £96.55  £167.17   £539.46  £107.89 
==================++=================================================================
 Net:             || £740.61  £786.14   £991.56  £704.17  £736.35  £3958.83  £791.77 

To increase the level of detail even further, we need to slice that monolithic slab of expenses into smaller expense categories. This could be done based on the transaction statement that you can get from your bank, but going over the statements and converting each line into a journal entry manually would be extemely tedious and error prone.

Fortunately, hledger (with the help from scripts in this repository) allows you to automate this.

Next steps

Now it is time to get some data in.