Overview
********

Ledger is a command line accounting tool that provides double-entry accounting based on a text journal.  It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father's CRT.

Copying
*******

Copyright (c) 2003-2011, John Wiegley.  All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

- Neither the name of New Artisans LLC nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Introduction to Ledger
**********************

Fat-free Accounting
===================

Ledger is an accounting tool with the moxie to exist.  It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father's CRT.

What it does offer is a double-entry accounting journal with all the flexibility and muscle of its modern day cousins, without any of the fat.  Think of it as the Bran Muffin of accounting tools.

To use it, you need to start keeping a journal.  This is the basis of all accounting, and if you haven't started yet, now is the time to learn.  The little booklet that comes with your checkbook is a journal, so we'll describe double-entry accounting in terms of that.  If you use another GUI accounting program like GNUCash, the vast majority of its functionality is geared towards helping you keep a journal.

A checkbook journal records debits (subtractions, or withdrawals) and credits (additions, or deposits) with reference to a single account: the checking account.  Where the money comes from, and where it goes to, are described in the payee field, where you write the person or company's name.  The ultimate aim of keeping a checkbook journal is to know how much money is available to spend.  That's really the aim of all journals.

What computers add is the ability to walk through these postings, and tell you things about your spending habits; to let you devise budgets and get control over your spending; to squirrel away money into virtual savings account without having to physically move money around; etc.  As you keep your journal, you are recording information about your life and habits, and sometimes that information can start telling you things you aren't aware of.  Such is the aim of all good accounting tools.

The next step up from a checkbook journal, is a journal that keeps track of all your accounts, not just checking.  In such a journal, you record not only who gets paid---in the case of a debit---but where the money came from.  In a checkbook journal, its assumed that all the money comes from your checking account.  But in a general journal, you write posting two-lines: the source account and target account. There must always be a debit from at least one account for every credit made to another account.  This is what is meant by ``double-entry'' accounting: the journal must always balance to zero, with an equal number of debits and credits.

For example, let's say you have a checking account and a brokerage account, and you can write checks from both of them.  Rather than keep two checkbooks, you decide to use one journal for both.  In this general journal you need to record a payment to Pacific Bell for your monthly phone bill, and a transfer (via check) from your brokerage account to your checking account.  The Pacific Bell bill is $23.00, let's say, and you want to pay it from your checking account.  In the general journal you need to say where the money came from, in addition to where it's going to.  These transactions might look like this:

     9/29        Pacific Bell                $23.00     $23.00
                 Checking                   $-23.00          0
     9/30        Checking                   $100.00    $100.00
           (123) Brokerage                 $-100.00          0

The posting must balance to $0: $23 went to Pacific Bell, $23 came from Checking.  The next entry shows check number 123 written against your brokerage account, transfering money to your checking account.  There is nothing left over to be accounted for, since the money has simply moved from one account to another in both cases.  This is the basis of double-entry accounting: money never pops in or out of existence; it is always a posting from one account to another.

Keeping a general journal is the same as keeping two separate journals: One for Pacific Bell and one for Checking.  In that case, each time a payment is written into one, you write a corresponding withdrawal into the other.  This makes it easier to write in a ``running balance'', since you don't have to look back at the last time the account was referenced---but it also means having a lot of journal books, if you deal with multiple accounts.

