Cookbook
========

Invoking Ledger
---------------

     ledger --group-by "tag('trip')" bal
     legder reg --sort "tag('foo')" %foo
     ledger cleared VWCU NFCU Tithe Misentry
     ledger register Joint --uncleared
     ledger register NFCUChecking  --sort d  -d 'd>[2011/04/01]' until 2011/05/25

Ledger Files
------------

     = /^Income:Taxable/
       (Liabilities:Tithe Owed)    -0.1
     = /Noah/
       (Liabilities:Tithe Owed)    -0.1
     = /Jonah/
       (Liabilities:Tithe Owed)    -0.1
     = /Tithe/
       (Liabilities:Tithe Owed)    -1.0

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

This chapter describes '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.

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

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

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

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

     ledger bal rent food movies -- freddie

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

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

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 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. Typically, the environment variable LEDGER_FILE is set, rather than using this command-line option.

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

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

     --price-db ~/finance/.pricedb
     --cache /tmp/ledger-cache

     ; ~/.ledgerrc ends here

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

--cache FILE identifies FILE as the default binary cache file.  That is, if the ledger files to be read are specified using the environment variable LEDGER_FILE, then whenever a command is finished a binary copy will be written to the specified cache, to speed up the loading time of subsequent queries.  This filename can also be given using the environment variable LEDGER_CACHE, or by putting the option into your init file.  The --no-cache option causes 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 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 initialization file ~/.ledgerrc (or the file referred to by LEDGER_INIT).

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

  * --balance-format STR

  * --register-format STR

  * --print-format STR

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

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

  * --equity-format STR

  * --prices-format STR

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

Commodity reporting
-------------------

These options affect how commodity values are displayed:

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

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

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

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

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

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

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

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

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

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

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

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

     --cache /tmp/.mycache
     --pager /bin/cat

Period expressions
==================

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

     [INTERVAL] [BEGIN] [END]

The optional INTERVAL part may be any one of:

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

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

     from <SPEC>
     since <SPEC>

The end time can be either of:

     to <SPEC>
     until <SPEC>

Where SPEC can be any of:

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

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

     <SPEC>
     in <SPEC>

Here are a few examples of period expressions:

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

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