How to Manage your Finances with Ledger Mode in Emacs

Ledger Mode is a package in Emacs for the command line accounting program Ledger. This allows Emacs users to utilize Ledger’s powerful features from the comfort of their favorite text editor.

Also read: What Is Doom Emacs and How to Install It

Why Use Ledger Mode and Do Your Bookkeeping in Emacs?

Ledger Mode is simple and intuitive to use. It automatically balances your finances and notifies you when there is any issue with your records. It also allows you to categorize your expenses and sources of income which could, then, be sorted and analyzed from the package itself.

Simply put, Ledger Mode is a brilliant addition for someone that uses Emacs as their productivity suite. It removes the need for spreadsheets while also allowing you to use the ledger data in the other parts of your Emacs experience.

Emacs works in the idea of interoperability. This means that any data produced in Emacs can be repurposed to any other package within it. In that, Ledger Mode allows its users to create and combine the data you have written for ledger to other tools in Emacs.

This allows you, for example, to create Org Mode documents that link to both archived emails and ledger files. Not only that, you can also easily copy your ledger entries to your emails and vice versa. This is all because entries in Ledger Mode are plain text and Emacs can easily move that to any buffer.

Also read: How to Use Email within Emacs

The Ledger Utility

As discussed above, Emacs’ Ledger Mode is just a way to access the Ledger command line utility. With that, it is important to know what the Ledger program is and what it can do out of the box.

Also read: How to Manage Git in Emacs with Magit

How Ledger Works

Ledger is a simple program that reads plain text ledgers and create accounting reports out of them. Unlike traditional bookkeeping programs, it does not create and modify any database files. This makes Ledger a lean and flexible solution for keeping tabs on your financial status.

The way Ledger makes this possible is that it expects each entry in the file to follow a specific format. Consider the following the example:

  2022/02/16 Expenses
    Expenses:Food:Lunch                          140 PHP
    Expenses:Food:Snack                          50  PHP
    Assets:Fiat:Cash                            -190 PHP

In here, Ledger expects three things from the plain text file:

• A title line that specifies a date and a name for the book entry. In this case, I added an Expenses entry on February 16.
• A group of accounts that shows where the money came from and where it went. In this case, I used my cash asset and I moved it to an expenses account.
• The value of money that I moved. In here, I moved my cash asset twice for my lunch and snack. However, it was all taken at once from my assets at the end of the day.

These three basic assumptions make it such that you can easily adapt Ledger to any kind of situation. For example, Ledger can deal with both currency and commodities. This makes it useful for people who are not only tracking their spending habits but also track their investments.

Also read: How to Use Emacs for RSS with Elfeed

Defining Account Categories in Ledger

One important thing to note is that the categories for each transaction in Ledger is completely arbitrary. However, the general practice of tracking personal finances can be divided into five parts:

• The Assets account are the commodities and currencies that you own. This could either be a single currency or a mixture of currencies, stocks and item inventories.
• The Expenses account are the commodities that you have purchased for with your assets.
• The Income account is where you can pull money from your sources of wealth. For example, you can attach the salary that you receive under this account.
• The Liabilities account is where you can assign all the commodities that you currently owe.
• The Equity account is a special account that you can use to determine your current net worth. This is commonly used when creating an opening balance in Ledger.

You can further specify a transaction by appending a colon (:) after each of those five categories. For example, a transaction with the label Expenses:Food:Lunch can be represented by a three level hierarchy.

Also read: 5 Hidden Features You Can Use to Improve Emacs

Installing Ledger

With that in mind, installing Ledger is simple. You can find it in the repositories of most Linux distributions. For example, you can install ledger in Debian and Ubuntu using apt:

sudo apt install ledger

For Fedora, you can use dnf:

sudo dnf install ledger

In Arch Linux, you can use pacman:

sudo pacman -S ledger

In my case, I am using Debian so I will be installing ledger through apt.

Also read: How to Use IRC in Emacs with ERC

Using Ledger Mode in Emacs

In order to use the Ledger program with Emacs, you need to install its companion package, Ledger Mode. This package is available in the default ELPA repository. As such, you can already install it through Emacs’ package manager.

1. To do that, you can press Alt + X and type package-install. This will bring up a command buffer where you can type the package that you want to add to Emacs. Type ledger-mode.
2. From there, Emacs will download and compile the package’s source code. After that, you can now use Ledger in Emacs through Ledger Mode.

Creating your First Ledger in Emacs

By default, Ledger Mode automatically enables itself when Emacs opens a file that ends with .ledger.

1. As such, you can start creating your own ledger file in Emacs by pressing Control + X, Control + F.
2. This will open a buffer where you can type the name of the file that you want to create. Type example.ledger.

3. After that, Emacs will create the “example.ledger” file in the current directory and open it for you. From here, you can then start populating your ledger file with your transactions.

Also read: How to Create Beautiful Beamer Slides with Emacs

Create your Opening Balance in Emacs

