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-2010, 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 (it is copied in 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
--------------

Run this command:

     ledger -f drewr.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

Principles of Accounting
************************

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

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 label using whatever is convenient for you (stock ticker symbols are suggested for publicly traded assets). (you can track ANYTHING, even time. 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:

     macbook-2:$ 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.

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.  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.

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 withouth the --budget option specified.

See Budgeting and Forecasting for exmaples and details.

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

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.

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)

=
     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 an exclamation mark denotes a command directive. It must be immediately followed by the command word.  The supported commands are:

     !include
          Include the stated journal file.

     !account
          The account name is given is taken to be the parent of all postings that follow, until !end is seen.

     !end
          Ends an account block.

;
     A line beginning with a colon 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 to reporting and filtering capabilities of LEDGER.

Y
     If a line begins with a capital Y, it 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: Y2004.  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.

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

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, 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.

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

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 NFCUChecking  --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

Quick Reference
===============

This chapter describes LEDGER's features and serves as a quick reference. 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...]

Command options must always precede the command word.  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 --.  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 -- 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.

Options
=======

With all of the reports, command-line options are useful to modify the output generated.  These command-line options always occur before the command word.  This is done to distinguish options from exclusive regular expressions, which also begin with a dash.  The basic form for most commands is:

     ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]

The OPTIONS and REGEXPS expressions are both optional. You could just use ledger balance, without any options---which prints a summary of all accounts.  But for more specific reporting, or to change the appearance of the output, options are needed.

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

These are the most basic command options.  Most likely, the user will want to set them using environment variables (see Options), 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
     --cache /tmp/ledger-cache

     ; ~/.ledgerrc ends here

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

--cache FILE identifies FILE as the default binary cache file.  That is, if the ledger files to be read are specified using the environment variable LEDGER_FILE, then whenever a command is finished a binary copy will be written to the specified cache, to speed up the loading time of subsequent queries.  This filename can also be given using the environment variable LEDGER_CACHE, or by putting the option into your init file.  The --no-cache option causes LEDGER to always ignore the binary cache.

--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 Basic 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 ``ffod'' 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.

--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.

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

--totals include running total information in the xml report.

--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.

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:

     --cache /tmp/.mycache
     --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

Basic Reporting Commands
************************

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.

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.

output
======

The output command is very similar to the print command, except that it attempts to replicate the specified ledger file exactly.  The format of the command is:

     ledger -f FILENAME output FILENAME

Where FILENAME is the name of the ledger file to output.  The reason for specifying this command is that only transactions contained within that file will be output, and not an included transactions (as can happen with the print command).

xml
===

The xml command outputs results similar to what print and register display, but as an XML form. This data can then be read in and processed.  Use the --totals option to include the running total with each posting.

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

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.

prices
======

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 pricesdb command which outputs the same information as prices, but does in a format that can be parsed by LEDGER.

xact
====

The xact commands simplifies 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 xact 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.

There is a shell script in the distribution's scripts directory called xact, which simplifies the task of adding a new transaction to your ledger.  It launches vi to confirm that the transaction looks appropriate.

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

     ledger xact 4/9 viva 11.50
     ledger xact 4/9 viva 11.50 checking # (from `checking')
     ledger xact 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"

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

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. & | ?:

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 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 strings, a substitution is specified using a percent character (%).  The basic format of all substitutions is:

     %[-][MIN WIDTH][.MAX WIDTH]EXPR

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.  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.

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

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 commdity designator).

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.

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 by 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
*********************

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.

Commodity Pricing Problem
=========================

Sun, 26 Dec 2010 04:13:04 -0800

One of the things which stalled Ledger development recently is that I'd never found a truly satisfying way to handle the "commodity pricing problem".  That is, 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.

After experimenting with several different concepts and syntaxes, I found none of them were either satisfying or general enough.  My one attempt at providing "fixated prices" was too specific, and too inelegant for many usage patterns.

