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.
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.
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.
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.
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.
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.
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.
- 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
- 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.
- As such, you can start creating your own ledger file in Emacs by pressing Control + X, Control + F.
- This will open a buffer where you can type the name of the file that you want to create. Type
- 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.
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.
- To do that, you can press Control + C, Control + O, Control + R. This will prompt Ledger Mode to generate a report for you.
balto display the running balance.
- 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.
- You can do this by pressing Control + C, Control + A. This will tell Ledger Mode that you want to create a new transaction.
- 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.
- 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.
- 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
Generate Basic Reports
- 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.
- For example, you can type
accountand 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.
- On the other hand, you can type
payeeto 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.
- Lastly, you can type
regto 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.
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
Our latest tutorials delivered straight to your inbox