Overview
********

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.

Copyright
=========

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

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 ledger 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 ledger.  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 ledger, so we'll describe double-entry accounting in terms of that.

A checkbook ledger 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 ledger is to know how much money is available to spend.  That's really the aim of all ledgers.

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 ledger, 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 ledger, is a ledger that keeps track of all your accounts, not just checking.  In such a ledger, you record not only who gets paid---in the case of a debit---but where the money came from.  In a checkbook ledger, its assumed that all the money comes from your checking account.  But in a general ledger, 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 ledger 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 ledger for both.  In this general ledger you need to record a payment to Pacific Bell for your monthly phone bill.  The cost is $23.00, let's say, and you want to pay it from your checking account.  In the general ledger you need to say where the money came from, in addition to where it's going to. The transaction might look like this:

     9/29  BAL  Pacific Bell              $-200.00   $-200.00
                Equity:Opening Balances    $200.00
     9/29  BAL  Checking                   $100.00    $100.00
                Equity:Opening Balances   $-100.00
     9/29  100  Pacific Bell                $23.00    $223.00
                Checking                   $-23.00     $77.00

The first line shows a payment to Pacific Bell for $23.00.  Because there is no ``balance'' in a general ledger---it's always zero---we write in the total balance of all payments to ``Pacific Bell'', which now is $223.00 (previously the balance was $200.00).  This is done by looking at the last transaction for ``Pacific Bell'' in the ledger, adding $23.00 to that amount, and writing the total in the balance column. And the money came from ``Checking''---a withdrawal of $23.00---which leaves the ending balance in ``Checking'' at $77.00.  This is a very manual procedure; but that's where computers come in...

The posting must balance to $0: $23 went to Pacific Bell, $23 came from Checking.  There is nothing left over to be accounted for, since the money has simply moved from one account to another.  This is the basis of double-entry accounting: that money never pops in or out of existence; it is always a posting from one account to another.

Keeping a general ledger is the same as keeping two separate ledgers: 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 ledger books, if you deal with multiple accounts.

Enter the beauty of computerized accounting.  The purpose of the Ledger program is to make general ledger accounting simple, by keeping track of the balances for you.  Your only job is to enter the postings.  If a 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 ledger 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 ledger transactions from above, formatting as the ledger program wishes to see them:

     2004/09/29 Pacific Bell
          Payable:Pacific Bell            $-200.00
          Equity:Opening Balances

     2004/09/29 Checking
          Accounts:Checking                $100.00
          Equity:Opening Balances

     2004/09/29 Pacific Bell
          Payable:Pacific Bell              $23.00
          Accounts: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

More introduction
=================

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

The Ledger program aims at making ledger transaction as simple as possible. Since it is a command-line tool, it does not provide a user interface for keeping a ledger.  If you like, you may use GnuCash to maintain your ledger, in which case the Ledger program 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 ledger, read on.  Ledger has been designed to make data transaction as simple as possible, by keeping the ledger 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.  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.

Here is the Pacific Bell example from above, given as a Ledger posting:

     9/29 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 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.

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 just the Ledger mailing list at the following Web address:

     https://lists.sourceforge.net/lists/listinfo/ledger-discuss

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

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

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"

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.  FILE may also be a list of file names separated by colons.  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.  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.

--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 the section on using virtual postings 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.

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

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

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.

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

File format
===========

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 postings, or square brackets if it is a virtual postings 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].

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

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

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.

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

This chapter presents a series of recipes, gradually introducing all of the command-line features of Ledger.

For the purpose of these examples, assume the environment variable LEDGER is set to the file sample.dat (which is included in the distribution), and that the contents of that file are:

     = /^Expenses:Books/
       (Liabilities:Taxes)             -0.10

     ~ Monthly
       Assets:Bank:Checking          $500.00
       Income:Salary

     2004/05/01 * Checking balance
       Assets:Bank:Checking        $1,000.00
       Equity:Opening Balances

     2004/05/01 * Investment balance
       Assets:Brokerage              50 AAPL @ $30.00
       Equity:Opening Balances

     2004/05/14 * Pay day
       Assets:Bank:Checking          $500.00
       Income:Salary

     2004/05/27 Book Store
       Expenses:Books                 $20.00
       Liabilities:MasterCard

     2004/05/27 (100) Credit card company
       Liabilities:MasterCard         $20.00
       Assets:Bank:Checking

This sample file demonstrates a basic principle of accounting which it is recommended you follow: Keep all of your accounts under five parent Assets, Liabilities, Income, Expenses and Equity.  It is important to do so in order to make sense out of the following examples.

Checking balances
=================

Ledger has seven basic commands, but by far the most often used are balance and register.  To see a summary balance of all accounts, use:

     ledger bal

bal is a short-hand for balance.  This command prints out the summary totals of the five parent accounts used in sample.dat:

                $1,480.00
                  50 AAPL  Assets
               $-2,500.00  Equity
                   $20.00  Expenses
                 $-500.00  Income
                   $-2.00  Liabilities
     --------------------
               $-1,502.00
                  50 AAPL