Here is a good place for an aside on the use of the word `account'. Most private people consider an account to be something that holds money at an institution for them.  Ledger uses a more general definition of the word.  An account is anywhere money can go.  Other finance programs use ``categories'', Ledger uses accounts. So, for example, if you buy some groceries at Trader Joe's then more groceries at Whole Foods Markets you might assign the transactions like this

     2011/03/15   Trader Joe's
           Expenses:Groceries   $100.00
           Assets:Checking
     2011/03/15   Whole Food Market
           Expenses:Groceries   $75.00
           Assets:Checking

In both cases the money goes to the ``Groceries'' account, even though the payees were different.  You can set up your accounts in any way you choose.

Enter the beauty of computerized accounting.  The purpose of the Ledger program is to make general journal accounting simple, by keeping track of the balances for you.  Your only job is to enter the postings.  If an individual posting does not balance, Ledger displays an error and indicates the incorrect posting. (In some special cases, it automatically balances this transaction for you.)

In summary, there are two aspects of Ledger use: updating the journal data file, and using the Ledger tool to view the summarized result of your transactions.

And just for the sake of example---as a starting point for those who want to dive in head-first---here are the journal transactions from above, formatted as the Ledger program wishes to see them:

     2004/09/29 Pacific Bell
          Expenses:Pacific Bell              $23.00
          Assets:Checking

The account balances and registers in this file, if saved as ledger.dat, could be reported using:

     $ ledger -f ledger.dat balance
     $ ledger -f ledger.dat register checking
     $ ledger -f ledger.dat register Bell

An important difference between Ledger and other finance packages is that journal will never alter your input file.  You can create and edit that file in any way you prefer, but journal is only for analyzing the data, not for altering it.

Building the program
====================

Ledger is written in ANSI C++, and should compile on any platform.  It depends on the GNU multiprecision integer library (libgmp), and the Perl regular expression library (libpcre).  It was developed using GNU make and gcc 3.3, on a PowerBook running OS/X.

To build and install once you have these libraries on your system, enter these commands:

     ./configure && make install

Getting help
============

If you need help on how to use Ledger, or run into problems, you can join the Ledger mailing list at the following Web address:

     http://groups.google.com/group/ledger-cli

You can also find help at the #ledger channel on the IRC server irc.freenode.net.

Ledger Tutorial
***************

Start a Journal File
====================

A journal is a record of your financial transactions and will be central to using Ledger.  For now we just want to get a taste of what Ledger can do.  An example journal is included with the source code distribution, called drewr3.dat (see Example Data File). Copy it someplace convenient and open up a terminal window in that directory.

If you would rather start with your own journal right away please skip to see Keeping a Journal.

Run a Few Reports
=================

Balance Report
--------------

To find the balances of all of your accounts, run this command:

     ledger -f drewr3.dat balance

Ledger will generate:

              $ -3,804.00  Assets
               $ 1,396.00    Checking
                  $ 30.00      Business
              $ -5,200.00    Savings
              $ -1,000.00  Equity:Opening Balances
               $ 6,654.00  Expenses
               $ 5,500.00    Auto
                  $ 20.00    Books
                 $ 300.00    Escrow
                 $ 334.00    Food:Groceries
                 $ 500.00    Interest:Mortgage
              $ -2,030.00  Income
              $ -2,000.00    Salary
                 $ -30.00    Sales
                 $ -63.60  Liabilities
                 $ -20.00    MasterCard
                 $ 200.00    Mortgage:Principal
                $ -243.60    Tithe
     --------------------
                $ -243.60

Showing you the balance of all accounts.  Options and search terms can pare this down to show only the accounts you want.

A more useful report is to show only your Assets and Liabilities:

     $ ledger -f drewr3.dat balance Assets Liabilities
              $ -3,804.00  Assets
               $ 1,396.00    Checking
                  $ 30.00      Business
              $ -5,200.00    Savings
                 $ -63.60  Liabilities
                 $ -20.00    MasterCard
                 $ 200.00    Mortgage:Principal
                $ -243.60    Tithe
     --------------------
              $ -3,867.60

Register Report
---------------

To show all transactions and a running total:

     ledger -f drewr3.dat register

Ledger will generate:

     10-Dec-01 Checking balance      Assets:Checking          $ 1,000.00   $ 1,000.00
                                     Equity:Opening Balances  $ -1,000.00            0
     10-Dec-20 Organic Co-op         Expense:Food:Groceries      $ 37.50      $ 37.50
                                     Expense:Food:Groceries      $ 37.50      $ 75.00
                                     Expense:Food:Groceries      $ 37.50     $ 112.50
                                     Expense:Food:Groceries      $ 37.50     $ 150.00
                                     Expense:Food:Groceries      $ 37.50     $ 187.50
                                     Expense:Food:Groceries      $ 37.50     $ 225.00
                                     Assets:Checking           $ -225.00            0
     10-Dec-28 Acme Mortgage         Lia:Mortgage:Principal     $ 200.00     $ 200.00
                                     Expe:Interest:Mortgage     $ 500.00     $ 700.00
                                     Expenses:Escrow            $ 300.00   $ 1,000.00
                                     Assets:Checking         $ -1,000.00            0
     11-Jan-02 Grocery Store         Expense:Food:Groceries      $ 65.00      $ 65.00
                                     Assets:Checking            $ -65.00            0
     11-Jan-05 Employer              Assets:Checking          $ 2,000.00   $ 2,000.00
                                     Income:Salary           $ -2,000.00            0
                                     (Liabilities:Tithe)       $ -240.00    $ -240.00
     11-Jan-14 Bank                  Assets:Savings             $ 300.00      $ 60.00
                                     Assets:Checking           $ -300.00    $ -240.00
     11-Jan-19 Grocery Store         Expense:Food:Groceries      $ 44.00    $ -196.00
                                     Assets:Checking            $ -44.00    $ -240.00
     11-Jan-25 Bank                  Assets:Checking          $ 5,500.00   $ 5,260.00
                                     Assets:Savings          $ -5,500.00    $ -240.00
     11-Jan-25 Tom's Used Cars       Expenses:Auto            $ 5,500.00   $ 5,260.00
                                     Assets:Checking         $ -5,500.00    $ -240.00
     11-Jan-27 Book Store            Expenses:Books              $ 20.00    $ -220.00
                                     Liabilities:MasterCard     $ -20.00    $ -240.00
     11-Dec-01 Sale                  Asse:Checking:Business      $ 30.00    $ -210.00
                                     Income:Sales               $ -30.00    $ -240.00
                                     (Liabilities:Tithe)         $ -3.60    $ -243.60

To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for:

     $ ledger -f drewr3.dat register Groceries
     10-Dec-20 Organic Co-op         Expense:Food:Groceries      $ 37.50      $ 37.50
                                     Expense:Food:Groceries      $ 37.50      $ 75.00
                                     Expense:Food:Groceries      $ 37.50     $ 112.50
                                     Expense:Food:Groceries      $ 37.50     $ 150.00
                                     Expense:Food:Groceries      $ 37.50     $ 187.50
                                     Expense:Food:Groceries      $ 37.50     $ 225.00
     11-Jan-02 Grocery Store         Expense:Food:Groceries      $ 65.00     $ 290.00
     11-Jan-19 Grocery Store         Expense:Food:Groceries      $ 44.00     $ 334.00

Which matches the balance reported for the Groceries account:

     $ ledger -f drewr3.dat balance Groceries
                 $ 334.00  Expenses:Food:Groceries

If you would like to find transaction to only a certain payee use payee or @:

     $ ledger -f drewr3.dat register payee "Organic"
     10-Dec-20 Organic Co-op         Expense:Food:Groceries      $ 37.50      $ 37.50
                                     Expense:Food:Groceries      $ 37.50      $ 75.00
                                     Expense:Food:Groceries      $ 37.50     $ 112.50
                                     Expense:Food:Groceries      $ 37.50     $ 150.00
                                     Expense:Food:Groceries      $ 37.50     $ 187.50
                                     Expense:Food:Groceries      $ 37.50     $ 225.00
                                     Assets:Checking           $ -225.00            0

Cleared Report
--------------

A very useful report is to show what your obligations are versus what expenditures have actually been recorded.  It can take several days for a check to clear, but you should treat it as money spent.  The cleared report shows just that:

     $ ledger -f drewr3.dat cleared
          $ -3,804.00            $ 775.00                 Assets
           $ 1,396.00            $ 775.00    10-Dec-20      Checking
              $ 30.00                   0                     Business
          $ -5,200.00                   0                   Savings
          $ -1,000.00         $ -1,000.00    10-Dec-01    Equity:Opening Balances
           $ 6,654.00            $ 225.00                 Expenses
           $ 5,500.00                   0                   Auto
              $ 20.00                   0                   Books
             $ 300.00                   0                   Escrow
             $ 334.00            $ 225.00    10-Dec-20      Food:Groceries
             $ 500.00                   0                   Interest:Mortgage
          $ -2,030.00                   0                 Income
          $ -2,000.00                   0                   Salary
             $ -30.00                   0                   Sales
             $ -63.60                   0                 Liabilities
             $ -20.00                   0                   MasterCard
             $ 200.00                   0                   Mortgage:Principal
            $ -243.60                   0                   Tithe
     ----------------  ----------------    ---------
            $ -243.60                   0

The first column shows the outstanding balance, the second column show the ``cleared'' balance.

Using the Windows Command Line
------------------------------

Using ledger under the windows command shell has one significant limitation.  CMD.exe is limited to standard ASCII characters and as such cannot display any currency symbols other than dollar signs ($).

Command Line Quick Reference
============================

Reporting Commands
------------------

Report   Description
balance   Show account balances
register   Show all transactions with running total
print    Print transaction in a ledger readable format
output    Similar to print without included transactions
xml   Produce XML output of the register command
emacs   Produce emacs lisp output
equity   Print account balances as transactions
prices   Print price history for matching commodities
pricedb   Print price history for matching commodities in ledger readable format
xact    Used to generate transactions based on previous postings

Basic Options
-------------

Short   Long   Description
-h   --help   prints summary of all options
-v   --version   prints version of ledger executable
-f FILE   --file FILE   read FILE as a ledger file
-o FILE   --output FILE   redirects output to FILE
-i FILE   --init-file FILE   specify options file
-a NAME   --account NAME   specify default account name for QIF file postings

Report Filtering
----------------

Short   Long   Description
-c   --current   Display transaction on or before the current date
-b DATE   --begin DATE   Begin reports on or after DATE
-e DATE   --end DATE   Limits end date od transactions for report
-p STR   --period   Set report period to STR
    --period-sort   Sort postings within each period
-C   --cleared   Display only cleared postings
-U   --uncleared   Display only uncleared postings
-R   --real   Display only real postings
-L   --actual   Displays only actual postings, not automated
-r   --related   Display related postings
--budget   Display how close your postings meet your budget
--add-budget   Shows unbudgeted postings
--unbudgeted   Shows only unbudgeted postings
--forecast   Project balances into the future
-l EXPR   --limit EXPR   Limits postings in calculations
-t EXPR   --amount   Change value expression reported in register report
-T EXPR   --total   Change the value expression used for ``totals'' column in register and balance reports

Output Customization
--------------------

Short   Long   Description
-n   --collapse   Collapse transactions with multiple postings
-s   --subtotal   Report register as a single subtotal
-P   --by-payee   Report subtotals by payee
-x   --comm-as-payee   Change the payee of every posting to be the commodity used in that posting
-E   --empty   Include empty accounts in report
-W   --weekly   Report posting totals by week
-Y   --yearly   Report posting totals by year
--dow   report Posting totals by day of week
-S EXPR   --sort EXPR   Sorts a report using EXPR
-w   --wide   Assume 132 columns instead of 80
--head N   Report the first N postings
--tail N   Report the last N postings
--pager prog   Direct output prog pager program
-A   --average   Reports average posting value
-D   --deviation   Reports each posting deviation from the average
-%   --percent   Show subtotals in the balance report as percentages
--pivot TAG   produce a pivot table of the tag type specified
-j   --amount-data   Show only date and value column
-J   --total-data   Show only dates and totals
-d EXPR   --display EXPR   Limit only the display of certain postings
-y STR   --date-format STR   Change the basic date format used in reports
-F STR   --format STR   Set reporting format
--balance-format STR
--register-format STR
--print-format STR
-j register   --plot-amount-format STR
-J register   --plot-total-format STR
--equity-format STR
--prices-format STR
-w register   --wide-register-format STR
--anon    Print the ledger register with anonymized accounts and payees, usefule for filing bug reports

Grouping Options
----------------

Short   Long   Description
-P   --by-payee   Group postings by common payee names
-D   --daily    Group postings by day
-W   --weekly   Group postings by week
-M   --Monthly   Group postings by month
--quarterly    Group postings by quarter
-Y   --yearly    Group postings by year
-dow Group by day of weeks
-s   --subtotal   Group posting together, similar to balance report

Commodity Reporting
-------------------

Short   Long   Description
--price-db FILE   Use FILE for retrieving downloaded commodity prices
-L MINS   --price-exp MINS   Set expected freshness of prices in minutes
-Q   --download   Download quotes using getquote
-O   --quantity    Report commodity totals without conversion
-B   --basis   Report cost basis
-V   --market   Report last known market value
-G   --gain    Report net gain loss for commodities that have a price history

Principles of Accounting with Ledger
************************************

Accounting with Ledger
======================

Accounting is simply tracking your money.  It can range from nothing, and just waiting for automatic overdraft protection to kick in, or not, to a full blown double entry accounting system.  Ledger accomplishes the latter.  With ledger you can handle your personal finances or you businesses.  Double-entry accounting scales.

Stating where money goes
========================

Accountants will talk of ``credits'' and ``debits'', but the meaning is often different from the layman's understanding.  To avoid confusion, Ledger uses only subtractions and additions, although the underlying intent is the same as standard accounting principles.

Recall that every posting will involve two or more accounts. Money is transferred from one or more accounts to one or more other accounts.  To record the posting, an amount is subtracted from the source accounts, and added to the target accounts.

In order to write a Ledger transaction correctly, you must determine where the money comes from and where it goes to.  For example, when you are paid a salary, you must add money to your bank account and also subtract it from an income account:

     9/29  My Employer
         Assets:Checking                           $500.00
         Income:Salary                            $-500.00

Why is the Income a negative figure?  When you look at the balance totals for your ledger, you may be surprised to see that Expenses are a positive figure, and Income is a negative figure.  It may take some getting used to, but to properly use a general ledger you must think in terms of how money moves.  Rather than Ledger ``fixing'' the minus signs, let's understand why they are there.

When you earn money, the money has to come from somewhere.  Let's call that somewhere ``society''.  In order for society to give you an income, you must take money away (withdraw) from society in order to put it into (make a payment to) your bank.  When you then spend that money, it leaves your bank account (a withdrawal) and goes back to society (a payment).  This is why Income will appear negative---it reflects the money you have drawn from society---and why Expenses will be positive---it is the amount you've given back.  These additions and subtractions will always cancel each other out in the end, because you don't have the ability to create new money: it must always come from somewhere, and in the end must always leave.  This is the beginning of economy, after which the explanation gets terribly difficult.

Based on that explanation, here's another way to look at your balance report: every negative figure means that that account or person or place has less money now than when you started your ledger; and every positive figure means that that account or person or place has more money now than when you started your ledger.  Make sense?

Assets and Liabilities
======================

Assets are money that you have, and Liabilities are money that you owe.  ``Liabilities'' is just a more inclusive name for Debts.

An Asset is typically increased by transferring money from an Income account, such as when you get paid.  Here is a typical transaction:

     2004/09/29  My Employer
         Assets:Checking               $500.00
         Income:Salary

Money, here, comes from an Income account belonging to ``My Employer'', and is transferred to your checking account.  The money is now yours, which makes it an Asset.

Liabilities track money owed to others.  This can happen when you borrow money to buy something, or if you owe someone money.  Here is an example of increasing a MasterCard liability by spending money with it:

     2004/09/30  Restaurant
         Expenses:Dining                $25.00
         Liabilities:MasterCard

The Dining account balance now shows $25 spent on Dining, and a corresponding $25 owed on the MasterCard---and therefore shown as $-25.00.  The MasterCard liability shows up as negative because it offsets the value of your assets.

The combined total of your Assets and Liabilities is your net worth. So to see your current net worth, use this command:

     ledger balance ^assets ^liabilities

Relatedly, your Income accounts show up negative, because they transfer money from an account in order to increase your assets.  Your Expenses show up positive because that is where the money went to.  The combined total of Income and Expenses is your cash flow.  A positive cash flow means you are spending more than you make, since income is always a negative figure.  To see your current cash flow, use this command:

     ledger balance ^income ^expenses

Another common question to ask of your expenses is: How much do I spend each month on X?  Ledger provides a simple way of displaying monthly totals for any account.  Here is an example that summarizes your monthly automobile expenses:

     ledger -M register expenses:auto

This assumes, of course, that you use account names like Expenses:Auto:Gas and Expenses:Auto:Repair.

Tracking reimbursable expenses
------------------------------

Sometimes you will want to spend money on behalf of someone else, which will eventually get repaid.  Since the money is still ``yours'', it is really an asset.  And since the expenditure was for someone else, you don't want it contaminating your Expenses reports.  You will need to keep an account for tracking reimbursements.

This is fairly easy to do in ledger.  When spending the money, spend it to your Assets:Reimbursements, using a different account for each person or business that you spend money for.  For example:

     2004/09/29  Circuit City
         Assets:Reimbursements:Company XYZ     $100.00
         Liabilities:MasterCard

This shows $100.00 spent on a MasterCard at Circuit City, with the expense was made on behalf of Company XYZ.  Later, when Company XYZ pays the amount back, the money will transfer from that reimbursement account back to a regular asset account:

     2004/09/29  Company XYZ
         Assets:Checking                       $100.00
         Assets:Reimbursements:Company XYZ

This deposits the money owed from Company XYZ into a checking account, presumably because they paid the amount back with a check.

But what to do if you run your own business, and you want to keep track of expenses made on your own behalf, while still tracking everything in a single ledger file?  This is more complex, because you need to track two separate things: 1) The fact that the money should be reimbursed to you, and 2) What the expense account was, so that you can later determine where your company is spending its money.

This kind of posting is best handled with mirrored postings in two different files, one for your personal accounts, and one for your company accounts.  But keeping them in one file involves the same kinds of postings, so those are what is shown here.  First, the personal transaction, which shows the need for reimbursement:

     2004/09/29  Circuit City
         Assets:Reimbursements:Company XYZ     $100.00
         Liabilities:MasterCard

This is the same as above, except that you own Company XYZ, and are keeping track of its expenses in the same ledger file.  This transaction should be immediately followed by an equivalent transaction, which shows the kind of expense, and also notes the fact that $100.00 is now payable to you:

     2004/09/29  Circuit City
         Company XYZ:Expenses:Computer:Software      $100.00
         Company XYZ:Accounts Payable:Your Name

This second transaction shows that Company XYZ has just spent $100.00 on software, and that this $100.00 came from Your Name, which must be paid back.

These two transactions can also be merged, to make things a little clearer. Note that all amounts must be specified now:

     2004/09/29  Circuit City
         Assets:Reimbursements:Company XYZ         $100.00
         Liabilities:MasterCard                   $-100.00
         Company XYZ:Expenses:Computer:Software    $100.00
         Company XYZ:Accounts Payable:Your Name   $-100.00

To ``pay back'' the reimbursement, just reverse the order of everything, except this time drawing the money from a company asset, paying it to accounts payable, and then drawing it again from the reimbursement account, and paying it to your personal asset account. It's easier shown than said:

     2004/10/15  Company XYZ
         Assets:Checking                           $100.00
         Assets:Reimbursements:Company XYZ        $-100.00
         Company XYZ:Accounts Payable:Your Name    $100.00
         Company XYZ:Assets:Checking              $-100.00

And now the reimbursements account is paid off, accounts payable is paid off, and $100.00 has been effectively transferred from the company's checking account to your personal checking account.  The money simply ``waited''---in both Assets:Reimbursements:Company XYZ, and Company XYZ:Accounts Payable:Your Name---until such time as it could be paid off.

The value of tracking expenses from both sides like that is that you do not contaminate your personal expense report with expenses made on behalf of others, while at the same time making it possible to generate accurate reports of your company's expenditures.  It is more verbose than just paying for things with your personal assets, but it gives you a very accurate information trail.

The advantage to keep these doubled transactions together is that they always stay in sync.  The advantage to keeping them apart is that it clarifies the transfer's point of view.  To keep the postings in separate files, just separate the two transactions that were joined above. For example, for both the expense and the pay-back shown above, the following four transactions would be created.  Two in your personal ledger file:

     2004/09/29  Circuit City
         Assets:Reimbursements:Company XYZ     $100.00
         Liabilities:MasterCard               $-100.00

     2004/10/15  Company XYZ
         Assets:Checking                       $100.00
         Assets:Reimbursements:Company XYZ    $-100.00

And two in your company ledger file:

     !account Company XYZ

     2004/09/29  Circuit City
         Expenses:Computer:Software            $100.00
         Accounts Payable:Your Name           $-100.00

     2004/10/15  Company XYZ
         Accounts Payable:Your Name            $100.00
         Assets:Checking                      $-100.00

     !end

(Note: The !account above means that all accounts mentioned in the file are children of that account.  In this case it means that all activity in the file relates to Company XYZ).

After creating these transactions, you will always know that $100.00 was spent using your MasterCard on behalf of Company XYZ, and that Company XYZ spent the money on computer software and paid it back about two weeks later.

Typical queries
===============

A query such as the following shows all expenses since last October, sorted by total:

     ledger -b "last oct" -s -S T bal ^expenses

From left to right the options mean: Show transactions since October, 2003; show all sub-accounts; sort by the absolute value of the total; and report the balance for all expenses.

Reporting monthly expenses
--------------------------

The following query makes it easy to see monthly expenses, with each month's expenses sorted by the amount:

     ledger -M --period-sort t reg ^expenses

Now, you might wonder where the money came from to pay for these things.  To see that report, add -r, which shows the ``related account'' postings:

     ledger -M --period-sort t -r reg ^expenses

But maybe this prints too much information.  You might just want to see how much you're spending with your MasterCard.  That kind of query requires the use of a display predicate, since the postings calculated must match ^expenses, while the postings displayed must match mastercard.  The command would be:

     ledger -M -r -d /mastercard/ reg ^expenses

This query says: Report monthly subtotals; report the ``related account'' postings; display only related postings whose account matches mastercard, and base the calculation on postings matching ^expenses.

This works just as well for report the overall total, too:

     ledger -s -r -d /mastercard/ reg ^expenses

The -s option subtotals all postings, just as -M subtotaled by the month.  The running total in both cases is off, however, since a display expression is being used.

Visualizing with Gnuplot
------------------------

If you have Gnuplot installed, you can graph any of the above register reports.  The script to do this is included in the ledger distribution, and is named scripts/report.  Install report anywhere along your PATH, and then use report instead of ledger when doing a register report.  The only thing to keep in mind is that you must specify -j or -J to indicate whether Gnuplot should plot the amount, or the running total.  For example, this command plots total monthly expenses made on your MasterCard.

     report -j -M -r -d /mastercard/ reg ^expenses

The report script is a very simple Bourne shell script, that passes a set of scripted commands to Gnuplot.  Feel free to modify the script to your liking, since you may prefer histograms to line plots, for example.

Typical plots
.............

Here are some useful plots:

     report -j -M reg ^expenses         # monthly expenses
     report -J reg checking             # checking account balance
     report -J reg ^income ^expenses    # cash flow report

     # net worth report, ignoring non-$ postings

     report -J -l "Ua>={\$0.01}" reg ^assets ^liab

     # net worth report starting last February.  the use of a display
     # predicate (-d) is needed, otherwise the balance will start at
     # zero, and thus the y-axis will not reflect the true balance

     report -J -l "Ua>={\$0.01}" -d "d>=[last feb]" reg ^assets ^liab

The last report uses both a calculation predicate (-l) and a display predicate (-d).  The calculation predicates limits the report to postings whose amount is greater than $1 (which can only happen if the posting amount is in dollars).  The display predicate limits the transactions displayed to just those since last February, even those transactions from before then will be computed as part of the balance.

Commodities and Currencies
==========================

Ledger makes no assumptions about the commodities you use; it only requires that you specify a commodity.  The commodity may be any non-numeric string that does not contain a period, comma, forward slash or at-sign.  It may appear before or after the amount, although it is assumed that symbols appearing before the amount refer to currencies, while non-joined symbols appearing after the amount refer to commodities.  Here are some valid currency and commodity specifiers:

     $20.00         ; currency: twenty US dollars
     40 AAPL        ; commodity: 40 shares of Apple stock
     60 DM          ; currency: 60 Deutsch Mark
     £50            ; currency: 50 British pounds
     50 EUR         ; currency: 50 Euros (or use appropriate symbol)

Ledger will examine the first use of any commodity to determine how that commodity should be printed on reports.  It pays attention to whether the name of commodity was separated from the amount, whether it came before or after, the precision used in specifying the amount, whether thousand marks were used, etc.  This is done so that printing the commodity looks the same as the way you use it.

An account may contain multiple commodities, in which case it will have separate totals for each.  For example, if your brokerage account contains both cash, gold, and several stock quantities, the balance might look like:

       $200.00
     100.00 AU
       AAPL 40
      BORL 100
      FEQTX 50  Assets:Brokerage

This balance report shows how much of each commodity is in your brokerage account.

Sometimes, you will want to know the current street value of your balance, and not the commodity totals.  For this to happen, you must specify what the current price is for each commodity.  The price can be any commodity, in which case the balance will be computed in terms of that commodity.  The usual way to specify prices is with a price history file, which might look like this:

     P 2004/06/21 02:18:01 FEQTX $22.49
     P 2004/06/21 02:18:01 BORL $6.20
     P 2004/06/21 02:18:02 AAPL $32.91
     P 2004/06/21 02:18:02 AU $400.00

Specify the price history to use with the --price-db option, with the -V option to report in terms of current market value:

     ledger --price-db prices.db -V balance brokerage

The balance for your brokerage account will be reported in US dollars, since the prices database uses that currency.

     $40880.00  Assets:Brokerage

You can convert from any commodity to any other commodity.  Let's say you had $5000 in your checking account, and for whatever reason you wanted to know many ounces of gold that would buy, in terms of the current price of gold:

     ledger -T "{1 AU}*(O/P{1 AU})" balance checking

Although the total expression appears complex, it is simply saying that the reported total should be in multiples of AU units, where the quantity is the account total divided by the price of one AU.  Without the initial multiplication, the reported total would still use the dollars commodity, since multiplying or dividing amounts always keeps the left value's commodity.  The result of this command might be:

     14.01 AU  Assets:Checking

Commodity price histories
-------------------------

Whenever a commodity is purchased using a different commodity (such as a share of common stock using dollars), it establishes a price for that commodity on that day.  It is also possible, by recording price details in a ledger file, to specify other prices for commodities at any given time.  Such price transactions might look like those below:

     P 2004/06/21 02:17:58 TWCUX $27.76
     P 2004/06/21 02:17:59 AGTHX $25.41
     P 2004/06/21 02:18:00 OPTFX $39.31
     P 2004/06/21 02:18:01 FEQTX $22.49
     P 2004/06/21 02:18:02 AAPL $32.91

By default, ledger will not consider commodity prices when generating its various reports.  It will always report balances in terms of the commodity total, rather than the current value of those commodities. To enable pricing reports, use one of the commodity reporting options.

Commodity equivalencies
-----------------------

Sometimes a commodity has several forms which are all equivalent.  An example of this is time.  Whether tracked in terms of minutes, hours or days, it should be possible to convert between the various forms. Doing this requires the use of commodity equivalencies.

For example, you might have the following two postings, one which transfers an hour of time into a Billable account, and another which decreases the same account by ten minutes.  The resulting report will indicate that fifty minutes remain:

     2005/10/01 Work done for company
         Billable:Client                 1h
         Project:XYZ

     2005/10/02 Return ten minutes to the project
         Project:XYZ                    10m
         Billable:Client

Reporting the balance for this ledger file produces:

            50.0m  Billable:Client
           -50.0m  Project:XYZ

This example works because ledger already knows how to handle seconds, minutes and hours, as part of its time tracking support.  Defining other equivalencies is simple.  The following is an example that creates data equivalencies, helpful for tracking bytes, kilobytes, megabytes, and more:

     C 1.00 Kb = 1024 b
     C 1.00 Mb = 1024 Kb
     C 1.00 Gb = 1024 Mb
     C 1.00 Tb = 1024 Gb

Each of these definitions correlates a commodity (such as Kb) and a default precision, with a certain quantity of another commodity. In the above example, kilobytes are reporetd with two decimal places of precision and each kilobyte is equal to 1024 bytes.

Equivalency chains can be as long as desired.  Whenever a commodity would report as a decimal amount (less than 1.00), the next smallest commodity is used.  If a commodity could be reported in terms of a higher commodity without resulting to a partial fraction, then the larger commodity is used.

Accounts and Inventories
========================

Since Ledger's accounts and commodity system is so flexible, you can have accounts that don't really exist, and use commodities that no one else recognizes.  For example, let's say you are buying and selling various items in EverQuest, and want to keep track of them using a ledger.  Just add items of whatever quantity you wish into your EverQuest account:

     9/29  Get some stuff at the Inn
         Places:Black's Tavern                   -3 Apples
         Places:Black's Tavern                   -5 Steaks
         EverQuest:Inventory

Now your EverQuest:Inventory has 3 apples and 5 steaks in it.  The amounts are negative, because you are taking from Black's Tavern in order to add to your Inventory account.  Note that you don't have to use Places:Black's Tavern as the source account.  You could use EverQuest:System to represent the fact that you acquired them online.  The only purpose for choosing one kind of source account over another is for generate more informative reports later on.  The more you know, the better analysis you can perform.

If you later sell some of these items to another player, the transaction would look like:

     10/2  Sturm Brightblade
         EverQuest:Inventory                     -2 Steaks
         EverQuest:Inventory                     15 Gold

Now you've turned 2 steaks into 15 gold, courtesy of your customer, Sturm Brightblade.

Understanding Equity
====================

The most confusing transaction in any ledger will be your equity account--- because starting balances can't come out of nowhere.

When you first start your ledger, you will likely already have money in some of your accounts.  Let's say there's $100 in your checking account; then add a transaction to your ledger to reflect this amount. Where will money come from?  The answer: your equity.

     10/2  Opening Balance
         Assets:Checking                         $100.00
         Equity:Opening Balances

But what is equity?  You may have heard of equity when people talked about house mortgages, as ``the part of the house that you own''. Basically, equity is like the value of something.  If you own a car worth $5000, then you have $5000 in equity in that car.  In order to turn that car (a commodity) into a cash flow, or a credit to your bank account, you will have to debit the equity by selling it.

When you start a ledger, you are probably already worth something. Your net worth is your current equity.  By transferring the money in the ledger from your equity to your bank accounts, you are crediting the ledger account based on your prior equity.  That is why, when you look at the balance report, you will see a large negative number for Equity that never changes: Because that is what you were worth (what you debited from yourself in order to start the ledger) before the money started moving around.  If the total positive value of your assets is greater than the absolute value of your starting equity, it means you are making money.

Clear as mud?  Keep thinking about it.  Until you figure it out, put -Equity at the end of your balance command, to remove the confusing figure from the total.

Dealing with Petty Cash
=======================

Something that stops many people from keeping a ledger at all is the insanity of tracking small cash expenses.  They rarely generate a receipt, and there are often a lot of small postings, rather than a few large ones, as with checks.

One solution is: don't bother.  Move your spending to a debit card, but in general ignore cash.  Once you withdraw it from the ATM, mark it as already spent to an Expenses:Cash category:

     2004/03/15 ATM
         Expenses:Cash                      $100.00
         Assets:Checking

If at some point you make a large cash expense that you want to track, just ``move'' the amount of the expense from Expenses:Cash into the target account:

     2004/03/20 Somebody
         Expenses:Food                       $65.00
         Expenses:Cash

This way, you can still track large cash expenses, while ignoring all of the smaller ones.

Working with multiple funds and accounts
========================================

There are situations when the accounts you're tracking are different between your clients and the financial institutions where money is kept.  An example of this is working as the treasurer for a religious institution.  From the secular point of view, you might be working with three different accounts:

  * Checking

  * Savings

  * Credit Card

From a religious point of view, the community expects to divide its resources into multiple ``funds'', from which it makes purchases or reserves resources for later:

  * School fund

  * Building fund

  * Community fund

The problem with this kind of setup is that when you spend money, it comes from two or more places at once: the account and the fund.  And yet, the correlation of amounts between funds and accounts is rarely one-to-one.  What if the school fund has $500.00, but $400.00 of that comes from Checking, and $100.00 from Savings?

Traditional finance packages require that the money reside in only one place.  But there are really two ``views'' of the data: from the account point of view and from the fund point of view -- yet both sets should reflect the same overall expenses and cash flow.  It's simply where the money resides that differs.

This situation can be handled one of two ways.  The first is using virtual postings to represent the fact that money is moving to and from two kind of accounts at the same time:

     2004/03/20 Contributions
         Assets:Checking                    $500.00
         Income:Donations

     2004/03/25 Distribution of donations
         [Funds:School]                     $300.00
         [Funds:Building]                   $200.00
         [Assets:Checking]                 $-500.00

The use of square brackets in the second transaction ensures that the virtual postings balance to zero.  Now money can be spent directly from a fund at the same time as money is drawn from a physical account:

     2004/03/25 Payment for books (paid from Checking)
         Expenses:Books                    $100.00
         Assets:Checking                  $-100.00
         (Funds:School)                   $-100.00

When reports are generated, by default they'll appear in terms of the funds.  In this case, you will likely want to mask out your Assets account, because otherwise the balance won't make much sense:

     ledger bal -^Assets

If the --real option is used, the report will be in terms of the real accounts:

     ledger --real bal

If more asset accounts are needed as the source of a posting, just list them as you would normally, for example:

     2004/03/25 Payment for books (paid from Checking)
         Expenses:Books                    $100.00
         Assets:Checking                   $-50.00
         Liabilities:Credit Card           $-50.00
         (Funds:School)                   $-100.00

The second way of tracking funds is to use transaction codes.  In this respect the codes become like virtual accounts that embrace the entire set of postings.  Basically, we are associating a transaction with a fund by setting its code.  Here are two transactions that desposit money into, and spend money from, the Funds:School fund:

     2004/03/25 (Funds:School) Donations
         Assets:Checking                   $100.00
         Income:Donations

     2004/04/25 (Funds:School) Payment for books
         Expenses:Books                     $50.00
         Assets:Checking

Note how the accounts now relate only to the real accounts, and any balance or registers reports will reflect this.  That the transactions relate to a particular fund is kept only in the code.

How does this become a fund report?  By using the --code-as-payee option, you can generate a register report where the payee for each posting shows the code.  Alone, this is not terribly interesting; but when combined with the --by-payee option, you will now see account subtotals for any postings related to a specific fund.  So, to see the current monetary balances of all funds, the command would be:

     ledger --code-as-payee -P reg ^Assets

Or to see a particular funds expenses, the School fund in this case:

     ledger --code-as-payee -P reg ^Expenses -- School

Both approaches yield different kinds of flexibility, depending on how you prefer to think of your funds: as virtual accounts, or as tags associated with particular transactions.  Your own tastes will decide which is best for your situation.

Keeping a Journal
*****************

The most important part of accounting is keeping a good journal.  If you have a good journal, tools can be written to work whatever mathematical tricks you need to better understand your spending patterns.  Without a good journal, no tool, however smart, can help you.

The Ledger program aims at making journal transactions as simple as possible.  Since it is a command-line tool, it does not provide a user interface for keeping a journal.  If you like, you may use GnuCash to maintain your journal, in which case Ledger will read GnuCash's data files directly.  In that case, read the GnuCash manual now, and skip to the next chapter.

If you are not using GnuCash, but a text editor to maintain your journal, read on.  Ledger has been designed to make data transactions as simple as possible, by keeping the journal format easy, and also by automagically determining as much information as possible based on the nature of your transactions.

For example, you do not need to tell Ledger about the accounts you use.  Any time Ledger sees a posting involving an account it knows nothing about, it will create it (This also means if you misspell an account it will end up getting counted separately from what you intended.  The provided Emacs major mode provides for automatically filling in account names.).  If you use a commodity that is new to Ledger, it will create that commodity, and determine its display characteristics (placement of the symbol before or after the amount, display precision, etc) based on how you used the commodity in the posting.

The Most Basic Entry
====================

Here is the Pacific Bell example from above, given as a Ledger posting, with the additional of a check number:

     9/29 (1023) Pacific Bell
         Expenses:Utilities:Phone                   $23.00
         Assets:Checking                           $-23.00

As you can see, it is very similar to what would be written on paper, minus the computed balance totals, and adding in account names that work better with Ledger's scheme of things.  In fact, since Ledger is smart about many things, you don't need to specify the balanced amount, if it is the same as the first line:

     9/29 (1023) Pacific Bell
         Expenses:Utilities:Phone                   $23.00
         Assets:Checking

For this transaction, Ledger will figure out that $-23.00 must come from Assets:Checking in order to balance the transaction.

Also note the structure of the account entries.  There is an implied hierarchy established by separating with colons (see Structuring Your Accounts).

The format is very flexible and it isn't necessary that you indent and space out things exactly as shown. The only requirements are that the start of the transaction (the date typically) is at the beginning of the first line of the transaction, and the accounts are indented by at least one space.  If you omit the leading spaces in the account lines Ledger will not count the transaction and will not give an error.  There must be at least two spaces, or a tab, between the amount and the account.  If you do not have adequate separation between the amount and the account Ledger will give an error and stop calculating

Commenting on your Journal
==========================

Comments are generally started using a ';'.  However, in order to increase compatibility with other text manipulation programs and methods three additional comment characters are valid if used at the beginning of a line: #, |, and * and %. Block comments can be made by use !comment ... !end comment

     ; This is a single line comment,
     #  and this,
     %   and this,
     |    and this,
     *     and this.

     !comment
         This is a block comment with
         multipl lines
     !end comment

Starting up
===========

Unless you have recntly arrived from another planet, you already have a financial state.  You need to capture that financial state so that Ledger has a starting point.

At some convenient point in time you new the balances and outstanding obligation of every financial account you have.  Those amounts form the basis of the opening entry for ledger. For example if you chose the beginning of 2011 as the date to start tracking finances with ledger, your opening balance entry could look like this:

     2011/01/01 * Opening Balance
           Assets:Joint Checking                   $800.14
           Assets:Other Checking                    $63.44
           Assets:Savings                         $2805.54
           Assets:Investments:401K:Deferred         100.0000 VIFSX  $80.5227
           Assets:Investments:401K:Matching          50.0000 VIFSX  $83.7015
           Assets:Investments:IRA                   250.0000 VTHRX  $20.5324
           Liabilities:Mortgage                $-175634.88
           Liabilities:Car Loan                  $-3494.26
           Liabilities:Visa                      -$1762.44
           Equity:Opening Balances

There is nothing special about the name ``Opening Balances'' as the payee of the account name, anything convenient that you understand will work.

Currency and Commodities
========================

Ledger is agnostic when it comes to how you value your accounts. Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''. Holdings in stocks, bonds, mutual funds and other financial instruments can be labelled using whatever is convenient for you (stock ticker symbols are suggested for publicly traded assets). (you can track ANYTHING, even time or distance travelled. As long as it cannot be created or destroyed inside your accounting system.)

For the rest of this manual, we will only use the word ``commodities'' when refering to the units on a transaction value.

This is fundamentally different than many common accounting packages, which assume the same currency throughout all of your accounts.  This means if you typically operate in Euros, but travel to the US and have some expenses, you would have to do the currency conversion BEFORE you made the entry into your financial system.  With ledger this is not required.  In the same journal you can have entries in any or all commodities you actually hold.  You can use the reporting capabilities to convert all commodities to a single commodity for reporting purposes without ever changing the underlying entry.

For example, the following entries reflect transaction made for a business trip to Europe from the US:

     2011/09/23 Cash in Munich
         Assets:Cash                               E50.00
         Assets:Checking                          $-66.00

     2011/09/24 Dinner in Munich
         Expenses:Business:Travel                  E35.00
         Assets:Cash

This says that $66.00 came out of checking and turned into 50 Euros. The implied exchange rate was $1.32.  Then 35.00 Euros was spent on Dinner in Munich.

Running a ledger balance report shows:

     $ ledger -f example.dat bal
                  $-66.00
                   E15.00  Assets
                   E15.00    Cash
                  $-66.00    Checking
                   E35.00  Expenses:Business:Travel
     --------------------
                  $-66.00
                   E50.00

The top two lines show my current assets as $-66.00 in checking (in this very short example I didn't establish opening an opening balance for the checking account) and E15.00.  After spending on dinner i have E15.00 in my wallet.  The bottom line balances to zero, but is shown in two lines since we haven't told ledger to convert commodities.

Naming Commodities
------------------

Commodity names can have any character, including whitespace.  However, if you include whitespace or numeric characters the commodity name must be enclosed in double quotes:

     1999/06/09 !  Achat
             Actif:SG PEE STK  49.957 "Arcancia Equilibre 454"
             Actif:SG PEE STK  $-234.90

     2000/12/08 !  Achat
             Actif:SG PEE STK  215.796 "Arcancia Equilibre 455"
             Actif:SG PEE STK  $-10742.54

Buying and Selling Stock
------------------------

Buying stock is a typical example that many will use that involves multiple commodities in the same transaction.  The type of the share (AAPL for Apple Inc.)  and the share purchase price in the currency unit you made the purcase in ($ for AAPL). Yes, the typical convention is as follows:

        2004/05/01 Stock purchase
            Assets:Broker                    50 AAPL @ $30.00
            Expenses:Broker:Commissions       $19.95
            Assets:Broker                 $-1,500.00

This assumes you have a brokerage account that is capable of managed both liquid and commodity assets.  Now, on the day of the sale:

        2005/08/01 Stock sale
            Assets:Broker                   -50 APPL {$30.00} @ $50.00
            Expenses:Broker:Commissions       $19.95
            Income:Capital Gains          $-1,000.00
            Assets:Broker                  $2,500.00

You can, of course, elide the amount of the last posting.  It is there for clarity's sake.

The {$30.00} is a lot price.  You can also use a lot date, [2004/05/01], or both, in case you have several lots of the same price/date and your taxation model is based on longest-held-first.

Fixing Lot Prices
-----------------

Commodites that you keep in order to sell them at a later time have a variable value that fluctuates with the market prices.  Commodities that you consume should not fluctuate in value, but stay at the lot price they were purchased at.  As an extension of ``lot pricing'', you can fix the per-unit price of a commodity.

For example, say you buy 10 gallons of gas at $1.20.  In future ``value'' reports, you don't want these gallons reported in terms of today's price, but rather the price when you bought it.  At the same time, you also want other kinds of commodities -- like stocks -- reported in terms of today's price.

This is supported as follows:

          2009/01/01 Shell
              Expenses:Gasoline             11 GAL {=$2.299}
              Assets:Checking

This transaction actually introduces a new commodity, ``GAL {=$2.29}'', whose market value disregards any future changes in the price of gasoline.

If you do not want price fixing, you can specify this same transaction in one of two ways, both equivalent (note the lack of the equal sing from the transaction above):

          2009/01/01 Shell
              Expenses:Gasoline             11 GAL {$2.299}
              Assets:Checking

          2009/01/01 Shell
              Expenses:Gasoline             11 GAL @ $2.299
              Assets:Checking

There is no difference in meaning between these two forms.  Why do both exist, you ask?  To support things like this:

          2009/01/01 Shell
              Expenses:Gasoline             11 GAL {=$2.299} @ $2.30
              Assets:Checking

This transaction says that you bought 11 gallons priced at $2.29 per gallon at a cost to you of $2.30 per gallon.  Ledger auto-generates a balance posting in this case to Equity:Capital Losses to reflect the 11 cent difference, which is then balanced by Assets:Checking because its amount is null.

Structuring your Accounts
=========================

There really are no requirements for how you do this, but to preserve your sanity we suggest some very basic structure to your accounting system.

At the highest level you have five sorts of accounts:

 1. Expenses: where money goes

 2. Assets: where money sits

 3. Income: where moeny comes from

 4. Liabilities: money you owe

 5. Equity: the real value of your property.

Starting the structure off this way will make it simpler for you to get answers to the questions you really need to ask about your finances.

Beneath these top level accounts you can have any level of detail you desire.  For example, if you want to keep specific track of how much you spend on burgers and fries, you could have the following:

     Expenses:Food:Hamburgers and Fries

Advanced Transactions
=====================

Transaction Notes and Tags
--------------------------

Ledger 3.0 supports entry and transaction ``notes'', which may contain new metadata and tag markers.  Here's an example:

        2004/05/27 (100) Credit card company
            ; This is an entry note!
            ; Sample: Value
            Liabilities:MasterCard         $20.00
            ; This is a transaction note!
            ; Sample: Another Value
            ; :MyTag:
            Assets:Bank:Checking
            ; :AnotherTag:

An indented paragraph starting with `;' is parsed as a persistent note for its preceding category.  These notes will get printed back to you with the ``print'' command.  They are accessible to value expressions using the ``note'' variable.

