org-tutorials/weaving-a-budget.org

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