None of the child accounts are shown, just the parent account totals. We can see that in Assets there is $1,480.00, and 50 shares of Apple stock.  There is also a negative grand total.  Usually the grand total is zero, which means that all accounts balance (It is impossible for accounts not to balance in ledger; it reports an error if a posting does not balance).  In this case, since the 50 shares of Apple stock cost $1,500.00 dollars, then these two amounts balance each other in the grand total.  The extra $2.00 comes from a virtual posting being added by the automatic transaction at the top of the file. The transaction is virtual because the account name was surrounded by parentheses in an automatic transaction.  Automatic transactions will be discussed later, but first let's remove the virtual posting from the balance report by using the --real option:

     ledger --real bal

Now the report is:

                $1,480.00
                  50 AAPL  Assets
               $-2,500.00  Equity
                   $20.00  Expenses
                 $-500.00  Income
     --------------------
               $-1,500.00
                  50 AAPL

Since the liability was a virtual posting, it has dropped from the report and we see that the final total is balanced.

But we only know that it balances because sample.dat is quite simple, and we happen to know that the 50 shares of Apple stock cost $1,500.00.  We can verify that things really balance by reporting the Apple shares in terms of their cost, instead of their quantity.  To do this requires the --basis, or -B, option:

     ledger --real -B bal

This command reports:

                $2,980.00  Assets
               $-2,500.00  Equity
                   $20.00  Expenses
                 $-500.00  Income

With the basis cost option, the grand total has disappeared, as it is now zero.  The confirms that the cost of everything balances to zero, which must always be true.  Reporting the real basis cost should never yield a remainder (If it ever does, then generated postings are involved, which can be removed using --actual).

Sub-account balances
--------------------

The totals reported by the balance command are only the topmost parent accounts.  To see the totals of all child accounts as well, use the -s option:

     ledger --real -B -s bal

This reports:

                $2,980.00  Assets
                $1,480.00    Bank:Checking
                $1,500.00    Brokerage
               $-2,500.00  Equity:Opening Balances
                   $20.00  Expenses:Books
                 $-500.00  Income:Salary

This shows that the Assets total is made up from two child accounts, but that the total for each of the other accounts comes from one child account.

Sometimes you may have a lot of children, nested very deeply, but only want to report the first two levels.  This can be done with a display predicate, using a value expression.  In the value expression, T represents the reported total, and l is the display level for the account:

     ledger --real -B -d "T&l<=2" bal

This reports:

                $2,980.00  Assets
                $1,480.00    Bank
                $1,500.00    Brokerage
               $-2,500.00  Equity:Opening Balances
                   $20.00  Expenses:Books
                 $-500.00  Income:Salary

Instead of reporting Bank:Checking as a child of Assets, it report only Bank, since that account is a nesting level of 2, while Checking is at level 3.

To review the display predicate used---T&l<=2---this rather terse expression means: Display an account only if it has a non-zero total (T), and its nesting level is less than or equal to 2 (l<=2).

Specific account balances
-------------------------

While reporting the totals for all accounts can be useful, most often you will want to check the balance of a specific account or accounts. To do this, put one or more account names after the balance command. Since these names are really regular expressions, you can use partial names if you wish:

     ledger bal checking

Reports:

                $1,480.00  Assets:Bank:Checking

Any number of names may be used:

     ledger bal checking broker liab

Reports:

                $1,480.00  Assets:Bank:Checking
                  50 AAPL  Assets:Brokerage
                   $-2.00  Liabilities

In this case no grand total is reported, because you are asking for specific account balances.

For those comfortable with regular expressions, any Perl regexp is allowed:

     ledger bal ^assets.*checking ^liab

Reports:

                $1,480.00  Assets:Bank:Checking
                   $-2.00  Liabilities:Taxes

The register report
===================

While the balance command can be very handy for checking account totals, by far the most powerful of Ledger's reporting tools is the register command.  In fact, internally both commands use the same logic, but report the results differently: balance shows the summary totals, while register reports each posting and how it contributes to that total.

Paradoxically, the most basic form of register is almost never used, since it displays every posting:

     ledger reg

reg is a short-hand for register.  This command reports:

     2004/05/01 Checking balance     Assets:Bank:Checking      $1,000.00    $1,000.00
                                     Equity:Opening Balan..   $-1,000.00            0
     2004/05/01 Investment balance   Assets:Brokerage            50 AAPL      50 AAPL
                                     Equity:Opening Balan..   $-1,500.00   $-1,500.00
                                                                              50 AAPL
     2004/05/14 Pay day              Assets:Bank:Checking        $500.00   $-1,000.00
                                                                              50 AAPL
                                     Income:Salary              $-500.00   $-1,500.00
                                                                              50 AAPL
     2004/05/27 Book Store           Expenses:Books               $20.00   $-1,480.00
                                                                              50 AAPL
                                     Liabilities:MasterCard      $-20.00   $-1,500.00
                                                                              50 AAPL
                                     (Liabilities:Taxes)          $-2.00   $-1,502.00
                                                                              50 AAPL
     2004/05/27 Credit card company  Liabilities:MasterCard       $20.00   $-1,482.00
                                                                              50 AAPL
                                     Assets:Bank:Checking        $-20.00   $-1,502.00
                                                                              50 AAPL