Further, any occurrence of ``:foo:'' in a note will cause a metadata tag for "foo" to be registered for that entry.  You can then search for such transactions using:

        ledger reg %foo
        ledger reg tag foo

Also, if any word in the note ends (but does not start) with a colon, the remainder of that line will be taken to be the metadata value for that tag.  That is:

        ; :foo:bar:baz:  <-- These are three tags
        ; name: value    <-- this is a tag with a value

Tags with value can be searched for just like tags.  In addition, you can further limit your tag search by looking for only those tags that have specific values:

        ledger reg %name=value
        ledger reg tag name=value

The group-by and sort functions also support tags:

     ledger --group-by "tag('foo')" bal

Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.

     ledger reg --sort "tag('foo')" %foo

Produces a register view with the transaction have tag `foo' sorted by the tags value.

Comments that occur before an entry, or which starts at column zero, are always ignored and are neither searched nor printed back.

If a posting comment is a date (with brackets), it modifies the date for that posting:

     2010/02/01 Sample
       Assets:Bank  $400.00
       Income:Check  $-400.00 ; [2010/01/01]

You can use metadata to override the payee field for individual postings within a transaction: (source)

     2010/06/17 Sample
       Assets:Bank  $400.00
       Income:Check1  $-100.00 ; Payee: Person One
       Income:Check2  $-100.00 ; Payee: Person Two
       Income:Check3  $-100.00 ; Payee: Person Three
       Income:Check4  $-100.00 ; Payee: Person Four

Metadata are normally strings, but you can create metadata of other types:

     2010/06/17 Sample
       Assets:Bank  $400.00
       Income:Check1  $-100.00
       ; Date:: [2010/09/01]
       ; Amount:: $100.00

(Note that this Date tag is not the same as the posting date.)

There are now tag/pop directives, to apply metadata to a range of transactions (and their postings). For example, if you wanted a conceptual ``page'' of transactions relating to business trip to Chicago, you could do this:

      tag Location: Chicago
      tag Purpose: Business

      ... transactions go here

      pop
      pop

It would be as if you'd applied "; Location: Chicago", etc., to every transaction.

Multiple Account Transactions
-----------------------------

Often times a transaction needs to be split across several accounts. This is trivially simple in a Ledger journal:

     2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck
         Income:Taxable:Acme Bytepumps Inc.     $-2500.00
         Assets:Brokerage:Checking                $175.00
         Assets:Investments:401K Deferred         $250.00
         Expenses:Tax:Medicare                     $36.25
         Expenses:Tax:Federal Tax                 $200.00
         Expenses:Tax:State Tax                    $20.00
         Expenses:Insurance:Life                   $18.75
         Assets:Credit Union:Joint Checking

This is an example of a paycheck entry.  The money comes out of your income account, and is spent into several other accounts.  The last line doesn't require an amount, as ledger will automatically balance the transaction (it will be $1800 into the Joint Checking account)

Virtual Transactions
--------------------

A virtual posting is when you, in your mind, see money as moving to a certain place, when in reality that money has not moved at all. There are several scenarios in which this type of tracking comes in handy, and each of them will be discussed in detail.

To enter a virtual posting, surround the account name in parentheses.  This form of usage does not need to balance.  However, if you want to ensure the virtual posting balances with other virtual postings in the same transaction, use square brackets.  For example:

     10/2 Paycheck
         Assets:Checking                        $1000.00
         Income:Salary                         $-1000.00
         (Debt:Alimony)                          $200.00

In this example, after receiving a paycheck an alimony debt is increased---even though no money has moved around yet.

     10/2  Paycheck
         Assets:Checking                        $1000.00
         Income:Salary                         $-1000.00
         [Savings:Trip]                          $200.00
         [Assets:Checking]                      $-200.00

In this example, $200 has been deducted from checking toward savings for a trip.  It will appear as though the money has been moved from the account into Savings:Trip, although no money has actually moved anywhere.

When balances are displayed, virtual postings will be factored in. To view balances without any virtual balances factored in, using the -R flag, for ``reality''.

Automatic Transactions
----------------------

As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. It is similar to tithing for Jews and Christians, or to Zakát for Muslims.  The exact details of computing Huqúqu'lláh are somewhat complex, but if you have further interest, please consult the Web.

Ledger makes this otherwise difficult law very easy.  Just set up an automated posting at the top of your ledger file:

     ; This automated transaction will compute Huqúqu'lláh based on this
     ; journal's postings.  Any that match will affect the
     ; Liabilities:Huququ'llah account by 19% of the value of that posting.

     = /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
       (Liabilities:Huququ'llah)               0.19

This automated posting works by looking at each posting in the ledger file.  If any match the given value expression, 19% of the posting's value is applied to the Liabilities:Huququ'llah account.  So, if $1000 is earned from Income:Salary, $190 is added to Liabilities:Huqúqu'lláh; if $1000 is spent on Rent, $190 is subtracted.  The ultimate balance of Huqúqu'lláh reflects how much is owed in order to fulfill one's obligation to Huqúqu'lláh. When ready to pay, just write a check to cover the amount shown in Liabilities:Huququ'llah.  That transaction would look like:

     2003/01/01 (101) Baha'i Huqúqu'lláh Trust
         Liabilities:Huququ'llah          $1,000.00
         Assets:Checking

That's it.  To see how much Huqúq is currently owed based on your ledger transactions, use:

     ledger balance Liabilities:Huquq

This works fine, but omits one aspect of the law: that Huquq is only due once the liability exceeds the value of 19 mithqáls of gold (which is roughly 2.22 ounces).  So what we want is for the liability to appear in the balance report only when it exceeds the present day value of 2.22 ounces of gold.  This can be accomplished using the command:

     ledger -Q -t "/Liab.*Huquq/?(a/P{2.22 AU}<={-1.0}&a):a" -s bal liab

With this command, the current price for gold is downloaded, and the Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces of gold.  If you wish the liability to be reflected in the parent subtotal either way, use this instead:

     ledger -Q -T "/Liab.*Huquq/?(O/P{2.22 AU}<={-1.0}&O):O" -s bal liab

In some cases, you may wish to refer to the account of whichever posting matched your automated transaction's value expression.  To do this, use the special account name $account:

     = /^Some:Long:Account:Name/
       [$account]  -0.10
       [Savings]    0.10

This example causes 10% of the matching account's total to be deferred to the Savings account---as a balanced virtual posting, which may be excluded from reports by using --real.

Automated transactions can use the full range of value expressions in their predicate.  If you wanted to specify a transaction only occur to certain accounts that meet cetain value criteria you could specify:

     = /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000)
       Expenses:Tax  0.27

In this case, amount is tied to the amount of the posting being tested.

But, wait! There's more!

In the short example above we calculated the taxes due for income within a certain bracket.  But in reality this calculation is more difficult. There are different rates for different marginal incomes and those taxes are not easily descirbed by a simple multiplicative coefficient. Automated transactions can use value expressions in their postings to determine the ammounts.  So to expand the example above for a three tax bracket system we could enter:

     = /Employees:.*:Payroll$/ and expr (amount < $10000.00)
       (Expenses:Tax)  0.1
     = /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 )
       (Expenses:Tax)  ($1000.00 + .15 * (amount - $10000.00))
     = /Employees:.*:Payroll$/ and expr (amount > $100000.00)
       (Expenses:Tax)  ($13500.00 + .20 * (amount-$100000.00))

Forcing balances and Reconciling Accounts
-----------------------------------------

Ledger has a feature for ensuring known past balances.  Here's an example entry:

        2008/11/26 (Interest) EXTND INS SWEEP ACCT(FDIC-INS)
            * Assets:Brokerage                 $0.07 = $970.64
            Income:Interest                   $-0.07

What this says is that as of 11/26/08 (bank perspective), the Assets:Brokerage account was known to equal $970.64.  It must equal this amount at this point in the Ledger file, or there will be a balancing error.

If you reconcile bank statements you can enter the reconciliation and link to a file (if you have it)

     2009/12/01 Foo
         Assets:Checking    $10.00
         Equity

     2009/12/10 Reconciled statement dated 2009/12/08
         ; Link: [[file:statements/checking/2009-12.pdf][2009-12.pdf]]
         [Assets:Checking]    = $10.00

Effective Dates
---------------

In the real world transactions do not take place instantaneously. Purchases can take several days to post to a bank account. And you may pay ahead for something that you want to distribute cost for.  With Ledger you can control every aspect of the timing of a transaction.

Say you're in business.  If you bill a customer, you can enter something like

     2008/01/01=2008/01/14 Client invoice  ;  estimated date you'll be paid
       Assets:Accounts Receivable            $100.00
       Income: Client name

Then, when you receive the payment, you change it to

     2008/01/01=2008/01/15 Client invoice ;  actual date money received
       Assets:Accounts Receivable            $100.00
       Income: Client name

and add something like

     2008/01/15 Client payment
       Assets:Checking                       $100.00
       Assets:Accounts Receivable

Now

       ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income

gives you your accrued income in the first two weeks of the year, and

       ledger --effective --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income

gives you your cash basis income in the same two weeks.

Another use is distributing costs out in time. As an example, suppose you just prepaid into a local vegetable co-op that sustains you through the winter.  It cost $225 to join the program, so you write a check. You don't want your October grocery budget to be blown because you bought food ahead, however.  What you really want is for the money to be evenly distributed over the next six months so that your monthly budgets gradually take a hit for the vegetables you'll pick up from the co-op, even though you've already paid for them.

     2008/10/16 * (2090) Bountiful Blessings Farm
         Expenses:Food:Groceries                  $ 37.50  ; [=2008/10/01]
         Expenses:Food:Groceries                  $ 37.50  ; [=2008/11/01]
         Expenses:Food:Groceries                  $ 37.50  ; [=2008/12/01]
         Expenses:Food:Groceries                  $ 37.50  ; [=2009/01/01]
         Expenses:Food:Groceries                  $ 37.50  ; [=2009/02/01]
         Expenses:Food:Groceries                  $ 37.50  ; [=2009/03/01]
         Assets:Checking

This entry accomplishes this.  Every month until you'll start with an automatic $37.50 deficit like you should, while your checking account really knows that it debited $225 this month.

Periodic Transactions
---------------------

A periodic transaction starts with a ~ followed by a period expression. Periodic transactions are used for budgeting and forecasting only, they have no effect without the --budget option specified.

See Budgeting and Forecasting for examples and details.

Recording Commodity Lot Prices
------------------------------

If you are tracking investments it is often necessary to keep track of specific purchases of a commodity bought at difference prices.  These specific purchases are referred to as ``lots''.  Tracking lots using ledger requires some additional info in the journal as well as additional command-line options when generating reports.

Say you want to record purchase of two separate lots of ACME, then sell some shares.  The correct way to do this is:

     2010-09-01 * Buy 2 shares of ACME @ $100
        Assets:Broker                                  2 ACME @ $100.00
        Assets:Cash

     2010-09-10 * Buy 2 share of ACME @ $110
        Assets:Broker                                  2 ACME @ $110.00
        Assets:Cash

     2011-09-20 * Sell 2 shares of ACME @ $150
        Assets:Broker                       -1 ACME {$100.00} @ $150.00
        Assets:Broker                       -1 ACME {$200.00} @ $150.00
        Assets:Cash

To report which lots of commodities you hold, use the --lot-prices option.  For example, after buying the 2 shares at $100 and 1 at $200 it would show you:

     $ ledger balance --lot-prices Assets:Broker until 2011-09-15
         2 ACME {$100.00}
         1 ACME {$200.00}  Assets:Broker

without the --lot-prices option you would only see the total number of shares you held:

     $ ledger balance  Assets:Broker until 2011-09-15
         3 ACME  Assets:Broker

and after the sale on 2011-09-20 it would show you:

     $ ledger balance --lot-prices Assets:Broker
         1 ACME {$100.00}  Assets:Broker

File Format for Users
=====================

Introduction
------------

The ledger file format is quite simple, but also very flexible.  It supports many options, though typically the user can ignore most of them.  They are summarized below.

Transactions and Comments
-------------------------

The initial character of each line determines what the line means, and how it should be interpreted.  Allowable initial characters are:

NUMBER
     A line beginning with a number denotes a transaction.  It may be followed by any number of lines, each beginning with whitespace, to denote the transaction's account postings.  The format of the first line is:

          DATE[=EDATE] [*|!] [(CODE)] DESC

     If * appears after the date (with optional effective date), it indicates the transaction is ``cleared'', which can mean whatever the user wants it to mean.  If ! appears after the date, it indicates d the transaction is ``pending''; i.e., tentatively cleared from the user's point of view, but not yet actually cleared.  If a CODE appears in parentheses, it may be used to indicate a check number, or the type of the posting.  Following these is the payee, or a description of the posting.

     The format of each following posting is:

            ACCOUNT  AMOUNT  [; NOTE]

     The ACCOUNT may be surrounded by parentheses if it is a virtual posting, or square brackets if it is a virtual posting that must balance.  The AMOUNT can be followed by a per-unit posting cost, by specifying @ AMOUNT, or a complete posting cost with @@ AMOUNT.  Lastly, the NOTE may specify an actual and/or effective date for the posting by using the syntax [ACTUAL_DATE] or [=EFFECTIVE_DATE] or [ACTUAL_DATE=EFFECTIVE_DATE].(See Virtual Transactions)

P
     Specifies a historical price for a commodity.  These are usually found in a pricing history file (see the -Q option).  The syntax is:

          P DATE SYMBOL PRICE

=
     An automated transaction.  A value expression must appear after the equal sign.

     After this initial line there should be a set of one or more postings, just as if it were normal transaction.  If the amounts of the postings have no commodity, they will be applied as modifiers to whichever real posting is matched by the value expression(See Automatic Transactions).

~
     A period transaction.  A period expression must appear after the tilde.

     After this initial line there should be a set of one or more postings, just as if it were normal transaction.

; # % | *
     A line beginning with a colon, pound, percent, bar or asterisk indicates a comment, and is ignored. Comments will not be returned in a ``print'' response.

indented ;
     If the semi colon is indented and occurs inside a transaction, it is parsed as a persistent note for its preceding category.  These notes or tags can be used to augment the reporting and filtering capabilities of Ledger.

Command Directives
------------------

! @
     A line beginning with an exclamation mark or an @ sign denotes a command directive.  It must be immediately followed by a command word. The supported commands are:

account
     Sets the base for all account following the directive.  Ledger supports a hierarchical tree of accounts.  It may be convenient to keep two ``root accounts''.  For example you may be tracking your personal finances adn your business finances.  In order to keep them seperate you could preface all personal accounts with personal: and all business account with business:.  You can easily split out large groups of transaction without manually editing them using the account directive.  For example:

          @account Personal
          2011/11/15  Supermarket
              Expenses:Groceries
              Assets:Checking

     Would result in all postings going into Personal:Expenses:Groceries and Personal:Assets:hecking until and @end account directive was found.

alias
     Define an alias for an account name.  If you have a deeply nested tree of accounts, it may be convenient to define an alias, for example:

          @alias Dining=Expenses:Entertainment:Dining
          @alias Checking=Assets:Credit Union:Joint Checking Account

          2011/11/28 YummyPalace
             Dining        $10.00
             Checking

     The aliases are only in effect for transactions read in after the alias is defined and are effected by @account directives that precede tham.

assert
     An assertion can throw an eror if a condition is not met during Ledger's run.

          @assert <VALUE EXPRESSION BOOLEAN RESULT>

bucket
     Defines the default account to use for balancing transactions. Normally, each transaction has at least two postings, which must balance to zero.  Ledger allows you to leave one posting with no ammount and automatically calculate balance the transaction in the posting.  The @bucket allows you to fill in all postings and automatically generate an additional posting to the bucket account balancing the transaction.  The following example set the Assets:Checking as the bucket:

          @bucket Assets:Checking
          2011/01/25 Tom's Used Cars
            Expenses:Auto                    $ 5,500.00

          2011/01/27 Book Store
            Expenses:Books                       $20.00

          2011/12/01 Sale
            Assets:Checking:Business            $ 30.00

capture
     Directs Ledger to replace any account matching a regex with the given account. For example:

          @capture  Expenses:Deductible:Medical  Medical

     Would cause any posting with Medical in it's name to be replaced with Expenses:Deductible:Medical.

     Ledger will display the mapped payees in print and register reports.

check
     A check can issue a warning if a condition is not met during Ledger's run.

          @check <VALUE EXPRESSION BOOLEAN RESULT>

comment
     Start a block comment, closed by @end comment.

define

end

expr

fixed

include
     Include the stated file as if it were part of the current file.

payee
     Directs Ledger to replace any payee matching a regex with the given payee.  You may download transactions from your bank that you want to be shortened or altered.  For example, the the payee for the grocery store near me is only one character different than the payee if I buy gasoline at the grocery story.  I can enter payee mappings that make this very clear:

          @payee  Supermarket Gas  Supermarket 4
          @payee  Supermarket Groceries  Supermarket 1

     Ledger will display the mapped payees in print and register reports.

tag
     Allows you to designate a block of transactions and assign the same tag to all.  Tags can have values and may be nested.

          @tag hastag
          @tag nestedtag: true
          2011/01/25 Tom's Used Cars
            Expenses:Auto                    $ 5,500.00
            ; :nobudget:
            Assets:Checking

          2011/01/27 Book Store
            Expenses:Books                       $20.00
            Liabilities:MasterCard

          @end tag nestedtag

          2011/12/01 Sale
            Assets:Checking:Business            $ 30.00
            Income:Sales
          @end tag hastag

     is the equivalent of

          2011/01/25 Tom's Used Cars
            :hastag:
            nestedtag: true
            Expenses:Auto                    $ 5,500.00
            ; :nobudget:
            Assets:Checking

          2011/01/27 Book Store
            :hastag:
            nestedtag: true
            Expenses:Books                       $20.00
            Liabilities:MasterCard

          2011/12/01 Sale
            :hastag:
            Assets:Checking:Business            $ 30.00
            Income:Sales

     Note that anything following "@end tag" is ignored.  placeing the name of the tag that is being closed is a simple way to keep track.

test

year
     Denotes the year used for all subsequent transactions that give a date without a year.  The year should appear immediately after the Y, for example: @year 2004.  This is useful at the beginning of a file, to specify the year for that file.  If all transactions specify a year, however, this command has no effect.

The following single letter commands may be at the beginning of a line alone, for backwards compatibility with older Ledger versions.

A
     See @bucket

Y
     See @year

N SYMBOL
     Indicates that pricing information is to be ignored for a given symbol, nor will quotes ever be downloaded for that symbol.  Useful with a home currency, such as the dollar ($).  It is recommended that these pricing options be set in the price database file, which defaults to ~/.pricedb.  The syntax for this command is:

          N SYMBOL

D AMOUNT
     Specifies the default commodity to use, by specifying an amount in the expected format.  The transaction command will use this commodity as the default when none other can be determined.  This command may be used multiple times, to set the default flags for different commodities; whichever is seen last is used as the default commodity. For example, to set US dollars as the default commodity, while also setting the thousands flag and decimal flag for that commodity, use:

          D $1,000.00

C AMOUNT1 = AMOUNT2
     Specifies a commodity conversion, where the first amount is given to be equivalent to the second amount.  The first amount should use the decimal precision desired during reporting:

          C 1.00 Kb = 1024 bytes

I, i, O, o, b, h
     These four relate to timeclock support, which permits Ledger to read timelog files.  See the timeclock's documentation for more info on the syntax of its timelog files.

Archiving Previous Years
========================

After a while, your journal can get to be pretty large.  While this will not slow down Ledger---it's designed to process journals very quickly---things can start to feel ``messy''; and it's a universal complaint that when finances feel messy, people avoid them.

Thus, archiving the data from previous years into their own files can offer a sense of completion, and freedom from the past.  But how to best accomplish this with the ledger program?  There are two commands that make it very simple: print, and equity.

Let's take an example file, with data ranging from year 2000 until 2004. We want to archive years 2000 and 2001 to their own file, leaving just 2003 and 2004 in the current file.  So, use print to output all the earlier transactions to a file called ledger-old.dat:

     ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat

To delete older data from the current ledger file, use print again, this time specifying year 2002 as the starting date:

     ledger -f ledger.dat -b 2002 print > x
     mv x ledger.dat

However, now the current file contains only postings from 2002 onward, which will not yield accurate present-day balances, because the net income from previous years is no longer being tallied.  To compensate for this, we must append an equity report for the old ledger at the beginning of the new one:

     ledger -f ledger-old.dat equity > equity.dat
     cat equity.dat ledger.dat > x
     mv x ledger.dat
     rm equity.dat

Now the balances reported from ledger.dat are identical to what they were before the data was split.

How often should you split your ledger?  You never need to, if you don't want to.  Even eighty years of data will not slow down ledger much---and that's just using present day hardware!  Or, you can keep the previous and current year in one file, and each year before that in its own file.  It's really up to you, and how you want to organize your finances.  For those who also keep an accurate paper trail, it might be useful to archive the older years to their own files, then burn those files to a CD to keep with the paper records---along with any electronic statements received during the year.  In the arena of organization, just keep in mind this maxim: Do whatever keeps you doing it.

Using emacs to Maintain Your Journal
====================================

Running ledger-mode
-------------------

Journal files are simple free text files easily modifed by any text editor.  A special mode for emacs is included with the source distribution.

To use the emacs mopy, copy the several lisp files from the source lisp directory your your site-lisp directoy and add the following line to your .emacs (or equivalent, ~/Aquamacs/Preferences.el for Aquamacs on Mac OS X)

     (load "ledger")

To trigger ledger mode when you visit a journal file, the first line of each of your journal files should be:

     ; -*-ledger-*-

To enter ledger-mode on a new file, type M-x ledger-mode.

Once you have loaded a Journal file into emacs, you have several commands available to make entering, clearing and reconciling transactions and producing reports:

C-i  or <TAB>
     auto complete entry

C-c C-a
     add a new entry, based on previous entries

C-c C-e
     toggle cleared status of an entire entry

C-c C-c
     toggle cleared status of an individual posting

C-c C-y
     set default year for entry mode

C-c C-m
     set default month for entry mode

C-c C-r
     reconcile uncleared entries related to an account

C-c C-d
     delete the current entry

C-c C-s
     sort all entries in the journal by date. Drop comments outside of entries

C-c C-o C-r
     run a ledger report

C-C C-o C-g
     goto the ledger report buffer

C-c C-o C-e
     edit the defined ledger reports

C-c C-o C-s
     save a report definition based on the current report

C-c C-o C-a
     rerun a ledger report

C-c C-o C-k
     kill the ledger report buffer

Working with entries
--------------------

Manual Entry Support
....................

In most financial programs, some sort of autocompletion is avaiable to save typing and improve accuracy. Ledger doesn't leave you hanging, ledger-mode provides tab completion on all portions of an entry. Type a portion of the payee and hit <TAB>, and ledger-mode will suggest a completion.  When filling in the account type the first few letters followed by a <TAB> and the account will be filled in.  For example typing Ex<TAB>Au<TAB>F<TAB> would yield Expenses:Auto:Fuel if you had previously used that account in this journal. If there are more than one account with similar starting, hitting <TAB> multiple times will iterate through them. This is a good habit to get in to prevent misspellings of accounts. Remember Ledger does not validate the names of payees or account so a misspelled account will be interpreted as a new account by ledger.

Automagically Adding new entries
................................

C-c C-a will run the ledger entry command (see entry and xact) from within emacs.  When typed, the minibuffer will appear with the current year and month, waiting for you to enter the day and the payee.  Ledger will generate a new entry based on the most recent entry for that payee, using the amount and accounts from that transaction.  If you have a new amount simply type the amount after the payee.  For example, if your journal  contains an entry

     2011/11/25   Viva Italiano
          Expenses:Food  $12.45
          Expenses:Tips  $2.55
          Liabilities:MasterCard  $-15.00

and you type C-c C-a, the mini-buffer will appear showing the current year and month.  If you complete the minibuffer entry by typing

     Entry: 2011/11/28 viva food 34 tip 7 <enter>

emacs will add the following entry to your journal:

     2011/11/30 Viva Italiano
         Expenses:Food                             $34.00
         Expenses:Tips                              $7.00
         Liabilities:MasterCard

Notice that the entry will appear at the correct place in the journal ordered by date, not necessarily at the bottom of the file.

Clearing Transactions and Postings
..................................

C-c C-e will place an asterisk after the date in the current transaction.  The tells ledger the transaction has been cleared through your bank (or whatever else you want the concept to mean)

     2011/11/25   Viva Italiano
          Expenses:Food  $12.45
          Expenses:Tips  $2.55
          Liabilities:MasterCard  $-15.00

becomes

     2011/11/25 * Viva Italiano
          Expenses:Food  $12.45
          Expenses:Tips  $2.55
          Liabilities:MasterCard  $-15.00

If, for some reason you need to clear a specific posting in the transaction you can type C-c C-c and the posting at point will be toggled.

Reconciling accounts
--------------------

In the reconcile buffer, use SPACE to toggle the cleared status of a transaction, C-x C-s to save changes (to the ledger file as well).

Generating Reports
------------------

The ledger reports command asks the user to select a report to run then creates a report buffer containing the results of running the associated command line.  Its' behavior is modified by a prefix argument which, when given, causes the generated command line that will be used to create the report to be presented for editing before the report is actually run.  Arbitrary unnamed command lines can be run by specifying an empty name for the report.  The command line used can later be named and saved for future use as a named report from the generated reports buffer.

In a report buffer, the following keys are available:

(space)
     scroll up

e
     edit the defined ledger reports

s
     save a report definition based on the current report

q
     quit the report (return to ledger buffer)

r
     redo the report

k
     kill the report buffer

Building Reports
****************

Introduction
============

The power of Ledger comes from the incredible flexibility in its reporting commands, combined with formatting commands.  Some options control what is included in the calculations, and formatting controlls how it is displayed.  The combinations are infinite. This chapter will show you the basics of combining varous options and commands.  In the next chapters you will find details about the specific commands and options.

Balance Reports
===============

Controlling the Accounts and Payees
-----------------------------------

The balance report is the most commonly used report.  The simplest invocation is:

     ledger balance -f drewr3.dat

which will print the balances of every account in you journal.

              $ -3,804.00  Assets
               $ 1,396.00    Checking
                  $ 30.00      Business
              $ -5,200.00    Savings
              $ -1,000.00  Equity:Opening Balances
               $ 6,654.00  Expenses
               $ 5,500.00    Auto
                  $ 20.00    Books
                 $ 300.00    Escrow
                 $ 334.00    Food:Groceries
                 $ 500.00    Interest:Mortgage
              $ -2,030.00  Income
              $ -2,000.00    Salary
                 $ -30.00    Sales
                 $ -63.60  Liabilities
                 $ -20.00    MasterCard
                 $ 200.00    Mortgage:Principal
                $ -243.60    Tithe
     --------------------
                $ -243.60

Most times this is more than you want.  Limiting the results to specific accounts is as easy as entering the names of the accounts after the command.

     20:37:53 ~/ledger/test/input > ledger balance -f drewr3.dat Auto MasterCard
               $ 5,500.00  Expenses:Auto
                 $ -20.00  Liabilities:MasterCard
     --------------------
               $ 5,480.00
     20:39:21 ~/ledger/test/input >

note the implicit logical and between Auto and Mastercard.

If you want the entire contents of a branch of your account tree, use the highest common name in the branch:

     20:39:21 ~/ledger/test/input > ledger balance -f drewr3.dat Income
              $ -2,030.00  Income
              $ -2,000.00    Salary
                 $ -30.00    Sales
     --------------------
              $ -2,030.00
     20:40:28 ~/ledger/test/input >

You can use general regular expressions in nearly anyplace Ledger needs a string:

     20:40:28 ~/ledger/test/input > ledger balance -f drewr3.dat ^Bo
     21:13:29 ~/ledger/test/input > ledger balance -f drewr3.dat Bo
                  $ 20.00  Expenses:Books

The first example looks for any account starting with ``Bo'', of which there are none.  The second looks for any account with ``Bo'', which is Expenses:Books.

If you want to know exactly how much you have spent in a particular account on a particular payee, the following are equivalent:

     > ledger balance Auto:Fuel and @Chevron
     > ledger balance --limit "(account=~/Fuel/) & (payee=~/Chev/)"

will show you the amount expended on gasoline at Chevron.  The second example is the first example of the very power expression language available to shape reports.  The first example may be easier to remember, but learning to use the second will open up far morepossibilities.

Controlling Formatting
----------------------

These examples all use the default formatting for the balance report. Customizing the formatting can easily allowing to see only what you want, or interface Ledger with other programs.

Advanced Reports
================

Asset Allocation
----------------

A very popular method of managing portfolios is to control the percent allocation of assets by certain categories.  The mix of categories and the weights applied to them vary by investing philosophy, but most follow a similar pattern.  Tracking asset allocation in ledger is not difficult but does require some additional effort to describe how the various assets you own contribute to the asset classes you want to track.

In our simple example we assume you want to apportion you assets into the general categories of domestic and international equities (stocks) and a combined category of bonds and cash.  For illustrative purposes we will use several publicly available mutual funds from Vanguard.  the three funds we will track are the Vanguard 500 IDX FD Signal (VIFSX), the Vanguard Target Retirement 2030 (VTHRX), and the Vanguard Short Term Federal Fund (VSGBX).  Each of these funds allocates assets to different categories of the investment universe and in different proportions. When you buy a share of VTHRX, that share is partially invested in equities, and partially invested in bonds and cash.  Below is the asset allocation for each of the instruments listed above:

  Domestic   Global
Symbol   Equity   Equity    bonds/cash
VIFSX   100%
VTHRX   24.0%    56.3%    19.7%
VSGBX       100%

These numbers are available from the prospectus of any publicly available mutual fund.  Of course a single stock issue is 100% equity and a single bond issue is 100% bonds.

We track purchases of specific investments using the symbol of that investment as its commodity.  How do we tell Ledger that a share of VTHRX is 24% Global equity etc.?  Enter automatic transactions and virtual accounts.

At the top of our ledger we enter automatic transactions that describe these proportions to Ledger.  In the same entries we set up virtual accounts that let us separate these abstract calculations from our actual balances.

For the three instruments listed above, those automatic transactions would look like:

     ;
     ; automatic calculations for asset allocation tracking
     ;
     = expr ( commodity == 'VIFSX' )
       (Allocation:Equities:Domestic)                 1.000

     = expr ( commodity == 'VTHRX' )
           (Allocation:Equities:Global)               0.240
           (Allocation:Equities:Domestic)             0.563
           (Allocation:Bonds/Cash)                    0.197

     = expr ( commodity == 'VBMFX')
           (Allocation:Bonds/Cash)                    1.000

How do these work? First the `=' sign at the beginning of the line tells ledger this is an automatic transaction to be applied when the condition following the `=' is true.  After the `=' sign is a value expression (see Value Expressions) that returns true any time a posting contains the commodity of interest.

The following line gives the proportions (not percentages) of each unit of commodity that belongs to each asset class.  Whenever Ledger sees a buy or sell of a particular commodity it will credit or debit these virtual accounts with that proportion of the number of shares moved.

Now that Ledger understands how to distribute the commodities amongst the various asset classes how do we get a report that tells us our current allocation?  Using the balance command and some tricky formatting!

     ledger bal Allocation --current --format "\
                    %-17((depth_spacer)+(partial_account))\
                    %10(percent(market(display_total), market(parent.total)))\
                    %16(market(display_total))\n"

Which yields:

     Allocation          100.00%      $100000.00
       Bonds/Cash         38.94%       $38940.00
       Equities           61.06%       $61060.00
         Domestic         95.31%       $58196.29
         Global            4.69%        $2863.71

Let's look at the Ledger invocation a bit closer.  The command above is split into lines for clarity.  The first line is very vanilla Ledger asking for the current balances of the account in the ``Allocation'' tree, using a special formatter.

The magic is in the formatter.  The second line simply tells Ledger to print the partial account name indented by its depth in the tree.  The third line is where we calculate and display the percentages.  The display_total command give the values of the total calculated for the account in this line.  The parent.total command gives the total for the next level up in the tree.  percent format their ratio as a percentage.  The fourth line tells ledger to display the current market value of the the line.

Reporting Commands
******************

Primary Financial Reports
=========================

balance
-------

The balance command reports the current balance of all accounts.  It accepts a list of optional regexps, which confine the balance report to the matching accounts.  If an account contains multiple types of commodities, each commodity's total is reported separately.

equity
------

The equity command prints out accounts balances as if they were transactions.  This makes it easy to establish the starting balances for an account, such as when Archiving Previous Years.

register
--------

The register command displays all the postings occurring in a single account, line by line.  The account regexp must be specified as the only argument to this command.  If any regexps occur after the required account name, the register will contain only those postings that match.  Very useful for hunting down a particular posting.

The output from register is very close to what a typical checkbook, or single-account ledger, would look like.  It also shows a running balance.  The final running balance of any register should always be the same as the current balance of that account.

If you have Gnuplot installed, you may plot the amount or running total of any register by using the script report, which is included in the Ledger distribution.  The only requirement is that you add either -j or -J to your register command, in order to plot either the amount or total column, respectively.

print
-----

The print command prints out ledger transactions in a textual format that can be parsed by Ledger.  They will be properly formatted, and output in the most economic form possible.  The ``print'' command also takes a list of optional regexps, which will cause only those postings which match in some way to be printed.

The print command can be a handy way to clean up a ledger file whose formatting has gotten out of hand.

Reports in other formats
========================

csv
---

emacs
-----

The emacs command outputs results in a form that can be read directly by Emacs Lisp.  The format of the sexp is:

     ((BEG-POS CLEARED DATE CODE PAYEE
       (ACCOUNT AMOUNT)...)  ; list of postings
      ...)                   ; list of transactions

org
---

The org command produces a journal file suitable for use in the emacs org mode.  More details on using org mode can be found at http://www.orgmode.org.

Org mode has a sub-system known as babel which allows for literate programming.  This allows you to mix text and code within the same document and automatically execute code which may generate results which will then appear in the text.

One of the languages supported by org+babel is ledger so that you can have ledger commands embedded in a text file and have the output of ledger commands also appear in the text file.  The output can be updated whenever any new ledger entries are added.

For instance, the following org mode text document snippet illustrates a very naive but still useful of the org+babel system:

     * A simple test of ledger in an org file
     The following are some entries and I have requested that ledger be run
     to generate a balance on the accounts.  I could have asked for a
     register or, in fact, anything at all the ledger can do through command
     line options.

     #+begin_src ledger :cmdline -s bal :results value
     2010/01/01 * Starting balance
      assets:bank:savings  £1300.00
      income:starting balances
     2010/07/22 * Got paid
      assets:bank:chequing  £1000.00
      income:salary
     2010/07/23 Rent
      expenses:rent  £500.00
      assets:bank:chequing
     #+end_src

     #+results:
     :            £1800.00  assets:bank
     :             £500.00    chequing
     :            £1300.00    savings
     :             £500.00  expenses:rent
     :           £-2300.00  income
     :           £-1000.00    salary
     :           £-1300.00    starting balances

Typing C-c C-c anywhere in the ``ledger source code block'' will invoke ledger on the contents of that block and generate a ``results'' block.  The results block can appear anywhere in the file but, by default, will appear immediately below the source code block.

You can combine multiple source code blocks before executing ledger and do all kinds of other wonderful things with Babel (and org).

Using Ledger for Accounting in Org-mode with Babel
..................................................

Using Babel, it is possible to record financial transactions conveniently in an org file and subsequently generate the financial reports required.

Getting Started
...............

With a recent version of org (7.01+), Ledger support is provided. To use it, enable Ledger support. Check the Babel documentation on Worg for instructions on how to achieve this but I currently do this directly as follows:

     (org-babel-do-load-languages
      'org-babel-load-languages
      '((ledger . t)         ;this is the important one for this tutorial
       ))

Once Ledger support in Babel has been enabled, we can use proceed to include Ledger entries within an org file. There are three ways (at least) in which these can be included:

 1. place all Ledger entries within one source block and execute this block with different arguments to generate the appropriate reports;

 2. place Ledger entries in more than one source block and use the noweb literary programming approach, supported by babel, to combine these into one block elsewhere in the file for processing by Ledger; and,

 3. place Ledger entries in different source blocks and use tangling to generate a Ledger file which you can subsequently process using Ledger directly.

The first two are described in more detail in this short tutorial.

Embedded Ledger example with single source block
................................................

The easiest, albeit possibly less useful, way in which to use Ledger within an org file is to use a single source block to record all Ledger entries. The following is an example source block:

     #+srcname: allinone
     #+begin_src ledger
     2010/01/01 * Starting balance
       assets:bank:savings  £1300.00
       income:starting balances
     2010/07/22 * Got paid
       assets:bank:chequing  £1000.00
       income:salary
     2010/07/23 Rent
       expenses:rent  £500.00
       assets:bank:chequing
     2010/07/24 Food
       expenses:food  £150.00
       assets:bank:chequing
     2010/07/31 * Interest on bank savings
       assets:bank:savings  £3.53
       income:interest
     2010/07/31 * Transfer savings
       assets:bank:savings  £250.00
       assets:bank:chequing
     2010/08/01 got paid again
       assets:bank:chequing  £1000.00
       income:salary
     #+end_src

In this example, we have combined both expenses and income into one set of Ledger entries. We can now generate register and balance reports (as well as many other types of reports) using babel to invoke Ledger with specific arguments. The arguments are passed to Ledger using the :cmdline header argument. In the code block above, there is no such argument so the system takes the default. For Ledger code blocks, the default :cmdline argument is bal and the result of evaluating this code block (C-c C-c) would be:

     #+results: allinone()
     :            £2653.53  assets
     :             £650.00  expenses
     :           £-3303.53  income

If, instead, you wished to generate a register of all the transactions, you would change the #+begin_src line for the code block to include the required command line option:

     #+begin_src ledger :cmdline reg

Evaluating the code block again would generate a different report.

Having to change the actual directive on the code block and re-evaluate makes it difficult to have more than one view of your transactions and financial state. Eventually, babel will support passing arguments to #+call evaluations of code blocks but this support is missing currently. Instead, we can use the concepts of literary programming, as implemented by the noweb features of babel, to help us.

Multiple Ledger source blocks with noweb
........................................

The noweb feature of babel allows us to expand references to other code blocks within a code block. For Ledger, this can be used to group transactions according to type, say, and then bring various sets of transactions together to generate reports.

Using the same transactions used above, we could consider splitting these into expenses and income, as follows:

Income Entries
..............

The first set of entries relates to income, either monthly pay or interest, all typically going into one of my bank accounts. Here, I have placed several entries, but we could have had each entry in a separate src block. Note that all code blocks you wish to refer to later must have the :noweb yes babel header argument specified.

     #+srcname: income
     #+begin_src ledger :noweb yes
     2010/01/01 * Starting balance
       assets:bank:savings  £1300.00
       income:starting balances
     2010/07/22 * Got paid
       assets:bank:chequing  £1000.00
       income:salary
     2010/07/31 * Interest on bank savings
       assets:bank:savings  £3.53
       income:interest
     2010/07/31 * Transfer savings
       assets:bank:savings  £250.00
       assets:bank:chequing
     2010/08/01 got paid again
       assets:bank:chequing  £1000.00
       income:salary
     #+end_src

Expenses
........

The following entries relate to personal expenses, such as rent and food. Again, these have all been placed in a single src block but could have been done individually.

     #+srcname: expenses
     #+begin_src ledger :noweb yes
     2010/07/23 Rent
       expenses:rent  £500.00
       assets:bank:chequing
     2010/07/24 Food
       expenses:food  £150.00
       assets:bank:chequing
     #+end_src

Financial Summaries
...................

Given the ledger entries defined above in the income and expenses code blocks, we can now refer to these using the noweb expansion directives, <<name>>. We can now define different code blocks to generate specific reports for those transactions. Below are two examples, one to generate a balance report and one to generate a register report of all transactions.

An overall balance summary
..........................

The overall balance of your account and expenditure with a breakdown according to category is specified by passing the :cmdline bal argument to Ledger. This code block can now be evaluated (C-c C-c) and the results generated by incorporating the transactions referred to by the <<income>> and <<expenses>>= lines.

     #+srcname: balance
     #+begin_src ledger :cmdline bal :noweb yes
     <<income>>
     <<expenses>>
     #+end_src

     #+results: balance
     :            £2653.53  assets
     :             £650.00  expenses
     :           £-3303.53  income

If you want a more detailed breakdown of where your money is and where it has been spent, you can specify the -s flag (i.e. :cmdline -s bal) to tell Ledger to include sub-accounts in the report.

     #+begin_src ledger :cmdline -s bal :noweb yes
     <<income>>
     <<expenses>>
     #+end_src

     #+results:
     :           £2653.53  assets:bank
     :           £1100.00    chequing
     :           £1553.53    savings
     :            £650.00  expenses
     :            £150.00    food
     :            £500.00    rent
     :          £-3303.53  income
     :             £-3.53    interest
     :          £-2000.00    salary
     :          £-1300.00    starting balances

Generating a monthly register
.............................

You can also generate a monthly register (the reg command) by executing the following src block. This presents a summary of transactions for each monthly period (the -M argument) with a running total in the final column (which should be 0 at the end if all the entries are correct).

     #+srcname: monthlyregister
     #+begin_src ledger :cmdline -M reg :noweb yes
     <<income>>
     <<expenses>>
     #+end_src

     #+results: monthlyregister
     :2010/01/01 - 2010/01/31         assets:bank:savings       £1300.00    £1300.00
     :                                in:starting balances     £-1300.00            0
     :2010/07/01 - 2010/07/31         assets:bank:chequing       £100.00     £100.00
     :                                assets:bank:savings        £253.53     £353.53
     :                                expenses:food              £150.00     £503.53
     :                                expenses:rent              £500.00    £1003.53
     :                                income:interest             £-3.53    £1000.00
     :                                income:salary            £-1000.00            0
     :2010/08/01 - 2010/08/01         assets:bank:chequing      £1000.00    £1000.00
     :                                income:salary            £-1000.00            0

We could also generate a monthly report on our assets showing how these are increasing (or decreasing!). In this case, the final column will be the running total of the assets in our ledger.

     #+srcname: monthlyassetsregister
     #+begin_src ledger :cmdline -M reg assets :noweb yes
     <<income>>
     <<expenses>>
     #+end_src

     #+results: monthlyassetsregister
     : 2010/01/01 - 2010/01/31         assets:bank:savings       £1300.00    £1300.00
     : 2010/07/01 - 2010/07/31         assets:bank:chequing       £100.00    £1400.00
     :                                 assets:bank:savings        £253.53    £1653.53
     : 2010/08/01 - 2010/08/01         assets:bank:chequing      £1000.00    £2653.53

Summary
.......

This short tutorial shows how Ledger entries can be embedded in a org file and manipulated using Babel. However, only simple Ledger features have been illustrated; please refer to the Ledger documentation for examples of more complex integrations with a ledger.

pricemap
--------

xml
---

By default, Ledger uses a human-readable data format, and displays its reports in a manner meant to be read on screen.  For the purpose of writing tools which use Ledger, however, it is possible to read and display data using XML.  This section documents that format.

The general format used for Ledger data is:

     <?xml version="1.0"?>
     <ledger>
       <xact>...</xact>
       <xact>...</xact>
       <xact>...</xact>...
     </ledger>

The data stream is enclosed in a ledger tag, which contains a series of one or more transactions.  Each xact describes the transaction and contains a series of one or more postings:

     <xact>
       <en:date>2004/03/01</en:date>
       <en:cleared/>
       <en:code>100</en:code>
       <en:payee>John Wiegley</en:payee>
       <en:postings>
         <posting>...</posting>
         <posting>...</posting>
         <posting>...</posting>...
       </en:postings>
     </xact>

The date format for en:date is always YYYY/MM/DD.  The en:cleared tag is optional, and indicates whether the posting has been cleared or not.  There is also an en:pending tag, for marking pending postings.  The en:code and en:payee tags both contain whatever text the user wishes.

After the initial transaction data, there must follow a set of postings marked with en:postings.  Typically these postings will all balance each other, but if not they will be automatically balanced into an account named <Unknown>.

Within the en:postings tag is a series of one or more posting's, which have the following form:

     <posting>
       <tr:account>Expenses:Computer:Hardware</tr:account>
       <tr:amount>
         <value type="amount">
           <amount>
             <commodity flags="PT">$</commodity>
             <quantity>90.00</quantity>
           </amount>
         </value>
       </tr:amount>
     </posting>

This is a basic posting.  It may also be begin with tr:virtual and/or tr:generated tags, to indicate virtual and auto-generated postings.  Then follows the tr:account tag, which contains the full name of the account the posting is related to.  Colons separate parent from child in an account name.

Lastly follows the amount of the posting, indicated by tr:amount.  Within this tag is a value tag, of which there are four different kinds, each with its own format:

 1. boolean

 2. integer

 3. amount

 4. balance

The format of a boolean value is true or false surrounded by a boolean tag, for example:

     <boolean>true</boolean>

The format of an integer value is the numerical value surrounded by an integer tag, for example:

     <integer>12036</integer>

The format of an amount contains two members, the commodity and the quantity.  The commodity can have a set of flags that indicate how to display it.  The meaning of the flags (all of which are optional) are:

P
     The commodity is prefixed to the value.

S
     The commodity is separated from the value by a space.

T
     Thousands markers are used to display the amount.

E
     The format of the amount is European, with period used as a thousands marker, and comma used as the decimal point.

The actual quantity for an amount is an integer of arbitrary size. Ledger uses the GNU multi-precision math library to handle such values.  The XML format assumes the reader to be equally capable. Here is an example amount:

     <value type="amount">
       <amount>
         <commodity flags="PT">$</commodity>
         <quantity>90.00</quantity>
       </amount>
     </value>

Lastly, a balance value contains a series of amounts, each with a different commodity.  Unlike the name, such a value does need to balance.  It is called a balance because it sums several amounts.  For example:

     <value type="balance">
       <balance>
         <amount>
           <commodity flags="PT">$</commodity>
           <quantity>90.00</quantity>
         </amount>
         <amount>
           <commodity flags="TE">DM</commodity>
           <quantity>200.00</quantity>
         </amount>
       </balance>
     </value>

That is the extent of the XML data format used by Ledger.  It will output such data if the xml command is used, and can read the same data.

prices and pricedb
------------------

The prices command displays the price history for matching commodities.  The -A flag is useful with this report, to display the running average price, or -D to show each price's deviation from that average.

There is also a pricedb command which outputs the same information as prices, but does in a format that can be parsed by Ledger.  This is useful for generating and tidying up pricedb databasefiles.

Reports about your Journals
===========================

accounts
--------

The accounts reports all of the accounts in the journal. Following the command with a regular expression will limit the output to accounts matching the regex.

convert
-------

commodities
-----------

Report all commodities present in the journals under consideration.

entry and xact
--------------

The entry and xact commands simplify the creation of new transactions.  It works on the principle that 80% of all postings are variants of earlier postings.  Here's how it works:

Say you currently have this posting in your ledger file:

     2004/03/15 * Viva Italiano
         Expenses:Food                       $12.45
         Expenses:Tips                        $2.55
         Liabilities:MasterCard             $-15.00

Now it's 2004/4/9, and you've just eating at Viva Italiano again.  The exact amounts are different, but the overall form is the same.  With the xact command you can type:

     ledger entry 2004/4/9 viva food 11 tips 2.50

This produces the following output:

     2004/04/09 Viva Italiano
         Expenses:Food                       $11.00
         Expenses:Tips                        $2.50
         Liabilities:MasterCard             $-13.50

It works by finding a past posting matching the regular expression viva, and assuming that any accounts or amounts specified will be similar to that earlier posting.  If Ledger does not succeed in generating a new transaction, an error is printed and the exit code is set to 1.

Here are a few more examples of the xact command, assuming the above journal transaction:

     ledger entry 4/9 viva 11.50
     ledger entry 4/9 viva 11.50 checking # (from `checking')
     ledger entry 4/9 viva food 11.50 tips 8
     ledger xact 4/9 viva food 11.50 tips 8 cash
     ledger xact 4/9 viva food $11.50 tips $8 cash
     ledger xact 4/9 viva dining "DM 11.50"

