org-tutorials/weaving-a-budget.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE: Weaving a budget with Org & ledger
   6 #+AUTHOR:     Erik Hetzner
   7 #+EMAIL:      egh@e6h.org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 * Weaving a budget with Org & ledger
  13
  14 Since I am intending this tutorial for worg, I will assume that the
  15 reader is familiar with Org. If you are not, but are an emacs user, I
  16 encourage you to explore Org. It is an invaluable piece of software.
  17
  18 Now, assuming that you are familiar (or have familiarized yourself)
  19 with Org, you might also be interested in using ledger. If you already
  20 are using it, this tutorial is for you. If you are new to ledger, you
  21 might find the [[http://www.ledger-cli.org/3.0/doc/ledger3.html][manual]] useful. The [[http://hledger.org/step-by-step][hledger step-by-step]] guide is also
  22 useful, though intended for hledger (a close cousin of ledger). I
  23 don’t intend to introduce the reader to ledger in this document.
  24
  25 Now, ledger comes with a built in budget system, but I wanted to get
  26 an “envelope” style budget working. While this was easy to do in
  27 theory, in practice it proved more difficult. The theory is pretty
  28 simple; enevelope budgeting merely requires you to create new accounts
  29 to keep track of each “envelope” of money, and assign all of your
  30 income to those separate accounts. But in practice, it requires a huge
  31 amount of duplicate data-entry, even when using ledger’s automatic
  32 transactions, because each month’s budget tends to *mostly* but not
  33 *exactly* the same as the last month’s. This quickly becomes a
  34 nightmare when you want to change your monthly food budget over the
  35 past six months. The following document describes how I managed to get
  36 something working, with nice reporting, using Org’s babel and noweb
  37 features.
  38
  39 ** The theory
  40
  41 In theory, ledger can easily be used to manage an envelope budget. The
  42 basic idea is that you will place all your money in different
  43 =Budgeted= accounts. For instance, if you earn $1000/mo and want to
  44 place half of that money in your food budget and the other half in
  45 your bars budget, you would use:
  46
  47 #+BEGIN_EXAMPLE
  48 2014/01/01 Income
  49   Assets:Checking         $1000
  50   Income                 -$1000
  51   Budgeted:Expenses:Food   $500
  52   Budgeted:Expenses:Bars   $500
  53   Budget                 -$1000
  54 #+END_EXAMPLE
  55
  56 (The =Budget= account is to ensure things balance; it should be equal
  57 to your income.)
  58
  59 Now, you will use automated transactions to deplete your budget as you
  60 move money to your =Expenses= accounts. Here is an automated
  61 transaction that will work for all your expenses in 2014 and
  62 afterwards:
  63
  64 #+BEGIN_EXAMPLE
  65 = expr (date>=[2014] and account =~ /^Expenses:/)
  66   Budgeted:$account        -1
  67   Budget                    1
  68 #+END_EXAMPLE
  69
  70 Now, given expense transactions that look like:
  71
  72 #+BEGIN_EXAMPLE
  73 2014/01/02 Foo
  74   Assets:Checking      -$100
  75   Expenses:Food         $100
  76 #+END_EXAMPLE
  77
  78 this will add, for every posting that starts with =Expenses=, a
  79 posting to =Budgeted:Expenses= and to =Budget=. This will result in
  80 the automated equivalent of having entered:
  81
  82 #+BEGIN_EXAMPLE
  83 2014/01/02 Foo
  84   Assets:Checking         -$100
  85   Expenses:Food            $100
  86   Budgeted:Expenses:Foo   -$100
  87   Budget                   $100
  88 #+END_EXAMPLE
  89
  90 The automated transaction saves us a great deal of repetetive work, as
  91 you can see.
  92
  93 Now, this solution will work. Each month, you will replenish your
  94 budget accounts by an amount equaling your income for that month, and
  95 as you spend money the budget accounts will be depleted as you spend
  96 money. But the trickiest part, I found, was in adjusting your budget
  97 as needed. For instance, I found that I needed a base budget for
  98 things like food and gas, but that other items might suddenly stop.
  99 For instance, you might cancel your cable, or take up a new hobby. You
 100 can copy and paste your base budget, but then when you go back to
 101 retroactively change your food budget (as you will probably need to,
 102 to adjust to the fact that you are spending more or less than
 103 anticipated), you need to go back and change all those budget entries.
 104 This quickly becomes a hassle.
 105
 106 ** The practice (Org enters the picture)
 107
 108 This is where Org, and particularly babel’s noweb features come in.
 109 But first, let’s look at how you can use Org to generate some useful
 110 reports. Here is how I generate last month’s expenses:
 111
 112 : * Last month's expenses
 113 : #+begin_src ledger :cmdline bal -p "last month" ^Expenses: :results output :exports results
 114 : !include /path/to/ledger.lgr
 115 : #+end_src
 116
 117 (You may need to ensure that =ob-ledger= is loaded into your Org;
 118 see the [[file:../org-contrib/babel/languages/ob-doc-ledger.org][ob-ledger doc]] for details.) Now, if you type =C-c C-c= on this
 119 entry, it will generate a report of your expenses last month, which
 120 will be placed after the source block, and will look like:
 121
 122 : #+RESULTS:
 123 : #+begin_example
 124 :             $150.00  Expenses
 125 :             $100.00    Food
 126 :              $50.00    Bars
 127 : --------------------
 128 :             $150.00
 129 : #+end_example
 130
 131 By using babel, you can generate a lot of useful reports and keep them
 132 up-to-date, exporting them to HTML or PDF for printing, etc.
 133
 134 But some of the really useful features come when you use Org’s noweb
 135 to weave a budget together. noweb allows, among other things, you to
 136 include source blocks in other blocks. First, you’ll set up your base
 137 budget, which will be included in every budget. Say you know that
 138 every month you will spend $500 on food. You create a ledger source
 139 block with a name, =base-budget=:
 140
 141 : #+name: base-budget
 142 : #+begin_src ledger
 143 :   ; :BUDGET:
 144 :   Budgeted:Expenses:Food  $500
 145 :   Budgeted:Savings
 146 : #+end_src
 147
 148 This means that you want $500 to go to food, and the balance to
 149 savings. (The first line =; :BUDGET:= is a tag to let you identify
 150 this as a budget; this helps with some reports.) Now, you can set up
 151 your budget block:
 152
 153 : #+name: budget
 154 : #+begin_src ledger :noweb yes
 155 : = expr (date>=[2014] and account =~ /^Expenses:/)
 156 :   Budgeted:$account        -1
 157 :   Budget  1
 158 :
 159 : 2014/01/01 * Budget
 160 :  <<base-budget>>
 161 :  Budget  -$1000
 162 : #+end_src
 163
 164 What you have done here is set up your automated transaction, as
 165 above, and set up your first month’s budget. You have assumed that
 166 your first month’s income is $1000, and you have included your base
 167 budget. When this is woven by noweb, =<<base-budget>>= will be
 168 replaced with the =base-budget= source block, and Org will pass the
 169 following on to ledger:
 170
 171 : 2014/01/01 * Budget
 172 :   Budgeted:Expenses:Food  $500
 173 :   Budgeted:Savings
 174 :   Budget                -$1000
 175
 176 This will set up $500 in your food budget, and the balance ($500) for
 177 savings.
 178
 179 Now, to generate a report, you can use the following:
 180
 181 : #+begin_src ledger :cmdline bal -p "this year" ^Budgeted:Expenses -E :results output :exports results :noweb yes
 182 : <<budget>>
 183 : !include /path/to/ledger.lgr
 184 : #+end_src
 185
 186 Running this report (=C-c C-c=) will tell you your budget balance for
 187 each expense. If you budgeted $500 for food and spent $600, your
 188 balance will be -$100. If you spend $300, your balance will be $200.
 189
 190 Each month, month, you will create a new budget entry in your =budget=
 191 source block, with the =Budget= account equaling your income that
 192 month. You will include your =<<base-budget>>=, and any adjustments
 193 you want to make.
 194
 195 For example, say that in June you take up cycling. You want to budget
 196 $100 per month for this, but you want to start in June, not January.
 197 You will add the following entry to your =budget= source block:
 198
 199 : 2014/06/01 * Budget
 200 :  <<base-budget>>
 201 :  Budgeted:Expenses:Cycling  $100
 202 :  Budget                   -$1000
 203
 204 This means that for June your budget will be $500 for food, $100 for
 205 cycling, and $400 for savings.
 206
 207 Now, you will need to keep adding the cycling budget line every time
 208 from now on, so you might want, at some point, to get complicated. You
 209 could define a new source block with the name =base-budget-new=,
 210 include your old =base-budget=, using =<<base-budget>>=, and then
 211 include that in your budget entries going forward, to avoid duplicate
 212 typing. noweb should allow you to structure your budget entries
 213 however you like.
 214
 215 I’ve found this solution to be flexible enough to allow me to manage a
 216 budget that is contantly being adjusted, and easy to generate
 217 printable reports. ledger and Org make an excellent pair.