transactions

Description

transactions is a command line application for managing your finances using a plain text format (yaml or json). All transactions are written to a text file by hand similar to a checkbook register. This text file is your ledger and it can handle most financial bookkeeping needs.

Installation

Requirements

Before you can get started with transaction, the following must be installed on your system. Note that RubyGems is included with Ruby since version 1.9.

The best way to install transactions is via RubyGems. At the terminal prompt, run the following command:

gem install transactions

Additional Information

Using the program

  1. create a ledger file
    • you can copy and paste the example ledger below into a text file named "ledger.yaml" if you just want to try out the program. If this is your style of bookkeeping, then just edit the file with your own info using your favorite text editor.
    • run this command transactions bal and see the output.
    • by default, "transactions" looks in the current directory for a file named "ledger.yaml".
    • you can use the -f option to specify a different file (eg. transactions -f example.yaml bal)
  2. run transactions reg
    • this is a register for all transactions
    • notice that every transaction prints multiple times
      • this happens because each transaction affects multiple accounts
  3. to make the register more useful try transactions reg assets:checking
    • this will limit the register to assets:checking (case is ignored)
    • this would be equivalent to printing a checkbook register from "ledger.yaml"
    • more than one account can be included eg. assets:checking expenses:food
    • this limit by string of text also works with the balance command.
  4. see keeping a ledger below for information about general accounting principles to help you with your own ledger.

Sample Ledger File

# This is a sample ledger file
# this line and the one above are comments that will be ignored
# during processing! Comments can also be placed at the end of
# a line (see below for examples).

- date:                             2013/01/01
  transaction:                      Opening Balances
  Assets:Checking:                  251.0
  Assets:Savings:                   5005.3
  Assets:IRA:                       22510.92
  Liabilities:CreditCard:           -931.32
  Liabilities:Salliemae:            -10189.05
  Equity:OpeningBalances:           -16646.85

- date:                             2013/01/07
  transaction:                      Trader Joe's
  Expenses:Food:Groceries:          58.77
  Assets:Checking:                  -58.77

- date:                             2013/01/09
  transaction:                      Student Loan Payment
  Liabilities:Salliemae:            103.3
  Expenses:Interest:StudentLoan:    15.04
  Assets:Checking:                  -118.34

- date:                             2013/02/11
  transaction:                      Deposit Paycheck
  Assets:Checking:                  1242.87
  Income:JobName:                   -1242.87

- date:                             2013/02/11
  transaction:                      Visa Payment
  Expenses:Interest:CreditCard:     10.0
  Liabilities:CreditCard:           130.0
  Assets:Checking:                  -140.0

- date:                             2013/02/25
  transaction:                      PG&E
  Expenses:Utilities:Electric:      75
  Assets:Checking:                  -75

- date:                             2013/02/25
  transaction:                      Verizon  # Switch to Virgin Mobile
  Expenses:Phone:                   55.72
  Assets:Checking:                  -55.72

- date:                             2013/02/26
  transaction:                      Ike's Lair  # good sandwich
  Expenses:Food:Dining:             22.31
  Assets:Checking:                  -22.31

# a transaction requires only one space as a separator but can also be
# aligned as above. The choice is yours!

- date: 2013/02/26
  transaction: Money Transfer
  Assets:Savings: 494.7
  Assets:Checking: -494.7

Keeping a Ledger

Although the program doesn't limit you on naming your accounts, it is highly recommended to use some standard conventions in order to facilitate easier understanding of your finances by your accountant. The five base accounts that you should use are:

  • Assets
    • what you own
    • a debit or withdrawal will be a negative number
    • a deposit will be a positive number
  • Liabilities
    • what you owe
    • a payment towards a liability will be a positive number
    • borrowing on a liability will be a negative number
  • Equity
    • what you have accumulated over time
    • Equity = Assets - Liabilities
  • Income
    • your earnings from society
    • this will always be a negative number (seems weird but you'll get used to it)
    • think of Income as a withdrawal from society and that is why it is negative
  • Expenses
    • things you spent your assets on or incurred liabilities for
    • a purchase or expense will be a positive number
    • a return or refund will be a negative number

Everything falls under one of these five categories but also belongs in a sub-account. Sub-accounts are created by appending a colon and the name of the sub-account after one of the main accounts. Some examples for account names could then be Assets:Savings, Income:My Job, Expenses:Food:Groceries, Expenses:Food:Dining, Liabilities:Credit Card.

See the example ledger above for the complete syntax.

Start your own ledger

  1. Create an empty text file named "ledger.yaml"
  2. Enter your opening balances as the first transaction using the Equity account (see example ledger above)
    • The accounting equation that makes this work is Equity = Assets - Liabilities
    • Your Assets are positive numbers (unless your checking account is in the negative == BAD!)
    • Your Liabilities are negative since they bring down your net worth
    • The difference of your Assets and Liabilities is balanced to zero with the equity account.
    • A negative equity in our ledger means a positive net worth (your assets are greater than your liabilities).
    • A positive equity in our ledger means a negative net worth (your liabilities are greater than your assets).
  3. Enter transactions (be consistent with your account naming).
  4. The best way to be consistent is to run transactions bal to see all your accounts before creating your new entry.
  5. Transaction names can be whatever you want to help remind you of the transaction.
  6. The date is formatted as YYYY/MM/DD (this is important for the date limiting options to function)

Some (hopefully) Helpful Notes

  • Assets, Liabilities, and Equity accounts are called "Real" accounts since their balances are not zeroed out at the end of an accounting period.
    • While this is unfortunate in the case of your Liabilities, it is beneficial to your Assets.
  • Income and Expense accounts are called "Nominal" accounts since they begin at zero at the start of a new accounting period.
    • Income is used for expenses, to pay liabilities, or put into an asset account as it comes in from society and thus starts at zero every accounting period
    • Expenses start over every accounting period (you can't claim already claimed Expenses

Examples

Trial Balance - list of all accounts in the ledger and their balances

transactions balance

Balance Sheet - What you own and owe

transactions balance assets liabilities

Income Statement - measures cash flow / profitability (income vs expenses)

transactions balance income expenses

Limit by date

transactions -b 2013/01/01 -e 2013/12/31 balance
  • this will show the entire year of 2013 inclusive of the dates used as arguments.
  • the date limits work for balance, register, and print commands.
  • the totals for income and expenses will be accurate with date limits since they are nominal accounts that reset at the beginning of a new accounting period.
  • the totals for assets and liabilities are the amounts that the accounts changed during the accounting period. To see the totals that you actually have in your assets or liabilities the date limits must be left out.

Contributing

How to get your work merged into the project?

  • Fork the project.
  • Clone your fork ( git clone [email protected]:<username>/transactions.git ).
  • Create a topic branch for your change ( git checkout -b my_new_feature ).
  • Hack away, add tests. Not necessarily in that order.
  • Make sure everything still passes by running ruby test_transactions.rb from within the test directory (tests need to be run in the same directory as the included ledger.yaml file).
  • If necessary, rebase your commits into logical chunks, without errors.
  • Push the branch up ( git push origin my_new_feature ).
  • Create a pull request against randyschneck/transactions and describe what your change does and/or why you think it should be merged.

Credits

Written by Randy A. Schneck ([email protected])

see LICENSE.md