xact is identical to entry and is provide for backwards compatibility with Ledger 2.X.

payees
------

The payees reports all of the unique payees in the journal. To filter the payes displayed you must use the @ prefix:

     macbook-2:$ ledger payees '@Tar.+t'
     El Dorade Restaraunt
     My Big Fat Greek Restaraunt
     Target
     macbook-2:$

Developer Commands
==================

echo
----

This command simply echos its argument back to the output.

reload
------

Forces ledger to reload any journal files.  This function exists to support external programs controlling a running ledger process and does nothing for a command line user.

source
------

Pre-Commands
------------

args

eval
     evaluate the given value expression against the model transaction

expr "LIMIT EXPRESSION"
     Print details of how ledger parses the given limit expression and apply it against a model transaction.

format "FORMATTING"
     Print details of how ledger uses the given formatting description and apply it against a model transaction.

generate

parse <VALUE EXPR>
     Print details of how ledger uses the given value expression description and apply it against a model transaction.

period

query

template

Command-line Syntax
*******************

Basic Usage
===========

This chapter describes Ledger's features and options. You may wish to survey this to get an overview before diving in to the Ledger Tutorial and more detailed examples that follow.

Ledger has a very simple command-line interface, named---enticingly enough---ledger.  It supports a few reporting commands, and a large number of options for refining the output from those commands. The basic syntax of any ledger command is:

     ledger [OPTIONS...] COMMAND [ARGS...]