This rather verbose output shows every account posting in sample.dat, and how it affects the running total.  The final total is identical to what we saw with the plain balance command.  To see how things really balance, we can use --real -B, just as we did with balance:

     ledger --real -B reg

Reports:

     2004/05/01 Checking balance     Assets:Bank:Checking      $1,000.00    $1,000.00
                                     Equity:Opening Balan..   $-1,000.00            0
     2004/05/01 Investment balance   Assets:Brokerage          $1,500.00    $1,500.00
                                     Equity:Opening Balan..   $-1,500.00            0
     2004/05/14 Pay day              Assets:Bank:Checking        $500.00      $500.00
                                     Income:Salary              $-500.00            0
     2004/05/27 Book Store           Expenses:Books               $20.00       $20.00
                                     Liabilities:MasterCard      $-20.00            0
     2004/05/27 Credit card company  Liabilities:MasterCard       $20.00       $20.00
                                     Assets:Bank:Checking        $-20.00            0

Here we see that everything balances to zero in the end, as it must.

Specific register queries
-------------------------

The most common use of the register command is to summarize postings based on the account(s) they affect.  Using sample.dat as as example, we could look at all book purchases using:

     ledger reg books

Reports:

     2004/05/29 Book Store           Expenses:Books               $20.00       $20.00

If a double-dash (--) occurs in the list of regular expressions, any following arguments are matched against payee names, instead of account names:

     ledger reg ^liab -- credit

Reports:

     2004/05/29 Credit card company  Liabilities:MasterCard       $20.00       $20.00

There are many reporting options for tailoring which postings are found, and also how to summarize the various amounts and totals that result.  These are plumbed in greater depth below.

Selecting postings
==================

Although the easiest way to use the register is to report all the postings affecting a set of accounts, it can often result in more information than you want.  To cope with an ever-growing amount of data, there are several options which can help you pinpoint your report to include just the postings that interest you most.  This is called the ``calculation'' phase of Ledger.  All of its related options are documented under --help-calc.

By date
-------

--current(-c) displays transactions occurring on or before the current date.  Any transaction recorded for a future date will be ignored, as if it had not been seen.  This is useful if you happen to pre-record transactions, but still wish to view your balances in terms of what is available today.

--begin DATE (-b DATE) limits the report to only those transactions occurring on or after DATE.  The running total in the register will start at zero with the first posting, even if there are earlier transactions.

To limit the display only, but still add earlier postings to the running total, use the display expression -d 'd>=[DATE]'):

     ledger --basis -b may -d 'd>=[5/14]' reg ^assets

Reports:

     2004/05/14 Pay day              Assets:Bank:Checking        $500.00    $3,000.00
     2004/05/27 Credit card company  Assets:Bank:Checking        $-20.00    $2,980.00

In this example, the displayed postings start from 5/14, but the calculated total starts from the beginning of may.

--end DATE (-e DATE) states when reporting should end, both calculation and display.  The ending date is inclusive.

The DATE argument to the -b and -e options can be rather flexible.  Assuming the current date to be November 15, 2004, then all of the following are equivalent:

     ledger -b oct bal
     ledger -b "this oct" bal
     ledger -b 2004/10 bal
     ledger -b 10 bal
     ledger -b last bal
     ledger -b "last month" bal

To constrain the report to a specific time period, use --period (-p).  A time period may have both a beginning and an end, or neither, as well as a specified interval. Here are a few examples:

     ledger -p 2004 bal
     ledger -p august bal
     ledger -p "from aug to oct" bal
     ledger -p "daily from 8/1 to 8/15" bal
     ledger -p "weekly since august" bal
     ledger -p "monthly from feb to oct" bal
     ledger -p "quarterly in 2004" bal
     ledger -p yearly bal

See Period expressions for more on syntax.  Also, all of the options -b, -e and -p may be used together, but whatever information occurs last takes priority.  An example of such usage (in a script, perhaps) would be:

     ledger -b 2004 -e 2005 -p monthly reg ^expenses

This command is identical to:

     ledger -p "monthly in 2004" reg ^expenses

The postings within a period may be sorted using --period-sort, which takes a value expression.  This is similar to the --sort option, except that it sorts within each period transaction, rather than sorting all postings in the report. See the documentation on --sort below for more details.

By status
---------

By default, all regular postings are included in each report.  To limit the report to certain kinds of postings, use one or more of the following options:

-C, --cleared
     Consider only cleared postings.