To begin tracking your finances in Ledger, you need to first provide your current balance to it. You can do that by deducting what you currently have and owe to an Equity account. For example, this is the opening balance of someone with a number of Assets and Liabilities:

  2022/02/10 * Opening Balance
    Assets:Bitcoin:Savings                     0.045 BTC
    Assets:Bitcoin:Checking               0.00050712 BTC
    Assets:Fiat:Checking                   15,000.00 PHP
    Assets:Fiat:Savings                   255,944.00 PHP
    Liabilities:Fiat:Car Loan            -450,000.00 PHP
    Liabilities:Fiat:Credit Payable        -5,000.00 PHP
    Liabilities:Fiat:Home Loan           -755,831.34 PHP
    Equity:Opening Balance

The structure of the opening Ledger entry is similar to the example above with one key difference. In here, we have added an asterisk before the entry title to tell Ledger that this transaction is already “clear”. This means that Ledger is clear to add and deduct from these accounts.

Check your Current Balance

Once done, you can now test whether Ledger detects your file properly.

1. To do that, you can press Control + C, Control + O, Control + R. This will prompt Ledger Mode to generate a report for you.
2. Type bal to display the running balance.

3. Doing that will produce a hierarchy of all of the accounts that you added to your Ledger file. All of these should, then, total to zero at the final line.

Add New Transactions

With that done, you can now add new transactions to your ledger file.

1. You can do this by pressing Control + C, Control + A. This will tell Ledger Mode that you want to create a new transaction.
2. It will, then, ask you for the date that you want this transaction to be. This is useful if you are issuing checks that will only clear after a certain date. In my case, I want to use the current date so I will press Enter here.

3. From there Ledger Mode will, then, ask you for a name of a previously logged transaction. You can use this feature if you are doing recurring payments and you just want to copy a previous transaction instead. In my case, I want to create a new transaction so I also pressed Enter here.

4. With that, Ledger Mode will create a new blank line with the current date. You can, then, add the transaction that you want to do from here. For example, I have added the following transaction after my opening balance:

  2022/02/10 * Opening Balance
   Assets:PHP:Checking                     5,000.00 PHP
   Assets:PHP:Savings                     10,000.00 PHP
   Liabilities:PHP:Credit Payable         -5,000.00 PHP
   Equity:Opening Balance
 
  2022/02/11 My First Transaction
   Expenses:Food:Snack                       250.00 PHP
   Assets:PHP:Checking                      -250.00 PHP

Also read: 5 Better USENET Readers for Linux

Generate Basic Reports

1. As discussed above, you can press Control + C, Control + O, Control + R to generate a report. Aside from bal, however, you can also use a number of other commands to generate different reports from within ledger.
2. For example, you can type account and the account’s name to create an account statement for a specific category. In my case, I typed “Assets” to create a statement for my Assets category.

3. On the other hand, you can type payee to show all the transactions titled with the string you have provided. For example, I can type “snack” to only display all the transactions with the word snack.

4. Lastly, you can type reg to produce a register report of the whole ledger. This is a more detailed balance report where Ledger tracks each commodity and how they all balance.

Congratulations! You now know how to use Emacs to aid you in tracking your finances. You also learned about the Ledger program and how you can use it to create detailed reports about your financial status.

Also read: 5 Useful Emacs Packages for Better Productivity

Frequently Asked Questions

1. Ledger is throwing an error that my ledger is not balanced. What did I do wrong?

This can be due to a number of problems. The most common one, however, is that you forgot to close a transaction in the ledger. One way to fix this is to check whether there are any transactions that do not have any negative value.

A negative value in Ledger means that you are taking an amount from an account. On the other hand, a positive value means that you are adding on to it. These two values represent an asset flow and it is required to balance your accounts in Ledger.

With that, this means that for every transaction that you will make in Ledger. You need to have a positive and a negative value.

2. Is Ledger only usable with real world assets?

Not at all. As discussed above, all the accounts used in Ledger are completely arbitrary. This means that while the examples in this guide point to real world assets, you can also use Ledger to track virtual ones.

For example, this is an excerpt from a ledger that tracks assets in a popular MMO game, EVE Online:

  2022/01/04 Venture Profits
      Main:Assets:Liquid:ISK            150,000,000.00 ISK
      Alt 1:Income:Ore Mining           -10,000,000.00 ISK
      Alt 1:Income:Station Trading      -40,000,000.00 ISK
      Alt 2:Income:Data Running (0.0)  -100,000,000.00 ISK
 
  2022/01/07 Upkeep Costs
      Alt 1:Expenses:Ship Insurance          10,000.00 ISK
      Alt 2:Expenses:New Ship            53,450,000.00 ISK
      Main:Assets:Liquid:ISK            -53,460,000.00 ISK

3. Is it possible to reverse the order of transactions similar to a bank statement?

Yes and no. You can reverse the order of transactions in the reports that Ledger makes. However, you cannot reverse the order transactions in your Ledger file. To do the former, you can press Shift + R while in a report buffer to reverse its order.

Image credit: Unsplash

Ramces Red - Staff Writer

Ramces is a technology writer that lived with computers all his life. A prolific reader and a student of Anthropology, he is an eccentric character that writes articles about Linux and anything *nix.