After the command word there may appear any number of arguments.  For most commands, these arguments are regular expressions that cause the output to relate only to postings matching those regular expressions. For the transaction command, the arguments have a special meaning, described below.

The regular expressions arguments always match the account name that a posting refers to.  To match on the payee of the transaction instead, precede the regular expression with payee or @.  For example, the following balance command reports account totals for rent, food and movies, but only those whose payee matches Freddie:

     ledger bal rent food movies payee freddie

or

     ledger bal rent food movies @freddie

There are many, many command options available with the ledger command, and it takes a while to master them. However, none of them are required to use the basic reporting commands.

Detailed Option Description
===========================

Global Options
--------------

args_only debug full_help help_calc help_comm help_disp help init_file options script trace verbose verify version

Report Options
--------------

abbrev_len account account_width actual_dates actual add_budget amount_data amount amount_width anon average balance_format base basis begin bold_if budget_format budget by_payee cleared_format cleared collapse_if_zero collapse color columns count csv_format current daily date_format date date_width datetime_format depth deviation display_amount display display_total dow effective empty end equity exact exchange flat force_color force_pager forecast_while forecast_years format gain generated group_by group_title_format head inject invert limit lot_dates lot_prices lot_tags lots_actual lots market meta meta_width monthly no_color no_rounding no_titles no_total now only output pager payee payee_width pending percent period pivot plot_amount_format plot_total_format prepend_format prepend_width pricedb_format price prices_format quantity quarterly raw real register_format related_all related revalued_only revalued_total revalued seed sort_all sort sort_xacts start_of_week subtotal tail total_data total total_width truncate unbudgeted uncleared unrealized_gains unrealized_losses unrealized unround weekly wide yearly