-U, --uncleared
     Consider only uncleared and pending postings.

-R, --real
     Consider only real (non-virtual) postings.

-L, --actual
     Consider only actual (non-automated) postings.

Cleared postings are indicated by an asterix placed just before the payee name in a posting.  The meaning of this flag is up to the user, but typically it means that a transaction has been seen on a financial statement.  Pending postings use an exclamation mark in the same position, but are mainly used only by reconciling software. Uncleared postings are for things like uncashed checks, credit charges that haven't appeared on a statement yet, etc.

Real postings are all non-virtual postings, where the account name is not surrounded by parentheses or square brackets.  Virtual postings are useful for showing a transfer of money that never really happened, like money set aside for savings without actually transferring it from the parent account.

Actual postings are those not generated, either as part of an automated transaction, or a budget or forecast report.  A useful of when you might like to filter out generated postings is with a budget:

     ledger --budget --actual reg ^expenses

This command outputs all postings affecting a budgeted account, but without subtracting the budget amount (because the generated postings are suppressed with --actual).  The report shows how much you actually spent on budgeted items.

By relationship
---------------

Normally, a register report includes only the postings that match the regular expressions specified after the command word.  For example, to report all expenses:

     ledger reg ^expenses

This reports:

     2004/05/29 Book Store           Expenses:Books               $20.00       $20.00

Using --related (-r) reports the postings that did not match your query, but only in transactions that otherwise would have matched.  This has the effect of indicating where money came from, or when to:

     ledger -r reg ^expenses

Reports:

     2004/05/29 Book Store           Liabilities:MasterCard       $20.00       $20.00

By budget
---------

There is more information about budgeting and forecasting in Budgeting and forecasting.  Basically, if you have any period transactions in your ledger file, you can use these options.  A period transaction looks like:

     ~ Monthly
       Assets:Bank:Checking         $500.00
       Income:Salary

The difference from a regular transaction is that the first line begins with a tilde (~), and instead of a payee there's a period expression (Period expressions).  Otherwise, a period transaction is in every other way the same as a regular transaction.

With such a transaction in your ledger file, the --budget option will report only postings that match a budgeted account.  Using sample.dat from above:

     ledger --budget reg ^income

Reports:

     2004/05/01 Budget transaction         Income:Salary               $500.00      $500.00
     2004/05/14 Pay day              Income:Salary              $-500.00            0

The final total is zero, indicating that the budget matched exactly for the reported period.  Budgeting is most often helpful with period reporting; for example, to show monthly budget results use --budget -p monthly.

The --add-budget option reports all matching postings in addition to budget postings; while --unbudgeted shows only those that don't match a budgeted account.  To summarize:

--budget
     Show postings matching budgeted accounts.

--unbudgeted
     Show postings matching unbudgeted accounts.

--add-budget
     Show both budgeted and unbudgeted postings together (i.e., add the generated budget postings to the regular report).

A report with the --forecast option will add budgeted postings while the specified value expression is true.  For example:

     ledger --forecast 'd<[2005] reg ^income

Reports:

     2004/05/14 Pay day              Income:Salary              $-500.00     $-500.00
     2004/12/01 Forecast transaction       Income:Salary              $-500.00   $-1,000.00
     2005/01/01 Forecast transaction       Income:Salary              $-500.00   $-1,500.00

The date this report was made was November 5, 2004; the reason the first forecast transaction is in December is that forecast transactions are only added for the future, and they only stop after the value expression has matched at least once, which is why the January transaction appears.  A forecast report can be very useful for determining when money will run out in an account, or for projecting future cash flow:

     ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp

This reports balances projected income against projected expenses, showing the resulting total in yearly intervals until 2008.  For the case of sample.dat, which has no budgeted expenses, the result of the above command (in November 2004) is:

     2004/01/01 - 2004/12/31         Income:Salary            $-1,000.00   $-1,000.00
                                     Expenses:Books               $20.00     $-980.00
     2005/01/01 - 2005/12/31         Income:Salary            $-6,000.00   $-6,980.00
     2006/01/01 - 2006/12/31         Income:Salary            $-6,000.00  $-12,980.00
     2007/01/01 - 2007/12/31         Income:Salary            $-6,000.00  $-18,980.00
     2008/01/01 - 2008/01/01         Income:Salary              $-500.00  $-19,480.00

By value expression
-------------------

Value expressions can be quite complex, and are treated more fully in Value expressions.  They can be used for limiting a report with --limit (-l).  The following command report income since august, but expenses since october:

     ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg

The basic form of this value expression is (A&B)|(A&B).  The A in each part matches against an account name with /name/, while each B part compares the date of the posting (d) with a specified month.  The resulting report will contain only postings which match the value expression.

Another use of value expressions is to calculate the amount reported for each line of a register report, or for computing the subtotal of each account shown in a balance report.  This example divides each posting amount by two:

     ledger -t 'a/2' reg ^exp