This morning, however, I think I've finally cracked this nut; and in a way which fits harmoniously into the Ledger architecture as if it were meant to be there all along...

Here's how the new scheme will work: When a user specifies '-V', or '-X COMM', they are requesting that some or all of the commodities in their Ledger file be valuated as of today (or whatever --now is set to).  But what does such a valuation mean?  This meaning shall be 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, '$')

I think this scheme, of using predicated value expressions which can be generalized in automated transactions, and made specific via transaction and posting-based metadata, provides sufficient flexibility to express most of the use cases which have occurred on this topic.

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.

I may, for the sake of reporting *only*, be able to implement some sort of guessing strategy, based on the order in which transactions appear in the data file...  But I'll have to think about this a lot more, and it would be a 3.1 thing.

> b) I don't see how this VALUE property can differentiate between -V > and -B.  Does this imply that you want to get rid of the -B option and > simply let users define what VALUE they get with -V?  If so, I think > this would be a bad idea... I really like the ability to see different > valuation methods using command line options (i.e. -B for cost basis > and -V for market value).  (Incidentally, while I initially liked your > example of using the posting date for Expenses, I later realized that > I sometimes use -V to see what my expenses (in a foreign currency) > would have been if I bought everything at today's exchange rate.)

-V and -B are entirely unrelated.  Perhaps I could support a BASIS property setting, for customizing -B in the same way VALUE customizes -V...

> c) I never fully understood what -X does exactly but afaik -X is a > special version of -V.  However, I believe that -X should _only_ do > conversion.  This would allow -X to be combined with other options, > such as -X and -V.  Example: let's say I bought 10 shares for 10.00 > GBP and they are now worth 15.00.  Because my main assets are in EUR, > I want to see what those shares are worth in EUR.  Since I'm > conservative I want to see the cost basis, i.e. I want to use -B and > -X EUR together. (This actually works today but I'm told this is an > accident and won't work in all cases.)