Session Options
---------------

cache decimal_comma download file input_date_format master_account price_db price_exp strict

Basic options
-------------

These are the most basic command options.  Most likely, the user will want to set them using environment variables (see Environment Variables), instead of using actual command-line options:

--help (-h) prints a summary of all the options, and what they are used for.  This can be a handy way to remember which options do what.  This help screen is also printed if ledger is run without a command.

--version (-v) prints the current version of ledger and exits.  This is useful for sending bug reports, to let the author know which version of ledger you are using.

--file FILE (-f FILE) reads FILE as a ledger file. This command may be used multiple times. Typically, the environment variable LEDGER_FILE is set, rather than using this command-line option.

--output FILE (-o FILE) redirects output from any command to FILE.  By default, all output goes to standard output.

--init-file FILE (-i FILE) causes FILE to be read by ledger before any other ledger file.  This file may not contain any postings, but it may contain option settings.  To specify options in the init file, use the same syntax as the command-line, but put each option on it's own line.  Here's an example init file:

     --price-db ~/finance/.pricedb

     ; ~/.ledgerrc ends here

Option settings on the command-line or in the environment always take precedence over settings in the init file.

--account NAME (-a NAME) specifies the default account which QIF file postings are assumed to relate to.

Report filtering
----------------

These options change which postings affect the outcome of a report, in ways other than just using regular expressions:

--current(-c) displays only transactions occurring on or before the current date.

--begin DATE (-b DATE) constrains the report to transactions on or after DATE.  Only transactions after that date will be calculated, which means that the running total in the balance report will always start at zero with the first matching transaction.  (Note: This is different from using --display to constrain what is displayed).

--end DATE (-e DATE) constrains the report so that transactions on or after DATE are not considered.  The ending date is inclusive.

--period STR (-p STR) sets the reporting period to STR.  This will subtotal all matching transactions within each period separately, making it easy to see weekly, monthly, quarterly, etc., posting totals.  A period string can even specify the beginning and end of the report range, using simple terms like ``last june'' or ``next month''.  For more using period expressions, see Period Expressions.

--period-sort EXPR sorts the postings within each reporting period using the value expression EXPR.  This is most often useful when reporting monthly expenses, in order to view the highest expense categories at the top of each month:

     ledger -M --period-sort -At reg ^Expenses

--cleared (-C) displays only postings whose transaction has been marked ``cleared'' (by placing an asterix to the right of the date).

--uncleared (-U) displays only postings whose transaction has not been marked ``cleared'' (i.e., if there is no asterix to the right of the date).

--real (-R) displays only real postings, not virtual. (A virtual posting is indicated by surrounding the account name with parentheses or brackets; see Virtual Transactions for more information).

--actual (-L) displays only actual postings, and not those created due to automated postings.

--related (-r) displays postings that are related to whichever postings would otherwise have matched the filtering criteria.  In the register report, this shows where money went to, or the account it came from.  In the balance report, it shows all the accounts affected by transactions having a related posting. For example, if a file had this transaction:

     2004/03/20 Safeway
         Expenses:Food                       $65.00
         Expenses:Cash                       $20.00
         Assets:Checking                    $-85.00

And the register command was:

     ledger -r register food

The following would be output, showing the postings related to the posting that matched:

     2004/03/20 Safeway              Expenses:Cash               $-20.00      $-20.00
                                     Assets:Checking              $85.00       $65.00

--budget is useful for displaying how close your postings meet your budget.  --add-budget also shows unbudgeted postings, while --unbudgeted shows only those. --forecast is a related option that projects your budget into the future, showing how it will affect future balances. See Budgeting and Forecasting.

--limit EXPR (-l EXPR) limits which postings take part in the calculations of a report.