The -t option doesn't affect the running total, only how the posting amount is displayed.  To change the running total, use -T.  In that case, you will likely want to use the total (O) instead of the amount (a):

     ledger -T 'O/2' reg ^exp

Massaging register output
=========================

Even after filtering down your data to just the postings you're interested in, the default reporting method of one posting per line is often still too much.  To combat this complexity, it is possible to ask Ledger to report the details to you in many different forms, summarized in various ways.  This is the ``display'' phase of Ledger, and is documented under --help-disp.

Summarizing
-----------

When multiple postings relate to a single transaction, they are reported as part of that transaction.  For example, in the case of sample.dat:

     ledger reg -- book

Reports:

     2004/05/29 Book Store           Expenses:Books               $20.00       $20.00
                                     Liabilities:MasterCard      $-20.00            0
                                     (Liabilities:Taxes)          $-2.00       $-2.00

All three postings are part of one transaction, and as such the transaction details are printed only once.  To report every transaction on a single line, use -n to collapse transactions with multiple postings:

     ledger -n reg -- book

Reports:

     2004/05/29 Book Store           <Total>                      $-2.00       $-2.00

In the balance report, -n causes the grand total not to be displayed at the bottom of the report.

If an account occurs more than once in a report, it is possible to combine them all and report the total per-account, using -s. For example, this command:

     ledger -B reg ^assets

Reports:

     2004/05/01 Checking balance     Assets:Bank:Checking      $1,000.00    $1,000.00
     2004/05/01 Investment balance   Assets:Brokerage          $1,500.00    $2,500.00
     2004/05/14 Pay day              Assets:Bank:Checking        $500.00    $3,000.00
     2004/05/27 Credit card company  Assets:Bank:Checking        $-20.00    $2,980.00

But if the -s option is added, the result becomes:

     2004/05/01 - 2004/05/29         Assets:Bank:Checking      $1,480.00    $1,480.00
                                     Assets:Brokerage          $1,500.00    $2,980.00

When account subtotaling is used, only one transaction is printed, and the date and name reflect the range of the combined postings.

With -P, postings relating to the same payee are combined.  In this case, the date of the combined transaction is that of the latest posting.

-x changes the payee name for each posting to be the same as the commodity it uses.  This can be especially useful combined with other options, like -P.  For example:

     ledger -Px reg ^assets

Reports:

     2004/05/29 $                    Assets:Bank:Checking      $1,480.00    $1,480.00
     2004/05/01 AAPL                 Assets:Brokerage            50 AAPL    $1,480.00
                                                                              50 AAPL

This reports shows the subtotal for each commodity held, and where it is located.  To see the basis cost, or initial investment, add -B.  Applied to the example above:

     2004/05/29 $                    Assets:Bank:Checking      $1,480.00    $1,480.00
     2004/05/01 AAPL                 Assets:Brokerage          $1,500.00    $2,980.00

The only other options which affect summarized totals is -E, which works only in the balance report.  In this case, it shows matching accounts with a zero a balance, which are ordinarily excluded.  This can be useful to see all the accounts involved in a report, even if some have no total.

Quick periods
-------------

Although the -p option (also --period) is much more versatile, there are other options to make the most common period reports easier:

-W, --weekly
     Show weekly sub-totals.  Same as -p weekly.

-M, --monthly
     Show monthly sub-totals.  Same as -p monthly.

-Y, --yearly
     Show yearly sub-totals.  Same as -p yearly.

There is one kind of period report that cannot be done with -p.  This is the --dow, or ``days of the week'' report, which shows summarized totals for each day of the week.  The following examples shows a ``day of the week'' report of income and expenses:

     ledger --dow reg ^inc ^exp

Reports:

     2004/05/27 Thursdays            Expenses:Books               $20.00       $20.00
     2004/05/14 Fridays              Income:Salary              $-500.00     $-480.00

Ordering and width
------------------

The postings displayed in a report are shown in the same order as they appear in the ledger file.  To change the order and sort a report, use the --sort option.  --sort takes a value expression to determine the value to sort against, making it possible to sort according to complex criteria.  Here are some simple and useful examples:

     ledger --sort d reg ^exp    # sort by date
     ledger --sort t reg ^exp    # sort by amount total
     ledger --sort -t reg ^exp   # reverse sort by amount total
     ledger --sort Ut reg ^exp   # sort by abs amount total

For the balance report, you will want to use T instead of t:

     ledger --sort T reg ^exp    # sort by amount total
     ledger --sort -T reg ^exp   # reverse sort by amount total
     ledger --sort UT reg ^exp   # sort by abs amount total

The --sort options sorts all postings in a report.  If periods are used (such as --monthly), this can get somewhat confusing.  In that case, you'll probably want to sort within periods using --period-sort instead of --sort.

And if the register seems too cramped, and you have a lot of screen real estate, you can use -w to format the report within 132 acolumns, instead of 80.  You are more likely then to see full payee and account names, as well as properly formatted totals when long-named commodities are used.

