Doing Accounting in Plain Text

When it comes to personal planning, financial management is an important area worthy of a serious discourse. In this post, we seek to answer the crucial question as to whether it is possible to carry out bookkeeping or accounting on the command line.

What does Accounting Involve?

Accounting simply means to keep a record of. In financial matters, we want to track not only how much money we have on hand or at the bank, but how we are using it. Additionally, we are also interested in how much do our assets and/or liabilities weigh in monetary value.

Thus, it is important that in accounting, we use the traditional categories of accounts, namely

Assets
The things that we have.
Liabilities
The things that we owe, or anything that someone else has a claim on.
Equity
Your net worth after all liabilities are subtracted from your assets.

Additionally, you need to track your sources of money and how you spend it. So we have

Expenses
How you spend the money.
Income or revenue
Your source of money.

Plaintext Accounting

The basis of plaintext accounting is that you understand your own finances. In other words, unlike GUI-based applications such as GnuCash and Homebank where you get wizards to help you set up a chart of accounts, in plain text accounting, you are expected to be familiar with this organisation.

So your accounting is done in plain text. I use Hledger, which is based on Ledger for my accounting. As a result, I will provide its examples. However, you can learn more about plaintext accounting (PTA for short) here.

In PTA, entries are kept in a text file. You can name it whatever you like, and use any extension. For instance, with Hledger, the default place where this file is kept is in your Home directory under the name ~/.hledger.journal.

To change it, just define a new variable in your .bashrc or .zshrc file called LEDGER_FILE. Thus, a line like this will suffice:

LEDGER_FILE=~/.finance/journals/main.j

In the example above, I named my file main.j and have placed it under the journals directory, which is itself a subdirectory of the hidden directory called .finance in my home directory.

Key to working with plaintext accounting programs such as Ledger and Hledger is that each word triggers an action if it starts a line. For example,

account
Means that this line defines an account. Important when setting up your chart of accounts.
commodity
Means that this line is setting up a currency such as a US dollar, ZWL, Pound etc. You type in the name of the currency followed by how it is represented.
decimal-mark
defines how digits are separated. You can use a period (.) or a comma (,) for thousand groups.
date entry
A line that starts with a date entry such as 2022-03-11 is taken to be a journal entry. I will discuss the journal in the next section.
Semicolon
A semicolon (;) means a comment. It is ignored by the program, but is useful for humans. However, Comment lines can also be used as pointers to a program such as telling it what type of an account is being defined, or descriptions.

Naming your accounts

While it is not necessary to define a chart of accounts (COA), it is advised that you do so. This is especially useful when you would be exploring your journal or want to get a true picture of your balance sheet. Your application will place each account under the appropriate class. For example, your loan account will be placed under the Liabilities category.

So before making your very first entry in your journal, consider creating a chart of your accounts which lists all your current and potential sources of wealth and debt. When using Hledger, you can even indicate the higher level accounts using the keyword type after a comment. For example,

account Bank ; type: C

While Cash is technically an Asset account, Hledger and a program such as GnuCash often create a separate category for it.

The following are the sic types of account classes you can define in a chart of accounts. I will show you the Short and long version. You can use either, thus “type: X” is the same as “type: expense”. Note that for short forms, you use a capitalised letter.

Account type Long form Short form
Asset Asset A
Cash Cash C
Liability Liability L
Income or revenue Revenue R
Expense Expense X
Capital or Eqy Equity E

These are the types of accounts that generally act as parents to your main accounts.

So You can have an account that tracks how you buy your clothes, your vehicle repairs, home loans etc. An account name must reflect the purpose for which that account was set up. Thus, a Bank account means that this account tracks your bank savings. If you have more than one bank account, you can name them by the bank names.

From this, I think you can get the notion that accounts can be grouped

  • First, by what type of account they are (whether Asset, Liability or Equity).
  • Then by the purpose for which the account is set up. An account’s purpose shows what it tracks. It is specific to one thing and the moment you can subdivide it, consider creating a subclass for it.