--amount EXPR (-t EXPR) changes the value expression used to calculate the ``value'' column in the register report, the amount used to calculate account totals in the balance report, and the values printed in the equity report.  See Value Expressions.

--total EXPR (-T EXPR) sets the value expression used for the ``totals'' column in the register and balance reports.

Search Terms
------------

Valid Ledger invocations look like:

      ledger [OPTIONS] <COMMAND> <SEARCH-TERMS>

Where COMMAND is any command verb (see Reporting Commands), OPTIONS can occur anywhere, and SEARCH-TERM is one or more of the following:

      word              search for any account containing 'word'
      TERM and TERM     boolean AND between terms
      TERM or TERM      boolean OR between terms
      not TERM          invert the meaning of the term
      payee word        search for any payee containing 'word'
      @word             shorthand for 'payee word'
      desc word         alternate for 'payee word'
      note word         search for any note containing 'word'
      &word             shorthand for 'note word'
      tag word          search for any metadata tag containing 'word'
      tag word=value    search for any metadata tag containing 'word'
                        whose value contains 'value'
      %word             shorthand for 'tag word'
      %word=value       shorthand for 'tag word=value'
      meta word         alternate for 'tag word'
      meta word=value   alternate for 'tag word=value'
      expr 'EXPR'       apply the given value expression as a predicate
      '=EXPR'           shorthand for 'expr EXPR'
      \( TERMS \)     group terms; useful if using and/or/not

So, to list all transaction that charged to ``food'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent:

      ledger reg food not dining @chang
      ledger reg food and not dining and not payee chang
      ledger reg food not dining expr 'payee =~ /chang/'

Output Customization
--------------------

These options affect only the output, but not which postings are used to create it:

--collapse (-n) causes transactions in a register report with multiple postings to be collapsed into a single, subtotaled transaction.

--subtotal (-s) causes all transactions in a register report to be collapsed into a single, subtotaled transaction.

--by-payee (-P) reports subtotals by payee.

--comm-as-payee (-x) changes the payee of every posting to be the commodity used in that posting.  This can be useful when combined with other options, such as -s.

--empty (-E) includes even empty accounts in the balance report.

--weekly (-W) reports posting totals by the week.  The week begins on whichever day of the week begins the month containing that posting.  To set a specific begin date, use a period string, such as weekly from DATE.  --monthly (-M) reports posting totals by month; --yearly (-Y) reports posting totals by year.  For more complex period, using the --period option described above.

--dow reports postings totals for each day of the week. This is an easy way to see if weekend spending is more than on weekdays.

--sort EXPR (-S EXPR) sorts a report by comparing the values determined using the value expression EXPR.  For example, using -S -UT in the balance report will sort account balances from greatest to least, using the absolute value of the total.  For more on how to use value expressions, see Value Expressions.

--pivot TAG produces a pivot table around the tag provided. This requires meta data using valued tags.

--wide (-w) causes the default register report to assume 132 columns instead of 80.

--head causes only the first N transactions to be printed.  This is different from using the command-line utility head, which would limit to the first N postings.  --tail outputs only the last N transactions.  Both options may be used simultaneously.  If a negative amount is given, it will invert the meaning of the flag (instead of the first five transactions being printed, for example, it would print all but the first five).

--pager tells Ledger to pass its output to the given pager program---very useful when the output is especially long.  This behavior can be made the default by setting the LEDGER_PAGER environment variable.

--average (-A) reports the average posting value.

--deviation (-D) reports each posting's deviation from the average.  It is only meaningful in the register and prices reports.

--percent (-%) shows account subtotals in the balance report as percentages of the parent account.

--amount-data (-j) changes the register report so that it outputs nothing but the date and the value column, and the latter without commodities.  This is only meaningful if the report uses a single commodity.  This data can then be fed to other programs, which could plot the date, analyze it, etc.

--total-data (-J) changes the register report so that it outputs nothing but the date and totals column, without commodities.

--display EXPR (-d EXPR) limits which postings or accounts or actually displayed in a report.  They might still be calculated, and be part of the running total of a register report, for example, but they will not be displayed.  This is useful for seeing last month's checking postings, against a running balance which includes all posting values:

     ledger -d "d>=[last month]" reg checking

The output from this command is very different from the following, whose running total includes only postings from the last month onward:

     ledger -p "last month" reg checking

Which is more useful depends on what you're looking to know: the total amount for the reporting range (-p), or simply a display restricted to the reporting range (using -d).

--date-format STR (-y STR) changes the basic date format used by reports.  The default uses a date like 2004/08/01, which represents the default date format of %Y/%m/%d.  To change the way dates are printed in general, the easiest way is to put --date-format FORMAT in the Ledger initialization file ~/.ledgerrc (or the file referred to by LEDGER_INIT).

--format STR (-F STR) sets the reporting format for whatever report ledger is about to make.  See Format Strings. There are also specific format commands for each report type:

  * --balance-format STR

  * --register-format STR

  * --print-format STR

  * --plot-amount-format STR (-j register)

  * --plot-total-format STR (-J register)

  * --equity-format STR

  * --prices-format STR

  * --wide-register-format STR (-w register)

Commodity Reporting
-------------------

These options affect how commodity values are displayed:

--price-db FILE sets the file that is used for recording downloaded commodity prices.  It is always read on startup, to determine historical prices.  Other settings can be placed in this file manually, to prevent downloading quotes for a specific, for example.  This is done by adding a line like the following:

     ; Don't download quotes for the dollar, or timelog values
     N $
     N h

--price-exp MINS (-L MINS) sets the expected freshness of price quotes, in minutes.  That is, if the last known quote for any commodity is older than this value---and if --download is being used---then the Internet will be consulted again for a newer price.  Otherwise, the old price is still considered to be fresh enough.

--download (-Q) causes quotes to be automagically downloaded, as needed, by running a script named getquote and expecting that script to return a value understood by ledger.  A sample implementation of a getquote script, implemented in Perl, is provided in the distribution.  Downloaded quote price are then appended to the price database, usually specified using the environment variable LEDGER_PRICE_DB.

There are several different ways that ledger can report the totals it displays.  The most flexible way to adjust them is by using value expressions, and the -t and -T options.  However, there are also several ``default'' reports, which will satisfy most users basic reporting needs:

-O, --quantity
     Reports commodity totals (this is the default)

-B, --basis
     Reports the cost basis for all postings.

-V, --market
     Reports the last known market value for all commodities.

-G --gain
     Reports the net gain/loss for all commodities in the report that have a price history.

Often you will be more interested in the value of your entire holdings, in your preferred currency.  It might be nice to know you hold 10,000 shares of PENNY, but you are more interested in whether or not that is worth $1000.00 or $10,000.00.  However, the current day value of a commodity can mean different things to different people, depending on the accounts involved, the commodities, the nature of the transactions, etc.

When you specify -V, or -X COMM, you are requesting that some or all of the commodities be valuated as of today (or whatever --now is set to).  But what does such a valuation mean?  This meaning is governed by the presence of a VALUE metadata property, whose content is an expression used to compute that value.

If no VALUE property is specified, each posting is assumed to have a default, as if you'd specified a global, automated transaction as follows:

       = expr true
         ; VALUE:: market(amount, date, exchange)

This definition emulates the present day behavior of -V and -X (in the case of -X, the requested commodity is passed via the string 'exchange' above).

One thing many people have wanted to do is to fixate the valuation of old European currencies in terms of the Euro after a certain date:

       = expr commodity == "DM"
         ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR

This says: If --now is some old date, use market prices as they were at that time; but if --now is past June 2008, use a fixed price for converting Deutsch Mark to Euro.

Or how about never re-valuating commodities used in Expenses, since they cannot have a different future value:

       = /^Expenses:/
         ; VALUE:: market(amount, post.date, exchange)

This says the future valuation is the same as the valuation at the time of posting.  post.date equals the posting's date, while just 'date' is the value of --now (defaults to today).

Or how about valuating miles based on a reimbursement rate during a specific time period:

       = expr commodity == "miles" and date >= [2007] and date < [2008]
         ; VALUE:: market($1.05, date, exchange)

In this case, miles driven in 2007 will always be valuated at $1.05 each.  If you use -X EUR to expressly request all amounts in Euro, Ledger shall convert $1.05 to Euro by whatever means are appropriate for dollars.

Note that you can have a valuation expression specific to a particular posting or transaction, by overriding these general defaults using specific metadata:

       2010-12-26 Example
           Expenses:Food                $20
           ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what
           ; the user asks for with -V or -X
           ; VALUE:: 30 DM
           Assets:Cash

This example demonstrates that your VALUE expression should be as symbolic as possible, using terms like 'amount' and 'date', rather than specific amounts and dates.  Also, you should pass the amount along to the function 'market' so it can be further revalued if the user has asked for a specific currency.

Or, if it better suits your accounting, you can be less symbolic, which allows you to report most everything in EUR if you use -X EUR, except for certain accounts or postings which should always be valuated in another currency.  For example:

       = /^Assets:Brokerage:CAD$/
         ; Always report the value of commodities in this account in
         ; terms of present day dollars, despite what was asked for
         ; on the command-line VALUE:: market(amount, date, '$')

Ledger presently has no way of handling such things as FIFO and LIFO.

If you specify an unadorned commodity name, like AAPL, it will balance against itself.  If --lots are not being displayed, then it will appear to balance against any lot of AAPL.

If you specify an adorned commodity, like AAPL {$10.00}, it will also balance against itself, and against any AAPL if --lots is not specified.  But if you do specify --lot-prices, for example, then it will balance against that specific price for AAPL.

Environment variables
---------------------

Every option to ledger may be set using an environment variable.  If an option has a long name such --this-option, setting the environment variable LEDGER_THIS_OPTION will have the same affect as specifying that option on the command-line.  Options on the command-line always take precedence over environment variable settings, however.

Note that you may also permanently specify option values by placing option settings in the file ~/.ledgerrc, for example:

     --pager /bin/cat

Period Expressions
==================

A period expression indicates a span of time, or a reporting interval, or both.  The full syntax is:

     [INTERVAL] [BEGIN] [END]

The optional INTERVAL part may be any one of:

     every day
     every week
     every monthly
     every quarter
     every year
     every N days     # N is any integer
     every N weeks
     every N months
     every N quarters
     every N years
     daily
     weekly
     biweekly
     monthly
     bimonthly
     quarterly
     yearly

After the interval, a begin time, end time, both or neither may be specified.  As for the begin time, it can be either of:

     from <SPEC>
     since <SPEC>

The end time can be either of:

     to <SPEC>
     until <SPEC>

Where SPEC can be any of:

     2004
     2004/10
     2004/10/1
     10/1
     october
     oct
     this week  # or day, month, quarter, year
     next week
     last week

The beginning and ending can be given at the same time, if it spans a single period.  In that case, just use SPEC by itself.  In that case, the period oct, for example, will cover all the days in october.  The possible forms are:

     <SPEC>
     in <SPEC>

Here are a few examples of period expressions:

     monthly
     monthly in 2004
     weekly from oct
     weekly from last month
     from sep to oct
     from 10/1 to 10/5
     monthly until 2005
     from apr
     until nov
     last oct
     weekly last august

Budgeting and Forecasting
*************************

Budgeting
=========

Keeping a budget allows you to pay closer attention to your income and expenses, by reporting how far your actual financial activity is from your expectations.

To start keeping a budget, put some periodic transactions (see Periodic Transactions) at the top of your ledger file.  A period transaction is almost identical to a regular transaction, except that it begins with a tilde and has a period expression in place of a payee.  For example:

     ~ Monthly
       Expenses:Rent               $500.00
       Expenses:Food               $450.00
       Expenses:Auto:Gas           $120.00
       Expenses:Insurance          $150.00
       Expenses:Phone              $125.00
       Expenses:Utilities          $100.00
       Expenses:Movies              $50.00
       Expenses                    $200.00  ; all other expenses
       Assets

     ~ Yearly
       Expenses:Auto:Repair        $500.00
       Assets

These two period transactions give the usual monthly expenses, as well as one typical yearly expense.  For help on finding out what your average monthly expense is for any category, use a command like:

     ledger -p "this year" --monthly --average --subtotal balance ^expenses

The reported totals are the current year's average for each account.

Once these period transactions are defined, creating a budget report is as easy as adding --budget to the command-line.  For example, a typical monthly expense report would be:

     ledger --monthly register ^expenses

To see the same report balanced against your budget, use:

     ledger --budget --monthly register ^expenses

A budget report includes only those accounts that appear in the budget.  To see all expenses balanced against the budget, use --add-budget.  You can even see only the unbudgeted expenses using --unbudgeted:

     ledger --unbudgeted --monthly register ^expenses

You can also use these flags with the balance command.

Forecasting
===========

Sometimes it's useful to know what your finances will look like in the future, such as determining when an account will reach zero.  Ledger makes this easy to do, using the same period transactions as are used for budgeting.  An example forecast report can be generated with:

     ledger --forecast "T>{\$-500.00}" register ^assets ^liabilities

This report continues outputting postings until the running total is greater than $-500.00.  A final posting is always output, to show you what the total afterwards would be.

Forecasting can also be used with the balance report, but by date only, and not against the running total:

     ledger --forecast "d<[2010]" bal ^assets ^liabilities

l Value Expressions, Format Strings, Budgeting and Forecasting, Top

Value Expressions
*****************

Value expressions are an expression language used by Ledger to calculate values used by the program for many different purposes:

 1. The values displayed in reports

 2. For predicates (where truth is anything non-zero), to determine which postings are calculated (-l) or displayed (-d).

 3. For sorting criteria, to yield the sort key.

 4. In the matching criteria used by automated postings.

Value expressions support most simple math and logic operators, in addition to a set of one letter functions and variables.  A function's argument is whatever follows it.  The following is a display predicate that I use with the balance command:

     ledger -d /^Liabilities/?T<0:UT>100 balance

The effect is that account totals are displayed only if: 1) A Liabilities account has a total less than zero; or 2) the absolute value of the account's total exceeds 100 units of whatever commodity contains.  If it contains multiple commodities, only one of them must exceed 100 units.

Display predicates are also very handy with register reports, to constrain which transactions are printed.  For example, the following command shows only transactions from the beginning of the current month, while still calculating the running balance based on all transactions:

     ledger -d "d>[this month]" register checking

This advantage to this command's complexity is that it prints the running total in terms of all transactions in the register.  The following, simpler command is similar, but totals only the displayed postings:

     ledger -b "this month" register checking

Variables
=========

Below are the one letter variables available in any value expression. For the register and print commands, these variables relate to individual postings, and sometimes the account affected by a posting.  For the balance command, these variables relate to accounts---often with a subtle difference in meaning.  The use of each variable for both is specified.

t
     This maps to whatever the user specified with -t.  In a register report, -t changes the value column; in a balance report, it has no meaning by default.  If -t was not specified, the current report style's value expression is used.

T
     This maps to whatever the user specified with -T.  In a register report, -T changes the totals column; in a balance report, this is the value given for each account.  If -T was not specified, the current report style's value expression is used.

m
     This is always the present moment/date.

Posting/account details
-----------------------

d
     A posting's date, as the number of seconds past the epoch.  This is always ``today'' for an account.

a
     The posting's amount; the balance of an account, without considering children.

b
     The cost of a posting; the cost of an account, without its children.

v
     The market value of a posting, or an account without its children.

g
     The net gain (market value minus cost basis), for a posting or an account without its children.  It is the same as v-b.

l
     The depth (``level'') of an account.  If an account has one parent, it's depth is one.

n
     The index of a posting, or the count of postings affecting an account.

X
     1 if a posting's transaction has been cleared, 0 otherwise.

R
     1 if a posting is not virtual, 0 otherwise.

Z
     1 if a posting is not automated, 0 otherwise.

Calculated totals
-----------------

O
     The total of all postings seen so far, or the total of an account and all its children.

N
     The total count of postings affecting an account and all its children.

B
     The total cost of all postings seen so far; the total cost of an account and all its children.

V
     The market value of all postings seen so far, or of an account and all its children.

G
     The total net gain (market value minus cost basis), for a series of postings, or an account and its children.  It is the same as V-B.

Functions
=========

The available one letter functions are:

-
     Negates the argument.

U
     The absolute (unsigned) value of the argument.

S
     Strips the commodity from the argument.

A
     The arithmetic mean of the argument; Ax is the same as x/n.

P
     The present market value of the argument.  The syntax P(x,d) is supported, which yields the market value at time d.  If no date is given, then the current moment is used.

Operators
=========

The binary and ternary operators, in order of precedence, are:

 1. * /

 2. + -

 3. ! < > =

 4. & | ?:

Unary Operators
---------------

not neg

Binary Operators
----------------

== < <= > >= and or + - * / QUERY COLON CONS SEQ DEFINE LOOKUP LAMBDA CALL MATCH

Complex expressions
===================

More complicated expressions are possible using:

NUM
     A plain integer represents a commodity-less amount.

{AMOUNT}
     An amount in braces can be any kind of amount supported by ledger, with or without a commodity.  Use this for decimal values.

/REGEXP/

W/REGEXP/
     A regular expression that matches against an account's full name.  If a posting, this will match against the account affected by the posting.

//REGEXP/

p/REGEXP/
     A regular expression that matches against a transaction's payee name.

///REGEXP/

w/REGEXP/
     A regular expression that matches against an account's base name.  If a posting, this will match against the account affected by the posting.