If you want only the first or last N transactions to be printed---which can be very useful for viewing the last 10 transactions in your checking account, while also showing the cumulative balance from all transactions---use the --head and/or --tail options.  The two options may be used simultaneously, for example:

     ledger --tail 20 reg checking

If the output from your command is very long, Ledger can output the data to a pager utility, such as more or less:

     ledger --pager /usr/bin/less reg checking

Averages and percentages
------------------------

To see the running total changed to a running average, use -A.  The final posting's total will be the overall average of all displayed postings.  The works in conjunction with period reporting, so that you can see your monthly average expenses with:

     ledger -AM  reg ^expenses:food
     ledger -AMn reg ^expenses

This works in the balance report too:

     ledger -AM  bal ^expenses:food
     ledger -AMs bal ^expenses

The -D option changes the running average into a deviation from the running average.  This only makes sense in the register report, however.

     ledger -DM reg ^expenses:food

In the balance report only, -% changes the reported totals into a percentage of the parent account.  This kind of report is confusing if negative amounts are involved, and doesn't work at all if multiple commodities occur in an account's history.  It has a somewhat limited usefulness, therefore, but in certain cases it can be handy, such as reviewing overall expenses:

     ledger -%s -S T bal ^expenses

Reporting total data
--------------------

Normally in the xml report, only posting amounts are printed.  To include the running total under a <total> tag, use --totals.  This does not affect any other report.

In the register report only, the output can be changed with -j to show only the date and the amount---without commodities.  This only makes sense if a single commodity appears in the report, but can be quite useful for scripting, or passing the data to Gnuplot.  To show only the date and running total, use -J.

Display by value expression
---------------------------

With -d you can decide which postings (or accounts in the balance report) are displayed, according to a value expression.  The computed total is not affected, only the display.  This can be very useful for shortening a report without changing the running total:

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

This command shows the checking account's register, beginning from last month, but with the running total reflecting the entire history of the account.

Change report format
--------------------

When dates are printed in any report, the default format is %Y/%m/%d, which yields dates of the form YYYY/mm/dd. This can be changed with -y, whose argument is a strftime string---see your system's C library documentation for the allowable codes.  Mostly you will want to use %Y, %m and %d, in whatever combination is convenient for your locale.

To change the format of the entire reported line, use -F.  It supports quite a large number of options, which are all documented in Format strings.  In addition, each specific kind of report (except for xml) can be changed using one of the following options:

--balance-format
     balance report.  Default:

          %20T  %2_%-a\n

--register-format
     register report.  Default:

          %D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n

--print-format
     print report.  Default:

          %D  %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n

--plot-amount-format
     register report when -j (plot amount) is used.  Default:

          %D %(St)\n

--plot-total-format
     register report when -J (plot total) is used.  Default:

          %D %(ST)\n

--equity-format
     equity report.  Default:

          \n%D %Y%C%P\n    %-34W  %12o%n\n%/    %-34W  %12o%n\n

--prices-format
     prices report.  Default:

          \n%D %Y%C%P\n%/    %-34W  %12t\n

--wide-register-format
     register report when -w (wide) is used.  Default:

          %D  %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n

Standard queries
================

If your ledger file uses the standard top-level accounts: Assets, Liabilities, Income, Expenses, Equity: then the following queries will enable you to generate some typical accounting reports from your data.

Your net worth can be determined by balancing assets against liabilities:

     ledger bal ^assets ^liab

By removing long-term investment and loan accounts, you can see your current net liquidity (or liquid net worth):

     ledger bal ^assets ^liab -retirement -brokerage -loan

Balancing expenses against income yields your cash flow, or net profit/loss:

     ledger bal ^exp ^inc

In this case, if the number is positive it means you spent more than you earned during the report period.

The most often used command is the ``balance'' command:

     export LEDGER=/home/johnw/doc/ledger.dat
     ledger balance

Here I've set my Ledger environment variable to point to where my ledger file is hiding.  Thereafter, I needn't specify it again.

Reporting balance totals
========================

The balance command prints out the summarized balances of all my top-level accounts, excluding sub-accounts.  In order to see the balances for a specific account, just specify a regular expression after the balance command:

     ledger balance expenses:food

This will show all the money that's been spent on food, since the beginning of the ledger.  For food spending just this month (September), use:

     ledger -p sep balance expenses:food

Or maybe you want to see all of your assets, in which case the -s (show sub-accounts) option comes in handy:

     ledger -s balance ^assets

To exclude a particular account, use a regular expression with a leading minus sign.  The following will show all expenses, but without food spending:

     ledger balance expenses -food

Reporting percentages
=====================

There is no built-in way to report posting amounts or account balances in terms of percentages

Ledger in Practice
******************

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.

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 period 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" -MAs bal ^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 -M reg ^exp

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

     ledger --budget -M reg ^exp

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 -M reg ^exp

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

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.

Archiving previous years
========================