-V asks for the present day value of all commodities, and lets Ledger pick the target commodity based on its own hueristics.  -X is the same as -V, except that it overrides those hueristics and forces the target commodity.  (Although, as you've seen, the VALUE property could now countermand that).

There are reasons why -X can't be applied to any report.  Mainly it has to do with rounding.  For example, let's say I have 10 postings that each trade 1 DM, and the value of 1 DM is 0.001 EUR.  If I add all 10 DM and then apply -X, I get 0.01 EUR.  But if I apply -X to each 1 DM and *then* total them, I get 0.00 EUR.

This becomes very important to Ledger because -X is applied to totals, not just to individual amounts.  I'm going to have to use some magic internally to avoid this problem with the VALUE property (in most, but not all, cases).

And so, -X gets applied after, when the posting-origin of the commodities has been lost -- required information if a basis cost calculation is to be deferred.

The alternative would involve ever-growing lists of individual amounts, which would slow many parts of Ledger from O(N) to O(N^2).  Plus, it still wouldn't solve the rounding problem.

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

Yeah, I know... but I think it's a feature that ledger should eventually get (obviously not for 3.0).

> 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. > > I may, for the sake of reporting *only*, be able to implement some sort > of guessing strategy, based on the order in which transactions appear in > the data file...

Why for reporting only?  It seems to me that ledger has all the information to do FIFO and LIFO properly (i.e. to remove the right commodities from the list).  Let's take this example:

     2011-01-01 * Buy AAA
         Assets:Shares                             5 AAA  10.00 EUR
         Assets:Cash

     2011-01-03 * Buy AAA
         Assets:Shares                             2 AAA  10.00 EUR
         Assets:Cash

     2011-01-11 * Buy AAA
         Assets:Shares                             5 AAA  12.00 EUR
         Assets:Cash

     2011-01-21 * Buy AAA
         Assets:Shares                             5 AAA  13.00 EUR
         Assets:Cash

So we end up with (ledger --lots):

     5 AAA {10.00 EUR} [2011/01/01]
     2 AAA {10.00 EUR} [2011/01/03]
     5 AAA {12.00 EUR} [2011/01/11]
     5 AAA {13.00 EUR} [2011/01/21]  Assets:Shares

So if I sell 6 shares now, according to FIFO, I would do:

     2011-02-01 * Sell AAA
         Assets:Shares                          -5 AAA {10.00 EUR} [2011/01/01]
     13.50 EUR
         Assets:Shares                          -1 AAA {10.00 EUR} [2011/01/03]
     13.50 EUR
         Assets:Cash

ledger --lots:

     1 AAA {10.00 EUR} [2011/01/03]
     5 AAA {12.00 EUR} [2011/01/11]
     5 AAA {13.00 EUR} [2011/01/21]  Assets:Shares

According to LIFO, I would do this instead:

     2011-02-01 * Sell AAA
         Assets:Shares                          -5 AAA {13.00 EUR} [2011/01/21]
     13.50 EUR
         Assets:Shares                          -1 AAA {12.00 EUR} [2011/01/11]
     13.50 EUR
         Assets:Cash

In other words, you can manually do FIFO and LIFO with ledger already. However, it would be great if ledger would make this easier, e.g. that you could specify:

      2011-02-01 * Sell AAA
         Assets:Shares                          -6 AAA {FIFO}  13.50 EUR
         Assets:Cash

and ledger would iterate through all AAA commodities and take out the right ones (after all, it knows the date and price).

The only thing I don't think is possible with ledger at the moment is average cost.  I'm also not sure how --lot-dates should behave for average cost.

> There are reasons why -X can't be applied to any report.  Mainly it has > to do with rounding.  For example, let's say I have 10 postings that > each trade 1 DM, and the value of 1 DM is 0.001 EUR.  If I add all > 10 DM and then apply -X, I get 0.01 EUR.  But if I apply -X to each > 1 DM and *then* total them, I get 0.00 EUR.

Thanks for the explanation... what I was thinking of is that ledger would just produce a report according to -V or -B or whatever and *then* convert it with -X.  I use a shell script to do this for now:

     GBP2EUR="117/100"

     eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets"
     "^liabilities" | egrep " (EUR|GBP)$" | tail -n 2)
     eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//')
     gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//')
     eur=$(echo "$eur" | sed 's/\..*//')
     gbp=$(echo "$gbp" | sed 's/\..*//')
     gbpineur=$(($gbp*$GBP2EUR))
     echo "      " $(($eur + $gbpineur)) "   EUR   Total"

I'm kinda surprised that you no longer think it's a good idea to split -X from -V.  Last time I brought this up on IRC, you thought it was a good idea:

     10:44 < johnw> I think having -H, in addition to -X, may make what you want
      to see both natural and simple
     10:45 < johnw> you'd use -H for income/expense accounts, and -X for
      assets/liabilities
     10:45 < johnw> -H = historical values
     10:45 < johnw> -X = current exchange values
     10:45 < tbm> so what's the difference between -X and -V again?
     10:45 < johnw> -V is an automated version of -X
     10:45 < johnw> it tries to figure out what the reported commodity should be
     10:45 < johnw> we may then need an automated version of -H, to complete the
      reflection
     10:46 < johnw> btw, this is just an inside-out version of my "final"
      feature :)
     10:46 < tbm> why not change the meaning of -X to _only do conversion_?  And
      then you could combine -X with -B, -V or -H
     10:46 < johnw> instead of having it be syntactic, we're moving the semantic
      difference to a difference in options
     10:46 < johnw> oh HMM
     10:46 < johnw> -X with -B, -V and -I
     10:46 < johnw> (and -O, incidentally)
     10:46 < johnw> O = amount, B = cost, V = market value, I = price
     10:47 < johnw> that's really an excellent suggestion
     10:48 < johnw> i'd still need a flag to mean "historical" vs "current"
     10:48 < johnw> as well as "target commodity" (-X)