This classification and subclassification is denoted by a colon. Thus, in your chart of accounts, you can represent a Phone account as an Expense this way:

account Expense ; type: X
account Expense:Phone

For a bank account, we can do the following if we have more than one bank:

account Bank ; type: C
account Bank:First Bank
account Bank:Savings Bank LTD

Keeping your journal

The basis of accounting is simple: every transaction you do affects more than one account. This is the underlying principle of the double entry system.

When you buy something, you may not think much about it, but that transaction has resulted in

  • You getting the item you wanted;
  • And you losing some money from a cash account.

So every transaction gets something and gives up something.

In GUI-based accounting software, the moment you enter a transaction, you will see that when you enter a left-hand side entry, a corresponding righthand entry will be generated. A lefthand side is called a debit side, while the right hand is called the credit side.

As to whether a side reflects a gain or a loss to the account, it depends with the type of account.

Anyway, with PTA, it is not necessary to think about which side is affected. You use a hyphen or dash to mean the debit side, and use the plus sign to mean the credit side. As for the plus sign, it is implied which means you can (and most of the time we do) leave it out.

Still, you need to know the two accounts affected by each transaction. No transaction can ever have one account!

So to denote a new transaction, you start a new line with a date entry. The date is entered in the form yyyyy-member-dd (you can use a slash or a dot instead of a dash).

After the date, there comes a description. The description can optionally show the person to whom you were paying (the payee). You use a vertical bar to separate the description from the payee or payer.

Below the date line, there follows entries for this transaction.

  • Each entry is indented below its date line entry.
  • You enter one entry per line.
  • Each entry is constituted of an account followed by the amount for that account.

Thus, each transaction has at least three lines: the first being the date and the description, the next two lines each contain an account receiving an amount, and another giving the amount. For example,

2022-03-11 Receiving my weekly wages | Jones Factory
  Bank 100
  Revenue:Wages: -100

In the above transaction, you will see that

  • It was conducted on 11 March 2022.
  • From the description, we learn that it is a payment of a wage for the week.
  • From the optional bar, we know that the payer is Jones Factory.
  • Below the date entry, we have two entries that are indented.
  • The first one of this shows that the Bank account got $100. (the currency is not indicated.)
  • The entry below it shows that the Revenue:Salary account was debited with the same amount. This is indicated by the -100.

Entering more than one entry per transaction

A transaction can generate more than two entries when either of these conditions is true:

  • A giving account splits the amount into more than one account.
  • A receiving account receives its final balance from more than one account.

Whichever the case is, when you have more than two entries in a transaction, you have to make sure that one of those accounts balances the others. For example, \(10+20+30=60\)

hence, three accounts added up to sixty dollars, as in the following transaction:

2022-03-09 Buying Stationery | Stationery Booth LTD
  Expense:Education:Textbooks       30
  Expense:Education:Satchel     20
  Expense:Education:Exercise Books      10
  Bank             -60

It is an error when your accounts do not balance. So make sure that your recordings are accurate.

Transactions with more than one entry include transactions that reckon taxes, and bank charges.

Leaving out amounts

Whether you have only two entries or more, for both Ledger and Hledger, it is sufficient to just enter an amount for one account entry and the other is implied. Thus, for our weekly wage, we could have written it like this:

2022-03-11 Weekly Wages | Jones Factory
  Bank 100
  Revenue:Salary 

This is even true for transactions with more than two entries: Just enter amounts for the partial accounts and leave out the balancing amount like this:

2022-03-09 Buying stationery | Stationery Booth LTD
  Expense:Education:Textbooks     30
  Expense:Education:Satchel      20
  Expense:Education:Exercise Books   10
  Bank

Conclusion

Plaintext accounting is possible and in fact makes you understand not only how your program works, but even how your assets and liabilities balance each other. This post hopefully introduced you to a world of possibilities with both pure text and accounting.