After a while, your ledger can get to be pretty large.  While this will not slow down the ledger program much---it's designed to process ledger files 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.

Virtual postings
================

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

Automated postings
==================

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.

Using Emacs to Keep Your Ledger
===============================

In the Ledger tarball is an Emacs module, ledger.el.  This module makes the process of keeping a text ledger much easier for Emacs users.  I recommend putting this at the top of your ledger file:

     ; -*-ledger-*-

And this in your .emacs file, after copying ledger.el to your site-lisp directory:

     (load "ledger")

Now when you edit your ledger file, it will be in ledger-mode.  ledger-mode adds these commands:

C-c C-a
     For quickly adding new transactions based on the form of older ones (see previous section).

C-c C-c
     Toggles the ``cleared'' flag of the posting under point.

C-c C-d
     Delete the transaction under point.

C-c C-r
     Reconciles an account by displaying the postings in another buffer, where simply hitting the spacebar will toggle the pending flag of the posting in the ledger.  Once all the appropriate postings have been marked, press C-c C-c in the reconcile buffer to ``commit'' the reconciliation, which will mark all of the transactions as cleared, and display the new cleared balance in the minibuffer.

C-c C-m
     Set the default month for new transactions added with C-c C-a.  This is handy if you have a large number of postings to enter from a previous month.

C-c C-y
     Set the default year for new transactions added with C-c C-a.  This is handy if you have a large number of postings to enter from a previous year.

Once you enter the reconcile buffer, there are several key commands available:

RET
     Visit the ledger file transaction corresponding to the reconcile transaction.

C-c C-c
     Commit the reconcialation.  This marks all of the marked postings as ``cleared'', saves the ledger file, and then displays the new cleared balance.

C-l
     Refresh the reconcile buffer by re-reading postings from the ledger data file.

SPC
     Toggle the posting under point as cleared.

a
     Add a new transaction to the ledger data file, and refresh the reconcile buffer to include its postings (if the transaction is added to the same account as the one being reconciled).

d
     Delete the transaction related to the posting under point.  Note: This may result in multiple postings being deleted.

n
     Move to the next line.

p
     Move to the previous line.

C-c C-r

r
     Attempt to auto-reconcile the postings to the entered balance.  If it can do so, it will mark all those postings as pending that would yield the specified balance.

C-x C-s

s
     Save the ledger data file, and show the current cleared balance for the account being reconciled.

q
     Quit the reconcile buffer.

There is also an emacs command which can be used to output reports in a format directly read-able from Emacs Lisp.

Using GnuCash to Keep Your Ledger
=================================

The Ledger tool is fast and simple, but it offers no custom method for actually editing the ledger.  It assumes you know how to use a text editor, and like doing so.  There is, at least, an Emacs mode that makes editing Ledger's data files much easier.

You are also free to use GnuCash to maintain your ledger, and the Ledger program for querying and reporting on the contents of that ledger.  It takes a little longer to parse the XML data format that GnuCash uses, but the end result is identical.

Then again, why would anyone use a Gnome-centric, multi-megabyte behemoth to edit their data, and only a one megabyte binary to query it?

Using timeclock to record billable time
=======================================

The timeclock tool makes it easy to track time events, like clocking into and out of a particular job.  These events accumulate in a timelog file.

Each in/out event may have an optional description.  If the ``in'' description is a ledger account name, these in/out pairs may be viewed as virtual postings, adding time commodities (hours) to that account.

For example, the command-line version of the timeclock tool could be used to begin a timelog file like:

     export TIMELOG=$HOME/.timelog
     ti ClientOne category
     sleep 10
     to waited for ten seconds

The .timelog file now contains:

     i 2004/10/06 15:21:00 ClientOne  category
     o 2004/10/06 15:21:10 waited for ten seconds

Ledger parses this directly, as if it had seen the following transaction:

     2004/10/06 category
         (ClientOne)      10s

