Adam Richardson's Site

Ledger Notes

Table of Contents

<2022-05-01 Sun>

What is…

What is Plain Text Accounting?

  • https://plaintextaccounting.org/
  • Using software the uses plain text files for accounting records
  • The primary benefit of plain text format is to ensure that account data is accessible and freely integrated with new software

What is Ledger?

  • https://www.ledger-cli.org/
  • A cli tool to parse plain text double entry accounting files
  • The ledger tool uses the UNIX design philosophy, so it provides no interface outside of the command line
  • Its primary purpose is to generate reports from ledger files
  • Ledger uses double-entry style bookkeeping
  • Ledger is written in C++ and is actively maintained
  • Created in 2003 and inspired a lot of ledger-likes, including hledger and beancount

What is double-entry bookkeeping?

  • This tracks transactions as an in (credits) and an out (debits)
  • The balance of all of your accounts should total to zero

What is hledger?

  • https://hledger.org/
  • hledger is written in Haskell and is actively maintained
  • It also has an active community producing videos on YouTube, hledger fan
  • Provides small tools to manipulate the ledger files from the command line

What is beancount?

Ledger Format

Transaction

  • A transaction starts with the date of the transaction, followed by a name
    • The format of the date should be YEAR/MONTH/DAY
  • Below the transaction line you need to indicate which account was credited and which was debited
  • You can list as many accounts as necessary indicating which had a credit and which had a debit
  • For debits you can prefix the amount with a negative symbol
  • If you only show a credit the second account will automatically be debited the amount of the credit
2021/12/26 Opening Balance
                               $50.00
    

2021/12/26 Quick-E-Mart
              $3.99
  • Transactions have can have multple state values:
    • uncleared - This is the default state
    • cleared - To mark a transaction as cleared but an asterisk after the date
    • pending - To mark a transaction as pending but an exclamation point after the date

Accounts

  • Accounts can have any format but it is common to organize them into categories
  • Categories can have sub-categories typically delimitted with a ':'
  • Ledger docs recommend 5 high level categories:
    • Expenses: where money goes
    • Assets: where money sits
    • Income: where money comes from
    • Liabilities: money you owe
    • Equity: the real value of your property
  • This command shows using ledger to view the balance of specific accounts: ledger bal -f <SOME_FILE>.ledger ^assets:checking ^assets:savings
  • Ledger will show you the total of all of those accounts
  • This is good for balancing virtual accounts with real ones

Virtual Postings

  • Using [ ] around the virtual account ensures that it must balance out to zero
  • Using ( ) does not have such a requirement
  • To generate a budget report using virual postings use the following command template ledger --empty -S -T -f <SOME_FILE>.ledger bal ^assets:budget

Strict Mode

  • Strict mode is useful to verify that only accounts that are declared are used
  • The below code block shows declaring an account and commodity
 
 
 

commodity $

Comment Characters

  • ';' is the default comment character for ledger files.
  • Additionally '#', '|', '*' and '%' are comment characters
; A normal comment
# Another type of comment
| Another type of comment
* Another type of comment
% Another type of comment

Periodic Transactions

  • A periodic transaction starts with a tilde and specifies the frequency of repetitions
  • For example ~ Monthly
  • This can be used to define a monthly budget
~ Monthly
                                   $500
                                   $450
                               $120
    

~ Yearly
                            $500

Editing Ledger Files

  • ledger-mode in emacs provides a lot of nice features when editing ledger files

Ledger Reports

  • To view the monthly budget run ledger -f <SOME_FILE>.ledger --budget --monthly register ^expenses
  • When viewing a report in ledger mode inside emacs you can edit the report with the e key
  • Editing the report allows you to change the date range you are viewing

Using multiple files

  • Ledger files can have an include statement