c/REGEXP/
     A regular expression that matches against the transaction code (the text that occurs between parentheses before the payee name).

e/REGEXP/
     A regular expression that matches against a posting's note, or comment field.

(EXPR)
     A sub-expression is nested in parenthesis.  This can be useful passing more complicated arguments to functions, or for overriding the natural precedence order of operators.

[DATE]
     Useful specifying a date in plain terms.  For example, you could say [2004/06/01].

Format Strings
**************

Format String Basics
====================

Format strings may be used to change the output format of reports. They are specified by passing a formatting string to the --format (-F) option.  Within that string, constructs are allowed which make it possible to display the various parts of an account or posting in custom ways.

Within a format string, a substitution is specified using a percent character (%).  The basic format of all substitutions is:

     %[-][MIN WIDTH][.MAX WIDTH](VALEXPR)

If the optional minus sign (-) follows the percent character, whatever is substituted will be left justified.  The default is right justified.  If a minimum width is given next, the substituted text will be at least that wide, perhaps wider.  If a period and a maximum width is given, the substituted text will never be wider than this, and will be truncated to fit.  Here are some examples:

     %-P     a transaction's payee, left justified
     %20P    The same, right justified, at least 20 chars wide
     %.20P   The same, no more than 20 chars wide
     %-.20P  Left justified, maximum twenty chars wide

The expression following the format constraints can be a single letter, or an expression enclosed in parentheses or brackets.

Format Expressions
==================

The allowable expressions are:

%
     Inserts a percent sign.

t
     Inserts the results of the value expression specified by -t. If -t was not specified, the current report style's value expression is used.

T
     Inserts the results of the value expression specified by -T. If -T was not specified, the current report style's value expression is used.

|
     Inserts a single space.  This is useful if a width is specified, for inserting a certain number of spaces.

_
     Inserts a space for each level of an account's depth.  That is, if an account has two parents, this construct will insert two spaces.  If a minimum width is specified, that much space is inserted for each level of depth.  Thus %5_, for an account with four parents, will insert twenty spaces.

(EXPR)
     Inserts the amount resulting from the value expression given in parentheses.  To insert five times the total value of an account, for example, one could say %12(5*O).  Note: It's important to put the five first in that expression, so that the commodity doesn't get stripped from the total.

[DATEFMT]
     Inserts the result of formatting a posting's date with a date format string, exactly like those supported by strftime.  For example: %[%Y/%m/%d %H:%M:%S].

S
     Insert the pathname of the file from which the transaction's data was read.

B
     Inserts the beginning character position of that transaction within the file.

b
     Inserts the beginning line of that transaction within the file.

E
     Inserts the ending character position of that transaction within the file.

e
     Inserts the ending line of that transaction within the file.

D
     By default, this is the same as %[%Y/%m%/d].  The date format used can be changed at any time with the -y flag, however. Using %D gives the user more control over the way dates are output.

d
     This is the same as the %D option, unless the transaction has an effective date, in which case it prints [ACTUAL_DATE=EFFECTIVE_DATE].

X
     If a posting has been cleared, this inserts * followed by a space; otherwise nothing is inserted.

Y
     This is the same as %X, except that it only displays a state character if all of the member postings have the same state.

C
     Inserts the checking number for a transaction, in parentheses, followed by a space; if none was specified, nothing is inserted.

P
     Inserts the payee related to a posting.

a
     Inserts the optimal short name for an account.  This is normally used in balance reports.  It prints a parent account's name if that name has not been printed yet, otherwise it just prints the account's name.

A
     Inserts the full name of an account.

W
     This is the same as %A, except that it first displays the posting's state if the transaction's posting states are not all the same, followed by the full account name.  This is offered as a printing optimization, so that combined with %Y, only the minimum amount of state detail is printed.

o
     Inserts the ``optimized'' form of a posting's amount.  This is used by the print report.  In some cases, this inserts nothing; in others, it inserts the posting amount and its cost.  It's use is not recommend unless you are modifying the print report.

n
     Inserts the note associated with a posting, preceded by two spaces and a semi-colon, if it exists.  Thus, no none becomes an empty string, while the note foo is substituted as  ; foo.

N
     Inserts the note associated with a posting, if one exists.

/
     The %/ construct is special.  It separates a format string between what is printed for the first posting of a transaction, and what is printed for all subsequent postings.  If not used, the same format string is used for all postings.

--balance-format
================

As an example of how flexible the --format strings can be, the default balance format looks like this:

              "%(justify(scrub(display_total), 20, -1, true, color))"
              "  %(!options.flat ? depth_spacer : \"\")"
              "%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
              "%$1\n%/"
              "--------------------\n"

New Formatting Codes
====================

Field Widths
------------

Function   Abbrev.   Description
date_width
payee_width
account_width
amount_width
total_width

Colors
------

The character based formatting ledger can do is limited to the ANSI terminal character colors and font highlight in a normal TTY seesion.

red   magenta   bold
green    cyan   underline
yellow    white   blink
blue

Quantities and Calcuations
--------------------------

Function   Abbrev.   Description
amount_expr
abs   U
commodity
display_amount    t
display_total    T
floor
get_at
is_seq
market    P
percent
price
quantity
rounded
truncated
total_expr
top_amount
to_boolean
to_int
to_amount
to_balance
unrounded

Dates
-----

Function   Abbrev.   Description
date
format_date
now --> d m
today
to_datetime
to_date
value_date

Text Formatting
---------------

Summary
.......

Function    Description
ansify_if(str,color)    Colorize the string
justify(str, fwidth, lwidth, right, colorize)     Right or left justify the string.
join(str)    Remove line feeds from the input string.  Mainly used internaally for org-mode output
quoted(str)    Returns "<str>".
strip    Removes additional annotations from values.
scrub    S
should_bold

Detailed Descriptions
.....................

ansify_if(value, color)
     Surrounds the string representing value with ANSI codes to give it color on an TTY display.  Has no effect if directed to a file.

justify(value, first_width, latter_width, right_justify, colorize)
     Right or left justify the string representing value.  The width of the field in the first line is given by first_width.  For subsequent lines the width is given by latterwidth.  If latter_width=-1, then first_width is use for all lines.  If right_justify=true then the field is right justify within the width of the field. If it is false, then the field is left justified and padded to the full width of the field.  If colorize is true then ledger will hone color settings.

join(str)
     Replaces line feeds in str with \n.

quoted(str)
     Return str surounded by double quotes, "<str>".

strip(value)
     Values can have numerous annotations, such as effective dates and lot prices.  strip removes these annotations.

Miscellaneous
-------------

Function   Abbrev.   Description
amount_expr
abs --> U
commodity
display_amount --> t
display_total --> T
date
format_date
format
floor
get_at
is_seq
justify
join
market --> P
null
now  --> d m
options
post
percent
price
print
quoted
quantity
rounded
scrub
strip --> S
should_bold
truncated
total_expr
today
top_amount
to_boolean
to_int
to_datetime
to_date
to_amount
to_balance
to_spring
to_mask
to_sequence
unrounded
value_date

Journal File Format for Developers
**********************************

This chapter offers a complete description of the journal data format, suitable for implementors in other languages to follow.  For users, the chapter on keeping a journal is less extensive, but more typical of common usage (see Keeping a Journal).

Data is collected in the form of transactions which occur in one or more journal files.  Each transaction, in turn, is made up of one or more postings, which describe how amounts flow from one account to another.  Here is an example of the simplest of journal files:

     2010/05/31 Just an example
         Expenses:Some:Account                $100.00
         Income:Another:Account

In this example, there is a transaction date, a payee, or description of the transaction, and two postings.  The postings show movement of one hundred dollars from an account within the Income hierarchy, to the specified expense account.  The name and meaning of these accounts in arbitrary, with no preferences implied, although you will find it useful to follow standard accounting practice (see Principles of Accounting).

Since an amount is missing from the second posting, it is assumed to be the inverse of the first.  This guarantee the cardinal rule of double-entry accounting: the sum of every transaction must balance to zero, or it is in error.  Whenever Ledger encounters a null posting in a transaction, it uses it to balance the remainder.

It is also typical---though not enforced---to think of the first posting as the destination, and the final as the source.  Thus, the amount of the first posting is typically positive.  Consider:

     2010/05/31 An income transaction
         Assets:Checking       $1,000.00
         Income:Salary

     2010/05/31 An expense transaction
         Expenses:Dining         $100.00
         Assets:Checking

Comments and metadata
=====================

Comments
--------

Comments are generally started using a ';'.  However, in order to increase compatibility with other text manipulation programs and methods three additional comment characters are valid if used at the beginning of a line: #, |, and *.

Metadat
-------

Specifying Amounts
==================

The heart of a journal is the amounts it records, and this fact is reflected in the diversity of amount expressions allowed.  All of them are covered here, though it must be said that sometimes, there are multiple ways to achieve a desired result.

Note: It is important to note that there must be at least two spaces between the end of the post and the beginning of the amount (including and commodity designator).

Integer Amounts
---------------

In the simplest form, bare decimal numbers are accepted:

     2010/05/31 An income transaction
         Assets:Checking        1000.00
         Income:Salary

Such amounts may only use an optional period for a decimal point. These are referred to as integer amounts or uncommoditized amounts.  In most ways they are similar to commoditized amounts, but for one signficant difference: They always display in reports with full precision.  More on this in a moment.  For now, a word must be said about how Ledger stores numbers.

Every number parsed by Ledger is stored internally as an infinite-precision rational value.  Floating-point math is never used, as it cannot be trusted to maintain precision of values.  So, in the case of 1000.00 above, the internal value is 100000/100.

While rational numbers are great at not losing precision, the question arises: How should they be displayed?  A number like 100000/100 is no problem, since it represents a clean decimal fraction.  But what about when the number 1/1 is divided by three?  How should one print 1/3, an infinitely repeating decimal?

Ledger gets around this problem by rendering rationals into decimal at the last possible moment, and only for display.  As such, some rounding must, at times, occur.  If this rounding would affect the calculation of a running total, special accommodation postings are generated to make you aware it has happened.  In practice, it happens rarely, but even then it does not reflect adjustment of the internal amount, only the displayed amount.

What has still not been answered is how Ledger rounds values.  Should 1/3 be printed as 0.33 or 0.33333?  For commoditized amounts, the number of decimal places is decided by observing how each commodity is used; but in the case of integer amounts, an arbitrary factor must be chosen.  Initially, this factor is six.  Thus, 1/3 is printed back as 0.333333. Further, this rounding factor becomes associated with each particular value, and is carried through mathematical operations.  For example, if that particular number were multiplied by itself, the decimal precision of the result would be twelve.  Addition and subtraction do not affect precision.

Since each integer amount retains its own display precision, this is called full precision, as opposed to commoditized amounts, which always look to their commodity to know what precision they should round to, and so use commodity precision.

Commoditized Amounts
--------------------

A commoditized amount is an integer amount which has an associated commodity.  This commodity can appear before or after the amount, and may or may not be separated from it by a space.  Most characters are allowed in a commodity name, except for the following:

  * Any kind of whitespace

  * Numerical digits

  * Punctuation: .,;:?!

  * Mathematical and logical operators: -+*/^&|=

  * Bracketing characters: <>[](){}

  * The at symbol: @

And yet, any of these may appear in a commodity name if it is surrounded by double quotes, for example:

     100 "EUN+133"

If a quoted commodity is found, it is displayed in quotes as well, to avoid any confusion as to which part is the amount, and which part is the commodity.

Another feature of commoditized amounts is that they are reported back in the same form as parsed.  If you specify dollar amounts using $100, they will print the same; likewise with 100 $ or $100.000.  You may even use decimal commas, such as $100,00, or thousand-marks, as in $10,000.00.

These display characteristics become associated with the commodity, with the result being that all amounts of the same commodity are reported consistently.  Where this is most noticeable is the display precision, which is determined by the most precise value seen for a given commodity---in most cases.

Ledger makes a distinction between observed amounts and unobserved amounts.  An observed amount is critiqued by Ledger to determine how amounts using that commodity should be displayed; unobserved amounts are significant in their value only---no matter how they are specified, it does not change how other amounts in that commodity will be displayed.

An example of this is found in cost expressions, covered next.

Posting costs
=============

You have seen how to specify either a commoditized or an integer amount for a posting.  But what if the amount you paid for something was in one commodity, and the amount received was another?  There are two main ways to express this:

     2010/05/31 Farmer's Market
         Assets:My Larder           100 apples
         Assets:Checking                $20.00

In this example, you have paid twenty dollars for one hundred apples. The cost to you is twenty cents per apple, and Ledger calculates this implied cost for you.  You can also make the cost explicit using a cost amount:

     2010/05/31 Farmer's Market
         Assets:My Larder           100 apples @ $0.200000
         Assets:Checking

Here the per-unit cost is given explicitly in the form of a cost amount; and since cost amount are unobserved, the use of six decimal places has no effect on how dollar amounts are displayed in the final report.  You can also specify the total cost:

     2010/05/31 Farmer's Market
         Assets:My Larder           100 apples @@ $20
         Assets:Checking

These three forms have identical meaning.  In most cases the first is preferred, but the second two are necessary when more than two postings are involved:

     2010/05/31 Farmer's Market
         Assets:My Larder           100 apples        @ $0.200000
         Assets:My Larder           100 pineapples    @ $0.33
         Assets:My Larder           100 "crab apples" @ $0.04
         Assets:Checking

Here the implied cost is $57.00, which is entered into the null posting automatically so that the transaction balances.

Primary commodities
-------------------

In every transaction involving more than one commodity, there is always one which is the primary commodity.  This commodity should be thought of as the exchange commodity, or the commodity used to buy and sells units of the other commodity.  In the fruit examples above, dollars are the primary commodity.  This is decided by Ledger on the placement of the commodity in the transaction:

     2010/05/31 Sample Transaction
         Expenses               100 secondary
         Assets                  50 primary

     2010/05/31 Sample Transaction
         Expenses               100 secondary @ 0.5 primary
         Assets

     2010/05/31 Sample Transaction
         Expenses               100 secondary @@ 50 primary
         Assets

The only case where knowledge of primary versus secondary comes into play is in reports that use the -V or -B options. With these, only primary commodities are shown.

If a transaction uses only one commodity, this commodity is also considered a primary.  In fact, when Ledger goes about ensures that all transactions balance to zero, it only ever asks this of primary commodities.

Extending with Python
*********************

Major Changes from version 2.6
******************************

Example Journal File: drewr.dat
*******************************

The following journal file is included with the source distribution of ledger.  It is called drewr.dat and exhibits many ledger features, include automatic and virtual transactions,

     ; -*- ledger -*-

     = /^Income/
       (Liabilities:Tithe)                    0.12

     ~ Monthly
       Assets:Checking                     $500.00
       Income:Salary

     2003/12/01 * Checking balance
       Assets:Checking                   $1,000.00
       Equity:Opening Balances

     2003/12/20 Organic Co-op
       Expenses:Food:Groceries             $ 37.50  ; [=2004/01/01]
       Expenses:Food:Groceries             $ 37.50  ; [=2004/02/01]
       Expenses:Food:Groceries             $ 37.50  ; [=2004/03/01]
       Expenses:Food:Groceries             $ 37.50  ; [=2004/04/01]
       Expenses:Food:Groceries             $ 37.50  ; [=2004/05/01]
       Expenses:Food:Groceries             $ 37.50  ; [=2004/06/01]
       Assets:Checking                   $ -225.00

     2003/12/28=2004/01/01 Acme Mortgage
       Liabilities:Mortgage:Principal    $  200.00
       Expenses:Interest:Mortgage        $  500.00
       Expenses:Escrow                   $  300.00
       Assets:Checking                  $ -1000.00

     2004/01/02 Grocery Store
       Expenses:Food:Groceries             $ 65.00
       Assets:Checking

     2004/01/05 Employer
       Assets:Checking                   $ 2000.00
       Income:Salary

     2004/01/14 Bank
       ; Regular monthly savings transfer
       Assets:Savings                     $ 300.00
       Assets:Checking

     2004/01/19 Grocery Store
       Expenses:Food:Groceries             $ 44.00
       Assets:Checking

     2004/01/25 Bank
       ; Transfer to cover car purchase
       Assets:Checking                  $ 5,500.00
       Assets:Savings
       ; :nobudget:

     2004/01/25 Tom's Used Cars
       Expenses:Auto                    $ 5,500.00
       ; :nobudget:
       Assets:Checking

     2004/01/27 Book Store
       Expenses:Books                       $20.00
       Liabilities:MasterCard

     2004/02/01 Sale
       Assets:Checking:Business            $ 30.00
       Income:Sales

Miscellaneous Notes
*******************

Various notes from the discussion list that I haven't incorporated in to the main body of the documentation.

Cookbook
========

Invoking Ledger
---------------

     ledger --group-by "tag('trip')" bal
     legder reg --sort "tag('foo')" %foo
     ledger cleared VWCU NFCU Tithe Misentry
     ledger register Joint --uncleared
     ledger register Checking  --sort d  -d 'd>[2011/04/01]' until 2011/05/25

Ledger Files
------------

     = /^Income:Taxable/
       (Liabilities:Tithe Owed)    -0.1
     = /Noah/
       (Liabilities:Tithe Owed)    -0.1
     = /Jonah/
       (Liabilities:Tithe Owed)    -0.1
     = /Tithe/
       (Liabilities:Tithe Owed)    -1.0