In other words, the timelog event pair is seen as adding 0.00277h (ten seconds) worth of time to the ClientOne account.  This would be considered billable time, which later could be invoiced and credited to accounts receivable:

     2004/11/01 (INV#1) ClientOne, Inc.
         Receivable:ClientOne       $0.10
         ClientOne              -0.00277h @ $35.00

The above posting converts the clocked time into an invoice for the time spent, at an hourly rate of $35.  Once the invoice is paid, the money is deposited from the receivable account into a checking account:

     2004/12/01 ClientOne, Inc.
         Assets:Checking            $0.10
         Receivable:ClientOne

And now the time spent has been turned into hard cash in the checking account.

The advantage to using timeclock and invoicing to bill time is that you will always know, by looking at the balance report, exactly how much unbilled and unpaid time you've spent working for any particular client.

I like to !include my timelog at the top of my company's accounting ledger, with the attached prefix Billable:

     ; -*-ledger-*-

     ; This is the ledger file for my company.  But first, include the
     ; timelog data, entering all of the time events within the umbrella
     ; account "Billable".

     !account Billable
     !include /home/johnw/.timelog
     !end

     ; Here follows this fiscal year's postings for the company.

     2004/11/01 (INV#1) ClientOne, Inc.
         Receivable:ClientOne           $0.10
         Billable:ClientOne         -0.00277h @ $35.00

     2004/12/01 ClientOne, Inc.
         Assets:Checking                $0.10
         Receivable:ClientOne

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

Random things
*************

Whenever a commodity is exchanged for another in a posting, one of the two is considered primary, and the other secondary. Primariness of a commodity is remembered, since the --market option only renders balances into secondary commodities, never primaries.  To render primaries, use the --exchange=COMMODITY option.

In all of the following examples, the P commodity is considered primary and the S is secondary (the P at the beginning of the line indicates a price-setting directive):

     2009/01/01 Sample 1a
         Assets:Brokerage:Stocks                100 S
         Assets:Brokerage:Cash                 -100 P

     P 2009/01/15 00:00:00 S 2 P

     2009/02/01 Sample 2a
         Assets:Brokerage:Stocks                100 S @ 1 P
         Assets:Brokerage:Cash

     P 2009/02/01 00:00:00 S 4 P

     2009/03/01 Sample 3a
         Assets:Brokerage:Stocks                100 S @@ 100 P
         Assets:Brokerage:Cash

     P 2009/03/01 00:00:00 S 8 P

     2009/04/01 Sample 4a
         Assets:Brokerage:Cash                  100 P
         Assets:Brokerage:Stocks               -100 S {1 P}

     P 2009/04/01 00:00:00 S 16 P

Anatomy of a journal file
*************************

Everything begins with a journal file---the anatomy of which is covered in detail in chapter one.  To review: a journal contains one or more transactions, each of which refers to two or more postings.  A posting specifies that a given amount is added to, or subtracted from, an account. (Accounts may be nested hierarchically by separating the elements using a colon).  Lastly, an amount is a figure representing a given quantity of a commodity.  Here follows a review of these terms, which are all used extensively throughout this chapter:

journal
     A journal is a data file containing a series of transactions.

transaction
     a transaction relates a group of two or more postings, with the absolute constraint that the total sum of a transaction's postings must equal zero.  That is, every transaction in a journal must balance to zero.

posting
     Postings record how commodities are moved between accounts.  If you spent money on a movie ticket, for example, such a transaction would have two postings: One to show how the money was taken from your wallet, and another to show how it was applied to your movie expenses.

account
     An account

amount

quantity

commodity

Example accounting practices
****************************

Generating useful reports
*************************

Once you have a journal file representing a recent history of your finances, the next step is to generate reports in order to give richer meaning to this data.  For example: Where do you spend your money?  Do you have enough to cover upcoming expenses?  Are you creating or losing net worth?  Are your investment performing well?  All of these questions can be answered easily with Ledger---if you know how to ask them.

Preparing complex reports is not a simple task, but neither is it a difficult one.  All that's required is a proper understanding of how Ledger views your data, and how it prepares it for reporting.

After Ledger reads a journal file, it creates an in-memory representation reflecting the order and composition of those transactions.

Value expressions
*****************

Format strings
**************

Extensions in Python
********************

The design of Ledger
********************

The following sections discuss how Ledger is architected, from the ground up, and will show how to use the various parts of the Ledger library from your own scripts.  Ledger essentially follows five steps in reporting data to the user:

 1. Parse journal file into an internal representation

 2. Perform any implied math within the journal file

 3. ``Face'' this internal representation as a virtual document

 4. Apply a series of transforms to the virtual document

 5. Display the virtual document using a formatting command

The calculations in step two are specified by the user, such as when a posting's value might contain mathematical operators.  The calculations in step four are implied in the transformations, for example when the --average option is used.

At the core, however, Ledger is basically a sophisticated calculator with special knowledge about commoditized values.  It knows what you mean if you add ten dollars to twenty euros, and later ask for the balance of that particular account.  So it follows that first we must discuss how Ledger deals with math, and from there move on to describing how the steps above are achieved.

Numerics
========

Basic amounts
-------------

The most fundamental type in Ledger is the amount, which may or may not have a commodity attached to it.  First, we'll deal with the bare case, just to show how the amount type works.  In C++, most all of Ledger's internal types end in _t; in Python, the same type name is used, but the _t suffix is dropped.  Examples of usage in both languages will be presented throughout.

amount_t commodity_t updater_t datetime_t balance_t balance_pair_t value_t valexpr_t format_t mask_t

Journal Representation
======================

journal_t account_t xact_t post_t parser_t

Reporting
=========

Terminal Interface
==================

General Utility
===============

     2004/05/01 * Checking balance
         Assets:Bank:Checking                           $1,000.00
         Equity:Opening Balances

                $1,000.00  Assets:Bank:Checking
               $-1,000.00  Equity:Opening Balances
     --------------------
                        0