blog/content/posts/2021-01-15-plaintext-accounting/index.md

title	date	draft	description	tags	categories	series	favorite
Plaintext Accounting, beancount, and fava	2021-01-15T15:54:51+01:00	false	Or the story of my fall into systematically logging my expenses	accounting cli	software slice of life		false

Plain text accounting is a way of tracking your finances using simple text files and command line software.

Being about to work on my end-of-studies internship, and therefore enter the adult, professional world, I decided that I needed a better way to track my income, expenses, and net worth.

My accounting journey

I went through most of my life without having to account for my money explicitly, making use of the "dad bank". I received small sums of money at Christmas and for birthdays, most of which went straight to an envelop that my dad kept for me. This is the money that I used to buy myself books, games, and other small things during childhood. My father kept track of the money and told me how much I had left whenever I asked him.

During high school, my parents opened a bank account for me, and handed me a credit card to allow me to buy lunch, make gifts, and other discretionary spendings without having to explicitly go through them. It was regularly checked on by my parents to make sure I always had some amounts of money to my name in case I needed it, which they did up and until my engineering school. At this point I had a pretty good idea of how much I could spend and when I could spend it. This information could fit entirely in my head without any problems.

Once I had spent a year at EPITA, I decided to apply to the team of teaching assistants. Between the money that I earned during my internship and what I was earning as an assistant, I was finally gaining some financial independence. Until very recently I was still mostly keeping track of my spending in my head, my student job allowing me to avoid explicitly budgeting my money.

Why do I want an actual accounting solution?

As you can see from my history, I have spent my whole life until this point without using any form of accounting. Some people keep going their whole life without ever explicitly using any accounting solutions, having a ball-park idea of how much they have spent and how much they can afford to spend later.

This, however, does not accommodate me anymore. I want to have more fine-grained control over my money, and be able to track and analyse my spending. I also know that I am somewhat of an air-head, and tracking my money explicitly will probably allow me to avoid, or at least reduce, lifestyle inflation once I finish school and enter the work-force.

To that end, some people use a spreadsheet and simply keep track of their transactions as a row of in-n-out flow of money. This is also problematic to me: it is bothersome to come up with a useful template for budgeting, easy to mess up my reporting, especially with transactions that are harder to model using a simple template. Furthermore, it is very hard to version a spreadsheet, being a programmer, and lover of the command line, I want to be able to use git to keep track of my budget through time.

The perfect system for me has to be:

• foolproof: it is hard to mess up my reporting, and easy to know when I make a mistake,
• exhaustive: I can use the same system to keep track of my money, my investments, my debts, and anything that I would like to track,
• data-oriented: it should allow me to process my data and do some powerful analysis on my past transactions: I want to be able to know how much money I have spent at my neighbourhood bakery in the last semester.
• have a pretty interface and export abilities: this allows me to talk with a banker or an accountant without them having to know how to use my accounting system,
• be Free and Open-Source Software: I can tinker with the sources if something isn't to my liking, and more easily ensure that my data will still be usable 20 years down the line.

Beancount

What is it?

beancount is a tool to do double-entry accounting on the command line, using only plain text files. It is inspired by ledger and hledger, both respected tools in the plain text accounting community, from which beancount draws inspiration both in their syntax and their philosophy.

The point of plain text accounting is to make it easier and more efficient to use the double-entry-style of accounting. This translates both in the syntax of the ledger files, as well as the simplifications made to double-entry accounting to make it seem more intuitive and easier to use.

To be more specific about beancount, it is a tool written in Python, made to be kept simple and effective by its author. It is both very powerful from the get-go, and easy to extend thanks to a system of plug-ins using the dynamic nature of Python.

Why did I choose it ?

There are many different accounting solutions which I could have used, from my list of wanted features one can presume that I would naturally align myself with a double-entry accounting system: they are very powerful and make mistakes obvious.

Furthermore, my want for an easy way to version-control my ledger eliminates candidates like GNUCash, which make use of XML or other hard-to-version file format. The power of plain text accounting is that it is at once easy to read, write, and version, but also that I can feel confident that I will still be able to access my data in 20 years.

So, at this, point we're pretty much reduced to one of the plain text accounting software offerings. So why did I go with beancount rather than ledger or hledger ? There are three main factors which led me to this decision:

• beancount has a wonderful documentation, specifically, I was first introduced to the idea of double-entry accounting in its documentation.
• I read the author's reasoning for writing beancount instead of using ledger and hledger: I found him very reasonable, and agreed with a lot of his ideas (especially about being simpler, stricter, and being independent of any transaction ordering)
• finally, I grok python: I can dive in the source code to understand what is being done and why, I can write a few lines and submit a PR if I feel like something is missing from the base package, I can write a plug-in to customize it my exact liking.

So how do I use it?

I have only recently started using beancount, after having it been on my TODO list for 6 months. As a New Year's resolution, I finally decided to bite the bullet and start seriously using it.

The first step was importing a backlog of transactions: I opened accounts to represent my checking account, my cash on hand, my scrooge account (a special service used by the TAs to trade money between each other and buy snacks), and typed up how much money I had in each one. Importing the backlog allows me to both give some context to the amount of money I am currently holding, and have a representative set of transactions to open expense accounts and start categorising my spending.

The second step was setting up fava, which is a web-UI for beancount. This allows me to check on my accounts from any point on Earth. This meant that I had to setup syncing for my ledger file between devices, for which I am using syncthing. I have also had to make sure nobody could access the fava interface, I have accomplished the task with the help of Authelia, which I had already deployed on my server to access the syncthing interface securely.

Finally I setup a git repository, added a git hook to make sure my ledger was balanced, as well as a custom hook to make sure that it was formatted.

I am now able to input my transactions on the go using the beancount android app, and regularly using my computer to tidy them up and commit them to the repository.

What's next?

After all this work, the journey is still not done. It turns out that accounting is kind of addictive. I am yet to be accounting for my taxes from my pay slips, and still need to start tracking my Livret A opened by my parents, PEE opened by EPITA, and other future investments.

Finally, I will never be done with accounting, as there are only two things in life that are for certain: death and taxes, and only one of them is a one-time-thing.