sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ledger/ledger.texi
John Wiegley fcae023196 Reverted the master branch back to the state of v2.6.0.90, because I intend to 
be much more thorough about what gets commited to the master and why.  This
will still be the branch where new work will be checked in, but only after
thorough review in a development branch.
2008-05-02 01:24:29 -04:00

3960 lines
137 KiB
Text
Raw Blame History

\input texinfo @c -*-texinfo-*-
@setfilename ledger.info
@settitle Ledger: Command-Line Accounting
@dircategory User Applications
@copying
Copyright (c) 2003-2006, 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.
@end copying
@documentencoding iso-8859-1
@iftex
@finalout
@end iftex
@titlepage
@title Ledger: Command-Line Accounting
@author John Wiegley
@end titlepage
@direntry
* Ledger: (ledger). Command Line Accounting
@end direntry
@contents
@ifnottex
@node Top, Introduction, (dir), (dir)
@top Overview
@insertcopying
@end ifnottex
@menu
* Introduction::
* Running Ledger::
* Keeping a ledger::
* Using XML::
@end menu
@node Introduction, Running Ledger, Top, Top
@chapter 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 transactions,
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
transaction two-lines: the source account and target account.
@emph{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 entry might look like this:
@smallexample
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
@end smallexample
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 entry 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 transaction 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 transaction 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
transactions. If a transaction does not balance, Ledger displays an
error and indicates the incorrect transaction.@footnote{In some
special cases, it automatically balances this entry 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 entries.
And just for the sake of example---as a starting point for those who
want to dive in head-first---here are the ledger entries from above,
formatting as the ledger program wishes to see them:
@smallexample
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
@end smallexample
The account balances and registers in this file, if saved as
@file{ledger.dat}, could be reported using:
@example
$ ledger -f ledger.dat balance
$ ledger -f ledger.dat register checking
$ ledger -f ledger.dat register bell
@end example
@menu
* Building the program::
* Getting help::
@end menu
@node Building the program, Getting help, Introduction, Introduction
@section 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:
@example
./configure && make install
@end example
@node Getting help, , Building the program, Introduction
@section 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:
@example
https://lists.sourceforge.net/lists/listinfo/ledger-discuss
@end example
You can also find help at the @samp{#ledger} channel on the IRC server
@samp{irc.freenode.net}.
@node Running Ledger, Keeping a ledger, Introduction, Top
@chapter Running Ledger
Ledger has a very simple command-line interface, named---enticing
enough---@command{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:
@example
ledger [OPTIONS...] COMMAND [ARGS...]
@end example
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 transactions matching those regular
expressions. For the @command{entry} command, the arguments have a
special meaning, described below.
The regular expressions arguments always match the account name that a
transaction refers to. To match on the payee of the entry instead,
precede the regular expression with @samp{--}. For example, the
following balance command reports account totals for rent, food and
movies, but only those whose payee matches Freddie:
@example
ledger bal rent food movies -- freddie
@end example
There are many, many command options available with the
@command{ledger} command, and it takes a while to master them.
However, none of them are required to use the basic reporting
commands.
@menu
* Usage overview::
* Commands::
* Options::
* Format strings::
* Value expressions::
* Period expressions::
* File format::
* Some typical queries::
* Budgeting and forecasting::
@end menu
@node Usage overview, Commands, Running Ledger, Running Ledger
@section Usage overview
Before getting into the details of how to run Ledger, it will be
easier to introduce the features in the context of their typical
usage. To that end, this section 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
@var{LEDGER} is set to the file @file{sample.dat} (which is included
in the distribution), and that the contents of that file are:
@smallexample
= /^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
@end smallexample
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.
@subsection Checking balances
Ledger has seven basic commands, but by far the most often used are
@command{balance} and @command{register}. To see a summary balance of
all accounts, use:
@example
ledger bal
@end example
@command{bal} is a short-hand for @command{balance}. This command
prints out the summary totals of the five parent accounts used in
@file{sample.dat}:
@smallexample
$1,480.00
50 AAPL Assets
$-2,500.00 Equity
$20.00 Expenses
$-500.00 Income
$-2.00 Liabilities
--------------------
$-1,502.00
50 AAPL
@end smallexample
None of the child accounts are shown, just the parent account totals.
We can see that in @samp{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@footnote{It is
impossible for accounts not to balance in ledger; it reports an error
if a transaction 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
transaction being added by the automatic entry at the top of the file.
The entry is virtual because the account name was surrounded by
parentheses in an automatic entry. Automatic entries will be
discussed later, but first let's remove the virtual transaction from
the balance report by using the @option{--real} option:
@example
ledger --real bal
@end example
Now the report is:
@smallexample
$1,480.00
50 AAPL Assets
$-2,500.00 Equity
$20.00 Expenses
$-500.00 Income
--------------------
$-1,500.00
50 AAPL
@end smallexample
Since the liability was a virtual transaction, it has dropped from the
report and we see that final total is balanced.
But we only know that it balances because @file{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 @option{--basis}, or @option{-B}, option:
@example
ledger --real -B bal
@end example
This command reports:
@smallexample
$2,980.00 Assets
$-2,500.00 Equity
$20.00 Expenses
$-500.00 Income
@end smallexample
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,
@emph{which must always be true}. Reporting the real basis cost
should never yield a remainder@footnote{If it ever does, then
generated transactions are involved, which can be removed using
@option{--actual}}.
@subsubsection 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
@option{-s} option:
@example
ledger --real -B -s bal
@end example
This reports:
@smallexample
$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
@end smallexample
This shows that the @samp{Assets} total is made up from two child
account, 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,
@code{T} represents the reported total, and @code{l} is the display
level for the account:
@example
ledger --real -B -d "T&l<=2" bal
@end example
This reports:
@smallexample
$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
@end smallexample
Instead of reporting @samp{Bank:Checking} as a child of @samp{Assets},
it report only @samp{Bank}, since that account is a nesting level of
2, while @samp{Checking} is at level 3.
To review the display predicate used---@code{T&l<=2}---this rather
terse expression means: Display an account only if it has a non-zero
total (@code{T}), and its nesting level is less than or equal to 2
(@code{l<=2}).
@subsubsection 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:
@example
ledger bal checking
@end example
Reports:
@smallexample
$1,480.00 Assets:Bank:Checking
@end smallexample
Any number of names may be used:
@example
ledger bal checking broker liab
@end example
Reports:
@smallexample
$1,480.00 Assets:Bank:Checking
50 AAPL Assets:Brokerage
$-2.00 Liabilities
@end smallexample
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:
@example
ledger bal ^assets.*checking ^liab
@end example
Reports:
@smallexample
$1,480.00 Assets:Bank:Checking
$-2.00 Liabilities:Taxes
@end smallexample
@subsection The register report
While the @command{balance} command can be very handy for checking
account totals, by far the most powerful of Ledger's reporting tools
is the @command{register} command. In fact, internally both commands
use the same logic, but report the results differently:
@command{balance} shows the summary totals, while @command{register}
reports each transaction and how it contributes to that total.
Paradoxically, the most basic form of @command{register} is almost
never used, since it displays every transaction:
@example
ledger reg
@end example
@command{reg} is a short-hand for @command{register}. This command
reports:
@smallexample
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
@end smallexample
This rather verbose output shows every account transaction in
@file{sample.dat}, and how it affects the running total. The final
total is identical to what we saw with the plain @command{balance}
command. To see how things really balance, we can use @samp{--real
-B}, just as we did with @command{balance}:
@example
ledger --real -B reg
@end example
Reports:
@smallexample
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
@end smallexample
Here we see that everything balances to zero in the end, as it must.
@subsubsection Specific register queries
The most common use of the register command is to summarize
transactions based on the account(s) they affect. Using
@file{sample.dat} as as example, we could look at all book purchases
using:
@example
ledger reg books
@end example
Reports:
@smallexample
2004/05/29 Book Store Expenses:Books $20.00 $20.00
@end smallexample
If a double-dash (@samp{--}) occurs in the list of regular
expressions, any following arguments are matched against payee names,
instead of account names:
@example
ledger reg ^liab -- credit
@end example
Reports:
@smallexample
2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00
@end smallexample
There are many reporting options for tailoring which transactions are
found, and also how to summarize the various amounts and totals that
result. These are plumbed in greater depth below.
@subsection Selecting transactions
Although the easiest way to use the register is to report all the
transactions 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 exactly the transactions that interest you most. This is
called the ``calculation'' phase of Ledger. All of its related
options are documented under @option{--help-calc}.
@subsubsection By date
@c -c, --current show only current and past entries (not future)
@option{--current}(@option{-c}) displays entries occurring on or
before the current date. Any entry recorded for a future date will be
ignored, as if it had not been seen. This is useful if you happen to
pre-record entries, but still wish to view your balances in terms of
what is available today.
@c -b, --begin DATE set report begin date
@c -e, --end DATE set report end date
@option{--begin DATE} (@option{-b DATE}) limits the report to only
those entries occurring on or after @var{DATE}. The running total in
the register will start at zero with the first transaction, even if
there are earlier entries.
To limit the display only, but still add earlier transactions to the
running total, use the display expression @samp{-d 'd>=[DATE]'}):
@example
ledger --basis -b may -d 'd>=[5/14]' reg ^assets
@end example
Reports:
@smallexample
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
@end smallexample
In this example, the displayed transactions start from @samp{5/14},
but the calculated total starts from the beginning of @samp{may}.
@option{--end DATE} (@option{-e DATE}) states when reporting should
end, both calculation and display. The ending date is inclusive.
The @var{DATE} argument to the @option{-b} and @option{-e} options can
be rather flexible. Assuming the current date to be November 15,
2004, then all of the following are equivalent:
@example
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
@end example
@c -p, --period STR report using the given period
@c --period-sort EXPR sort each report period's entries by EXPR
To constrain the report to a specific time period, use
@option{--period} (@option{-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:
@example
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
@end example
See @ref{Period expressions} for more on syntax. Also, all of the
options @option{-b}, @option{-e} and @option{-p} may be used together,
but whatever information occurs last takes priority. An example of
such usage (in a script, perhaps) would be:
@example
ledger -b 2004 -e 2005 -p monthly reg ^expenses
@end example
This command is identical to:
@example
ledger -p "monthly in 2004" reg ^expenses
@end example
The transactions within a period may be sorted using
@option{--period-sort}, which takes a value expression. This is
similar to the @option{--sort} option, except that it sorts within
each period entry, rather than sorting all transactions in the report.
See the documentation on @option{--sort} below for more details.
@subsubsection By status
By default, all regular transactions are included in each report. To
limit the report to certain kinds of transactions, use one or more of
the following options:
@table @option
@item -C, --cleared
Consider only cleared transactions.
@item -U, --uncleared
Consider only uncleared and pending transactions.
@item -R, --real
Consider only real (non-virtual) transactions.
@item -L, --actual
Consider only actual (non-automated) transactions.
@end table
Cleared transactions are indicated by an asterix placed just before
the payee name in a transaction. The meaning of this flag is up to
the user, but typically it means that an entry has been seen on a
financial statement. Pending transactions use an exclamation mark in
the same position, but are mainly used only by reconciling software.
Uncleared transactions are for things like uncashed checks, credit
charges that haven't appeared on a statement yet, etc.
Real transactions are all non-virtual transactions, where the account
name is not surrounded by parentheses or square brackets. Virtual
transactions 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 transactions are those not generated, either as part of an
automated entry, or a budget or forecast report. A useful of when you
might like to filter out generated transactions is with a budget:
@example
ledger --budget --actual reg ^expenses
@end example
This command outputs all transactions affecting a budgeted account,
but without subtracting the budget amount (because the generated
transactions are suppressed with @option{--actual}). The report shows
how much you actually spent on budgeted items.
@subsubsection By relationship
@c -r, --related calculate report using related transactions
Normally, a register report includes only the transactions that match
the regular expressions specified after the command word. For
example, to report all expenses:
@example
ledger reg ^expenses
@end example
This reports:
@smallexample
2004/05/29 Book Store Expenses:Books $20.00 $20.00
@end smallexample
Using @option{--related} (@option{-r}) reports the transactions that
did not match your query, but only in entries that otherwise would
have matched. This has the effect of indicating where money came
from, or when to:
@example
ledger -r reg ^expenses
@end example
Reports:
@smallexample
2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00
@end smallexample
@subsubsection By budget
@c --budget generate budget entries based on FILE
There is more information about budgeting and forecasting in
@ref{Budgeting and forecasting}. Basically, if you have any period
entries in your ledger file, you can use these options. A period
entry looks like:
@example
~ Monthly
Assets:Bank:Checking $500.00
Income:Salary
@end example
The difference from a regular entry is that the first line begins with
a tilde (~), and instead of a payee there's a period expression
(@ref{Period expressions}). Otherwise, a period entry is in every
other way the same as a regular entry.
With such an entry in your ledger file, the @option{--budget} option
will report only transactions that match a budgeted account. Using
@file{sample.dat} from above:
@example
ledger --budget reg ^income
@end example
Reports:
@smallexample
2004/05/01 Budget entry Income:Salary $500.00 $500.00
2004/05/14 Pay day Income:Salary $-500.00 0
@end smallexample
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
@option{--budget -p monthly}.
@c --add-budget show all transactions plus the budget
@c --unbudgeted show only unbudgeted transactions
The @option{--add-budget} option reports all matching transactions in
addition to budget transactions; while @option{--unbudgeted} shows
only those that don't match a budgeted account. To summarize:
@table @option
@item --budget
Show transactions matching budgeted accounts.
@item --unbudgeted
Show transactions matching unbudgeted accounts.
@item --add-budget
Show both budgeted and unbudgeted transactions together (i.e., add the
generated budget transactions to the regular report).
@end table
@c --forecast EXPR generate forecast entries while EXPR is true
A report with the @option{--forecast} option will add budgeted
transactions while the specified value expression is true. For
example:
@example
ledger --forecast 'd<[2005] reg ^income
@end example
Reports:
@smallexample
2004/05/14 Pay day Income:Salary $-500.00 $-500.00
2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00
2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00
@end smallexample
The date this report was made was November 5, 2004; the reason the
first forecast entry is in december is that forecast entries are only
added for the future, and they only stop after the value expression
has matched at least once, which is why the January entry appears. A
forecast report can be very useful for determining when money will run
out in an account, or for projecting future cash flow:
@example
ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp
@end example
This reports balances projected income against projected expenses,
showing the resulting total in yearly intervals until 2008. For the
case of @file{sample.dat}, which has no budgeted expenses, the result
of the above command (in November 2004) is:
@smallexample
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
@end smallexample
@subsubsection By value expression
@c -l, --limit EXPR calculate only transactions matching EXPR
Value expressions can be quite complex, and are treated more fully in
@ref{Value expressions}. They can be used for limiting a report with
@option{--limit} (@option{-l}). The following command report income
since august, but expenses since october:
@example
ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg
@end example
The basic form of this value expression is @samp{(A&B)|(A&B)}. The
@samp{A} in each part matches against an account name with
@samp{/name/}, while each @samp{B} part compares the date of the
transaction (@samp{d}) with a specified month. The resulting report
will contain only transactions which match the value expression.
@c -t, --amount EXPR use EXPR to calculate the displayed amount
@c -T, --total EXPR use EXPR to calculate the displayed total
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
transaction amount by two:
@example
ledger -t 'a/2' reg ^exp
@end example
The @option{-t} option doesn't affect the running total, only how the
transaction amount is displayed. To change the running total, use
@option{-T}. In that case, you will likely want to use the total
(@samp{O}) instead of the amount (@samp{a}):
@example
ledger -T 'O/2' reg ^exp
@end example
@subsection Massaging register output
Even after filtering down your data to just the transactions you're
interested in, the default reporting method of one transaction 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 @option{--help-disp}.
@subsubsection Summarizing
@c -n, --collapse register: collapse entries with multiple transactions
When multiple transactions relate to a single entry, they are reported
as part of that entry. For example, in the case of @file{sample.dat}:
@example
ledger reg -- book
@end example
Reports:
@smallexample
2004/05/29 Book Store Expenses:Books $20.00 $20.00
Liabilities:MasterCard $-20.00 0
(Liabilities:Taxes) $-2.00 $-2.00
@end smallexample
All three transactions are part of one entry, and as such the entry
details are printed only once. To report every entry on a single
line, use @option{-n} to collapse entries with multiple transactions:
@example
ledger -n reg -- book
@end example
Reports:
@smallexample
2004/05/29 Book Store <Total> $-2.00 $-2.00
@end smallexample
In the balance report, @option{-n} causes the grand total not to be
displayed at the bottom of the report.
@c -s, --subtotal balance: show sub-accounts; other: show subtotals
If an account occurs more than once in a report, it is possible to
combine them all and report the total per-account, using @option{-s}.
For example, this command:
@example
ledger -B reg ^assets
@end example
Reports:
@smallexample
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
@end smallexample
But if the @option{-s} option is added, the result becomes:
@smallexample
2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00
Assets:Brokerage $1,500.00 $2,980.00
@end smallexample
When account subtotaling is used, only one entry is printed, and the
date and name reflect the range of the combined transactions.
@c -P, --by-payee show summarized totals by payee
With @option{-P}, transactions relating to the same payee are
combined. In this case, the date of the combined entry is that of the
latest transaction.
@c -x, --comm-as-payee set commodity name as the payee, for reporting
@option{-x} changes the payee name for each transaction to be the same
as the commodity it uses. This can be especially useful combined with
other options, like @option{-P}. For example:
@example
ledger -Px reg ^assets
@end example
Reports:
@smallexample
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
@end smallexample
This reports shows the subtotal for each commodity held, and where it
is located. To see the basis cost, or initial investment, add
@option{-B}. Applied to the example above:
@smallexample
2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00
2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00
@end smallexample
@c -E, --empty balance: show accounts with zero balance
The only other options which affect summarized totals is @option{-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.
@subsubsection Quick periods
Although the @option{-p} option (also @option{--period}) is much more
versatile, there are other options to make the most common period
reports easier:
@table @option
@item -W, --weekly
Show weekly sub-totals. Same as @samp{-p weekly}.
@item -M, --monthly
Show monthly sub-totals. Same as @samp{-p monthly}.
@item -Y, --yearly
Show yearly sub-totals. Same as @samp{-p yearly}.
@end table
@c --dow show a days-of-the-week report
There is one kind of period report cannot be done with @option{-p}.
This is the @option{--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:
@example
ledger --dow reg ^inc ^exp
@end example
Reports:
@smallexample
2004/05/27 Thursdays Expenses:Books $20.00 $20.00
2004/05/14 Fridays Income:Salary $-500.00 $-480.00
@end smallexample
@subsubsection Ordering and width
@c -S, --sort EXPR sort report according to the value expression EXPR
The transactions 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 @option{--sort} option. @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:
@example
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
@end example
For the balance report, you will want to use @samp{T} instead of
@samp{t}:
@example
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
@end example
The @option{--sort} options sorts all transactions in a report. If
periods are used (such as @option{--monthly}), this can get somewhat
confusing. In that case, you'll probably want to sort within periods
using @option{--period-sort} instead of @option{--sort}.
@c -w, --wide for the default register report, use 132 columns
And if the register seems too cramped, and you have a lot of screen
real estate, you can use @option{-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 entries to be printed---which can
be very useful for viewing the last 10 entries in your checking
account, while also showing the cumulative balance from all
entries---use the @option{--head} and/or @option{--tail} options. The
two options may be used simultaneously, for example:
@example
ledger --tail 20 reg checking
@end example
If the output from your command is very long, Ledger can output the
data to a pager utility, such as @command{more} or @command{less}:
@example
ledger --pager /usr/bin/less reg checking
@end example
@subsubsection Averages and percentages
@c -A, --average report average transaction amount
To see the running total changed to a running average, use
@option{-A}. The final transaction's total will be the overall
average of all displayed transactions. The works in conjunction with
period reporting, so that you can see your monthly average expenses
with:
@example
ledger -AM reg ^expenses:food
ledger -AMn reg ^expenses
@end example
This works in the balance report too:
@example
ledger -AM bal ^expenses:food
ledger -AMs bal ^expenses
@end example
@c -D, --deviation report deviation from the average
The @option{-D} option changes the running average into a deviation
from the running average. This only makes sense in the register
report, however.
@example
ledger -DM reg ^expenses:food
@end example
@c -%, --percentage report balance totals as a percentile of the parent
In the balance report only, @option{-%} 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:
@example
ledger -%s -S T bal ^expenses
@end example
@subsubsection Reporting total data
@c --totals in the "xml" report, include running total
Normally in the @command{xml} report, only transaction amounts are
printed. To include the running total under a @samp{<total>} tag, use
@option{--totals}. This does not affect any other report.
@c -j, --amount-data print only raw amount data (useful for scripting)
@c -J, --total-data print only raw total data
In the register report only, the output can be changed with
@option{-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 @option{-J}.
@subsubsection Display by value expression
@c -d, --display EXPR display only transactions matching EXPR
With @option{-d} you can decide which transactions (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:
@example
ledger -d 'd>=[last month]' reg checking
@end example
This command shows the checking account's register, beginning from
last month, but with the running total reflecting the entire history
of the account.
@subsubsection Change report format
@c -y, --date-format STR use STR as the date format (default: %Y/%m/%d)
When dates are printed in any report, the default format is
@samp{%Y/%m/%d}, which yields dates of the form @samp{YYYY/mm/dd}.
This can be changed with @option{-y}, whose argument is a
@code{strftime} string---see your system's C library documentation for
the allowable codes. Mostly you will want to use @samp{%Y}, @samp{%m}
and @samp{%d}, in whatever combination is convenient for your locale.
@c -F, --format STR use STR as the format; for each report type, use:
@c --balance-format --register-format --print-format
@c --plot-amount-format --plot-total-format --equity-format
@c --prices-format --wide-register-format
To change the format of the entire reported line, use @option{-F}. It
supports quite a large number of options, which are all documented in
@ref{Format strings}. In addition, each specific kind of report
(except for @command{xml}) can be changed using one of the following
options:
@table @option
@item --balance-format
@command{balance} report. Default:
@smallexample
%20T %2_%-a\n
@end smallexample
@item --register-format
@command{register} report. Default:
@smallexample
%D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n
@end smallexample
@item --print-format
@command{print} report. Default:
@smallexample
%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n
@end smallexample
@item --plot-amount-format
@command{register} report when @option{-j} (plot amount) is used. Default:
@smallexample
%D %(St)\n
@end smallexample
@item --plot-total-format
@command{register} report when @option{-J} (plot total) is used. Default:
@smallexample
%D %(ST)\n
@end smallexample
@item --equity-format
@command{equity} report. Default:
@smallexample
\n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n
@end smallexample
@item --prices-format
@command{prices} report. Default:
@smallexample
\n%D %Y%C%P\n%/ %-34W %12t\n
@end smallexample
@item --wide-register-format
@command{register} report when @option{-w} (wide) is used. Default:
@smallexample
%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n
@end smallexample
@end table
@subsection 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 @emph{net worth} can be determined by balancing assets against
liabilities:
@example
ledger bal ^assets ^liab
@end example
By removing long-term investment and loan accounts, you can see your
current net liquidity (or liquid net worth):
@example
ledger bal ^assets ^liab -retirement -brokerage -loan
@end example
Balancing expenses against income yields your @emph{cash flow}, or net
profit/loss:
@example
ledger bal ^exp ^inc
@end example
In this case, if the number is positive it means you spent more than
you earned during the report period.
@c ----------------------------------------------------------------------
The most often used command is the ``balance'' command:
@example
export LEDGER=/home/johnw/doc/ledger.dat
ledger balance
@end example
Here I've set my Ledger environment variable to point to where my
ledger file is hiding. Thereafter, I needn't specify it again.
@subsection 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:
@example
ledger balance expenses:food
@end example
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:
@example
ledger -p sep balance expenses:food
@end example
Or maybe you want to see all of your assets, in which case the -s
(show sub-accounts) option comes in handy:
@example
ledger -s balance ^assets
@end example
To exclude a particular account, use a regular expression with a
leading minus sign. The following will show all expenses, but without
food spending:
@example
ledger balance expenses -food
@end example
@subsection Reporting percentages
There is no built-in way to report transaction amounts or account
balances in terms of percentages
@node Commands, Options, Usage overview, Running Ledger
@section Commands
@subsection balance
The @command{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.
@subsection register
The @command{register} command displays all the transactions 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
transactions that match. Very useful for hunting down a particular
transaction.
The output from @command{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 @file{report}, which is
included in the Ledger distribution. The only requirement is that you
add either @option{-j} or @option{-J} to your register command, in
order to plot either the amount or total column, respectively.
@subsection print
The @command{print} command prints out ledger entries 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
transactions which match in some way to be printed.
The @command{print} command can be a handy way to clean up a ledger
file whose formatting has gotten out of hand.
@subsection output
The @command{output} command is very similar to the @command{print}
command, except that it attempts to replicate the specified ledger
file exactly. The format of the command is:
@example
ledger -f FILENAME output FILENAME
@end example
Where @file{FILENAME} is the name of the ledger file to output. The
reason for specifying this command is that only entries contained
within that file will be output, and not an included entries (as can
happen with the @command{print} command).
@subsection xml
The @command{xml} command outputs results similar to what
@command{print} and @command{register} display, but as an XML form.
This data can then be read in and processed. Use the
@option{--totals} option to include the running total with each
transaction.
@subsection emacs
The @command{emacs} command outputs results in a form that can be read
directly by Emacs Lisp. The format of the sexp is:
@example
((BEG-POS CLEARED DATE CODE PAYEE
(ACCOUNT AMOUNT)...) ; list of transactions
...) ; list of entries
@end example
@subsection equity
The @command{equity} command prints out accounts balances as if they
were entries. This makes it easy to establish the starting balances
for an account, such as when @ref{Archiving previous years}.
@subsection prices
The @command{prices} command displays the price history for matching
commodities. The @option{-A} flag is useful with this report, to
display the running average price, or @option{-D} to show each price's
deviation from that average.
There is also a @command{pricesdb} command which outputs the same
information as @command{prices}, but does in a format that can be
parsed by Ledger.
@subsection entry
The @command{entry} commands simplifies the creation of new entries.
It works on the principle that 80% of all transactions are variants of
earlier transactions. Here's how it works:
Say you currently have this transaction in your ledger file:
@smallexample
2004/03/15 * Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva
Italiano} again. The exact amounts are different, but the overall
form is the same. With the @command{entry} command you can type:
@example
ledger entry 2004/4/9 viva food 11 tips 2.50
@end example
This produces the following output:
@smallexample
2004/04/09 Viva Italiano
Expenses:Food $11.00
Expenses:Tips $2.50
Liabilities:MasterCard $-13.50
@end smallexample
It works by finding a past transaction matching the regular expression
@samp{viva}, and assuming that any accounts or amounts specified will
be similar to that earlier transaction. If Ledger does not succeed in
generating a new entry, an error is printed and the exit code is set
to @samp{1}.
There is a shell script in the distribution's @file{scripts} directory
called @file{entry}, which simplifies the task of adding a new entry
to your ledger. It launches @command{vi} to confirm that the entry
looks appropriate.
Here are a few more examples of the @command{entry} command, assuming
the above journal entry:
@example
ledger entry 4/9 viva 11.50
ledger entry 4/9 viva 11.50 checking # (from `checking')
ledger entry 4/9 viva food 11.50 tips 8
ledger entry 4/9 viva food 11.50 tips 8 cash
ledger entry 4/9 viva food $11.50 tips $8 cash
ledger entry 4/9 viva dining "DM 11.50"
@end example
@node Options, Format strings, Commands, Running Ledger
@section 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:
@example
ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
@end example
The @var{OPTIONS} and @var{REGEXPS} expressions are both optional.
You could just use @samp{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.
@menu
* Basic options::
* Report filtering::
* Output customization::
* Commodity reporting::
* Environment variables::
@end menu
@node Basic options, Report filtering, Options, Options
@subsection Basic options
These are the most basic command options. Most likely, the user will
want to set them using @ref{Environment variables}, instead of using
actual command-line options:
@option{--help} (@option{-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.
@option{--version} (@option{-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.
@option{--file FILE} (@option{-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
@env{LEDGER_FILE} is set, rather than using this command-line option.
@option{--output FILE} (@option{-o FILE}) redirects output from any
command to @var{FILE}. By default, all output goes to standard
output.
@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by
ledger before any other ledger file. This file may not contain any
transactions, 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:
@smallexample
--price-db ~/finance/.pricedb
; ~/.ledgerrc ends here
@end smallexample
Option settings on the command-line or in the environment always take
precedence over settings in the init file.
@option{--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 @env{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 @env{LEDGER_CACHE}, or by
putting the option into your init file. The @option{--no-cache}
option causes Ledger to always ignore the binary cache.
@option{--account NAME} (@option{-a NAME}) specifies the default
account which QIF file transactions are assumed to relate to.
@node Report filtering, Output customization, Basic options, Options
@subsection Report filtering
These options change which transactions affect the outcome of a
report, in ways other than just using regular expressions:
@option{--current}(@option{-c}) displays only entries occurring on or
before the current date.
@option{--begin DATE} (@option{-b DATE}) constrains the report to
entries on or after @var{DATE}. Only entries 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 entry. (Note: This
is different from using @option{--display} to constrain what is
displayed).
@option{--end DATE} (@option{-e DATE}) constrains the report so that
entries on or after @var{DATE} are not considered. The ending date
is inclusive.
@option{--period STR} (@option{-p STR}) sets the reporting period
to @var{STR}. This will subtotal all matching entries within each
period separately, making it easy to see weekly, monthly, quarterly,
etc., transaction 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
@ref{Period expressions}.
@option{--period-sort EXPR} sorts the transactions within each
reporting period using the value expression @var{EXPR}. This is most
often useful when reporting monthly expenses, in order to view the
highest expense categories at the top of each month:
@example
ledger -M --period-sort -At reg ^Expenses
@end example
@option{--cleared} (@option{-C}) displays only transactions whose entry
has been marked ``cleared'' (by placing an asterix to the right of the
date).
@option{--uncleared} (@option{-U}) displays only transactions whose
entry has not been marked ``cleared'' (i.e., if there is no asterix to
the right of the date).
@option{--real} (@option{-R}) displays only real transactions, not
virtual. (A virtual transaction is indicated by surrounding the
account name with parentheses or brackets; see the section on using
virtual transactions for more information).
@option{--actual} (@option{-L}) displays only actual transactions, and
not those created due to automated transactions.
@option{--related} (@option{-r}) displays transactions that are
related to whichever transactions 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 entries having a related transaction.
For example, if a file had this entry:
@smallexample
2004/03/20 Safeway
Expenses:Food $65.00
Expenses:Cash $20.00
Assets:Checking $-85.00
@end smallexample
And the register command was:
@example
ledger -r register food
@end example
The following would be output, showing the transactions related to the
transaction that matched:
@smallexample
2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00
Assets:Checking $85.00 $65.00
@end smallexample
@option{--budget} is useful for displaying how close your transactions
meet your budget. @option{--add-budget} also shows unbudgeted
transactions, while @option{--unbudgeted} shows only those.
@option{--forecast} is a related option that projects your budget into
the future, showing how it will affect future balances.
@xref{Budgeting and forecasting}.
@option{--limit EXPR} (@option{-l EXPR}) limits which transactions
take part in the calculations of a report.
@option{--amount EXPR} (@option{-t EXPR}) changes the value expression
used to calculate the ``value'' column in the @command{register}
report, the amount used to calculate account totals in the
@command{balance} report, and the values printed in the
@command{equity} report. @xref{Value expressions}.
@option{--total EXPR} (@option{-T EXPR}) sets the value expression
used for the ``totals'' column in the @command{register} and
@command{balance} reports.
@node Output customization, Commodity reporting, Report filtering, Options
@subsection Output customization
These options affect only the output, but not which transactions are
used to create it:
@option{--collapse} (@option{-n}) causes entries in a
@command{register} report with multiple transactions to be collapsed
into a single, subtotaled entry.
@option{--subtotal} (@option{-s}) causes all entries in a
@command{register} report to be collapsed into a single, subtotaled
entry.
@option{--by-payee} (@option{-P}) reports subtotals by payee.
@option{--comm-as-payee} (@option{-x}) changes the payee of every
transaction to be the commodity used in that transaction. This can be
useful when combined with other options, such as @option{-s}.
@option{--empty} (@option{-E}) includes even empty accounts in the
@command{balance} report.
@option{--weekly} (@option{-W}) reports transaction totals by the
week. The week begins on whichever day of the week begins the month
containing that transaction. To set a specific begin date, use a
period string, such as @samp{weekly from DATE}. @option{--monthly}
(@option{-M}) reports transaction totals by month; @option{--yearly}
(@option{-Y}) reports transaction totals by year. For more complex
period, using the @option{--period} option described above.
@option{--dow} reports transactions totals for each day of the week.
This is an easy way to see if weekend spending is more than on
weekdays.
@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
the values determined using the value expression @var{EXPR}. For
example, using @option{-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 @ref{Value
expressions}.
@option{--wide} (@option{-w}) causes the default @command{register}
report to assume 132 columns instead of 80.
@option{--head} causes only the first N entries to be printed. This
is different from using the command-line utility @command{head}, which
would limit to the first N transactions. @option{--tail} outputs only
the last N entries. 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 entries being printed, for example, it
would print all but the first five).
@option{--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 @env{LEDGER_PAGER}
environment variable.
@option{--average} (@option{-A}) reports the average transaction
value.
@option{--deviation} (@option{-D}) reports each transaction's
deviation from the average. It is only meaningful in the
@command{register} and @command{prices} reports.
@option{--percentage} (@option{-%}) shows account subtotals in the
@command{balance} report as percentages of the parent account.
@option{--totals} include running total information in the
@command{xml} report.
@option{--amount-data} (@option{-j}) changes the @command{register}
report so that it output 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.
@option{--total-data} (@option{-J}) changes the @command{register}
report so that it output nothing but the date and totals column,
without commodities.
@option{--display EXPR} (@option{-d EXPR}) limits which transactions
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 transactions, against a running balance which
includes all transaction values:
@example
ledger -d "d>=[last month]" reg checking
@end example
The output from this command is very different from the following,
whose running total includes only transactions from the last month
onward:
@example
ledger -p "last month" reg checking
@end example
Which is more useful depends on what you're looking to know: the total
amount for the reporting range (@option{-p}), or simply a display
restricted to the reporting range (using @option{-d}).
@option{--date-format STR} (@option{-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 @samp{%Y/%m/%d}. To
change the way dates are printed in general, the easiest way is to put
@option{--date-format FORMAT} in the Ledger initialization file
@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).
@option{--format STR} (@option{-F STR}) sets the reporting format for
whatever report ledger is about to make. @xref{Format strings}.
There are also specific format commands for each report type:
@itemize
@item @option{--balance-format STR}
@item @option{--register-format STR}
@item @option{--print-format STR}
@item @option{--plot-amount-format STR} (-j @command{register})
@item @option{--plot-total-format STR} (-J @command{register})
@item @option{--equity-format STR}
@item @option{--prices-format STR}
@item @option{--wide-register-format STR} (-w @command{register})
@end itemize
@node Commodity reporting, Environment variables, Output customization, Options
@subsection Commodity reporting
These options affect how commodity values are displayed:
@option{--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:
@example
; Don't download quotes for the dollar, or timelog values
N $
N h
@end example
@option{--price-exp MINS} (@option{-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
@option{--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.
@option{--download} (@option{-Q}) causes quotes to be automagically
downloaded, as needed, by running a script named @command{getquote}
and expecting that script to return a value understood by ledger. A
sample implementation of a @command{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 @env{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 @option{-t} and @option{-T} options. However,
there are also several ``default'' reports, which will satisfy most
users basic reporting needs:
@table @code
@item -O, --quantity
Reports commodity totals (this is the default)
@item -B, --basis
Reports the cost basis for all transactions.
@item -V, --market
Reports the last known market value for all commodities.
@item -g, --performance
Reports the net gain/loss for each transaction in a @command{register}
report.
@item -G --gain
Reports the net gain/loss for all commodities in the report that have
a price history.
@end table
@node Environment variables, , Commodity reporting, Options
@subsection Environment variables
Every option to ledger may be set using an environment variable. If
an option has a long name such @option{--this-option}, setting the
environment variable @env{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 @file{~/.ledgerrc}, for example:
@example
--cache /tmp/.mycache
@end example
@node Format strings, Value expressions, Options, Running Ledger
@section Format strings
Format strings may be used to change the output format of reports.
They are specified by passing a formatting string to the
@option{--format} (@option{-F}) option. Within that string,
constructs are allowed which make it possible to display the various
parts of an account or transaction in custom ways.
Within a format strings, a substitution is specified using a percent
character (@samp{%}). The basic format of all substitutions is:
@example
%[-][MIN WIDTH][.MAX WIDTH]EXPR
@end example
If the optional minus sign (@samp{-}) 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:
@example
%-P An entry'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
@end example
The expression following the format constraints can be a single
letter, or an expression enclosed in parentheses or brackets. The
allowable expressions are:
@table @code
@item %
Inserts a percent sign.
@item t
Inserts the results of the value expression specified by @option{-t}.
If @option{-t} was not specified, the current report style's value
expression is used.
@item T
Inserts the results of the value expression specified by @option{-T}.
If @option{-T} was not specified, the current report style's value
expression is used.
@item |
Inserts a single space. This is useful if a width is specified, for
inserting a certain number of spaces.
@item _
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 @samp{%5_}, for an account with four parents, will
insert twenty spaces.
@item (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 @samp{%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.
@item [DATEFMT]
Inserts the result of formatting a transaction's date with a date
format string, exactly like those supported by @code{strftime}. For
example: @samp{%[%Y/%m/%d %H:%M:%S]}.
@item S
Insert the pathname of the file from which the entry's data was read.
@item B
Inserts the beginning character position of that entry within the file.
@item b
Inserts the beginning line of that entry within the file.
@item E
Inserts the ending character position of that entry within the file.
@item e
Inserts the ending line of that entry within the file.
@item D
By default, this is the same as @samp{%[%Y/%m%/d]}. The date format
used can be changed at any time with the @option{-y} flag, however.
Using @samp{%D} gives the user more control over the way dates are
output.
@item d
This is the same as the @samp{%D} option, unless the entry has an
effective date, in which case it prints
@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
@item X
If a transaction has been cleared, this inserts @samp{*} followed by a
space; otherwise nothing is inserted.
@item Y
This is the same as @samp{%X}, except that it only displays a state
character if all of the member transactions have the same state.
@item C
Inserts the checking number for an entry, in parentheses, followed by
a space; if none was specified, nothing is inserted.
@item P
Inserts the payee related to a transaction.
@item 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.
@item A
Inserts the full name of an account.
@item W
This is the same as @samp{%A}, except that it first displays the
transaction's state @emph{if the entry's transaction states are not
all the same}, followed by the full account name. This is offered as
a printing optimization, so that combined with @samp{%Y}, only the
minimum amount of state detail is printed.
@item o
Inserts the ``optimized'' form of a transaction's amount. This is
used by the print report. In some cases, this inserts nothing; in
others, it inserts the transaction amount and its cost. It's use is
not recommend unless you are modifying the print report.
@item n
Inserts the note associated with a transaction, preceded by two spaces
and a semi-colon, if it exists. Thus, no none becomes an empty
string, while the note @samp{foo} is substituted as @samp{ ; foo}.
@item N
Inserts the note associated with a transaction, if one exists.
@item /
The @samp{%/} construct is special. It separates a format string
between what is printed for the first transaction of an entry, and
what is printed for all subsequent transactions. If not used, the
same format string is used for all transactions.
@end table
@node Value expressions, Period expressions, Format strings, Running Ledger
@section Value expressions
Value expressions are an expression language used by Ledger to
calculate values used by the program for many different purposes:
@enumerate
@item
The values displayed in reports
@item
For predicates (where truth is anything non-zero), to determine which
transactions are calculated (@option{-l}) or displayed (@option{-d}).
@item
For sorting criteria, to yield the sort key.
@item
In the matching criteria used by automated transactions.
@end enumerate
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 @command{balance} command:
@example
ledger -d /^Liabilities/?T<0:UT>100 balance
@end example
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 entries are printed. For example, the following
command shows only entries from the beginning of the current month,
while still calculating the running balance based on all entries:
@example
ledger -d "d>[this month]" register checking
@end example
This advantage to this command's complexity is that it prints the
running total in terms of all entries in the register. The following,
simpler command is similar, but totals only the displayed
transactions:
@example
ledger -b "this month" register checking
@end example
@subsection Variables
Below are the one letter variables available in any value expression.
For the register and print commands, these variables relate to
individual transactions, and sometimes the account affected by a
transaction. 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.
@table @code
@item t
This maps to whatever the user specified with @option{-t}. In a
register report, @option{-t} changes the value column; in a balance
report, it has no meaning by default. If @option{-t} was not
specified, the current report style's value expression is used.
@item T
This maps to whatever the user specified with @option{-T}. In a
register report, @option{-T} changes the totals column; in a balance
report, this is the value given for each account. If @option{-T} was
not specified, the current report style's value expression is used.
@item m
This is always the present moment/date.
@end table
@subsubsection Transaction/account details
@table @code
@item d
A transaction's date, as the number of seconds past the epoch. This
is always ``today'' for an account.
@item a
The transaction's amount; the balance of an account, without
considering children.
@item b
The cost of a transaction; the cost of an account, without its
children.
@item v
The market value of a transaction, or an account without its children.
@item g
The net gain (market value minus cost basis), for a transaction or an
account without its children. It is the same as @samp{v-b}.
@item l
The depth (``level'') of an account. If an account has one parent,
it's depth is one.
@item n
The index of a transaction, or the count of transactions affecting an
account.
@item X
1 if a transaction's entry has been cleared, 0 otherwise.
@item R
1 if a transaction is not virtual, 0 otherwise.
@item Z
1 if a transaction is not automated, 0 otherwise.
@end table
@subsubsection Calculated totals
@table @code
@item O
The total of all transactions seen so far, or the total of an account
and all its children.
@item N
The total count of transactions affecting an account and all its
children.
@item B
The total cost of all transactions seen so far; the total cost of an
account and all its children.
@item V
The market value of all transactions seen so far, or of an account and
all its children.
@item G
The total net gain (market value minus cost basis), for a series of
transactions, or an account and its children. It is the same as
@samp{V-B}.
@end table
@subsection Functions
The available one letter functions are:
@table @code
@item -
Negates the argument.
@item U
The absolute (unsigned) value of the argument.
@item S
Strips the commodity from the argument.
@item A
The arithmetic mean of the argument; @samp{Ax} is the same as
@samp{x/n}.
@item P
The present market value of the argument. The syntax @samp{P(x,d)} is
supported, which yields the market value at time @samp{d}. If no date
is given, then the current moment is used.
@end table
@subsection Operators
The binary and ternary operators, in order of precedence, are:
@enumerate
@item @samp{* /}
@item @samp{+ -}
@item @samp{! < > =}
@item @samp{& | ?:}
@end enumerate
@subsection Complex expressions
More complicated expressions are possible using:
@table @code
@item NUM
A plain integer represents a commodity-less amount.
@item @{AMOUNT@}
An amount in braces can be any kind of amount supported by ledger,
with or without a commodity. Use this for decimal values.
@item /REGEXP/
@item W/REGEXP/
A regular expression that matches against an account's full name. If
a transaction, this will match against the account affected by the
transaction.
@item //REGEXP/
@item p/REGEXP/
A regular expression that matches against an entry's payee name.
@item ///REGEXP/
@item w/REGEXP/
A regular expression that matches against an account's base name. If
a transaction, this will match against the account affected by the
transaction.
@item c/REGEXP/
A regular expression that matches against the entry code (the text
that occurs between parentheses before the payee name).
@item e/REGEXP/
A regular expression that matches against a transaction's note, or
comment field.
@item (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.
@item [DATE]
Useful specifying a date in plain terms. For example, you could say
@samp{[2004/06/01]}.
@end table
@node Period expressions, File format, Value expressions, Running Ledger
@section Period expressions
A period expression indicates a span of time, or a reporting interval,
or both. The full syntax is:
@example
[INTERVAL] [BEGIN] [END]
@end example
The optional @var{INTERVAL} part may be any one of:
@example
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
@end example
After the interval, a begin time, end time, both or neither may be
specified. As for the begin time, it can be either of:
@example
from <SPEC>
since <SPEC>
@end example
The end time can be either of:
@example
to <SPEC>
until <SPEC>
@end example
Where @var{SPEC} can be any of:
@example
2004
2004/10
2004/10/1
10/1
october
oct
this week # or day, month, quarter, year
next week
last week
@end example
The beginning and ending can be given at the same time, if it spans a
single period. In that case, just use @var{SPEC} by itself. In that
case, the period @samp{oct}, for example, will cover all the days in
october. The possible forms are:
@example
<SPEC>
in <SPEC>
@end example
Here are a few examples of period expressions:
@example
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
@end example
@node File format, Some typical queries, Period expressions, Running Ledger
@section 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:
@table @code
@item NUMBER
A line beginning with a number denotes an entry. It may be followed
by any number of lines, each beginning with whitespace, to denote the
entry's account transactions. The format of the first line is:
@example
DATE[=EDATE] [*|!] [(CODE)] DESC
@end example
If @samp{*} appears after the date (with optional effective date), it
indicates the entry is ``cleared'', which can mean whatever the user
wants it t omean. If @samp{!} appears after the date, it indicates d
the entry is ``pending''; i.e., tentatively cleared from the user's
point of view, but not yet actually cleared. If a @samp{CODE} appears
in parentheses, it may be used to indicate a check number, or the type
of the transaction. Following these is the payee, or a description of
the transaction.
The format of each following transaction is:
@example
ACCOUNT AMOUNT [; NOTE]
@end example
The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
transactions, or square brackets if it is a virtual transactions that
must balance. The @samp{AMOUNT} can be followed by a per-unit
transaction cost, by specifying @samp{@ AMOUNT}, or a complete
transaction cost with @samp{@@ AMOUNT}. Lastly, the @samp{NOTE} may
specify an actual and/or effective date for the transaction by using
the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
@item =
An automated entry. A value expression must appear after the equal
sign.
After this initial line there should be a set of one or more
transactions, just as if it were normal entry. If the amounts of the
transactions have no commodity, they will be applied as modifiers to
whichever real transaction is matched by the value expression.
@item ~
A period entry. A period expression must appear after the tilde.
After this initial line there should be a set of one or more
transactions, just as if it were normal entry.
@item !
A line beginning with an exclamation mark denotes a command directive.
It must be immediately followed by the command word. The supported
commands are:
@table @samp
@item !include
Include the stated ledger file.
@item !account
The account name is given is taken to be the parent of all
transactions that follow, until @samp{!end} is seen.
@item !end
Ends an account block.
@end table
@item ;
A line beginning with a colon indicates a comment, and is ignored.
@item Y
If a line begins with a capital Y, it denotes the year used for all
subsequent entries that give a date without a year. The year should
appear immediately after the Y, for example: @samp{Y2004}. This is
useful at the beginning of a file, to specify the year for that file.
If all entries specify a year, however, this command has no effect.
@item P
Specifies a historical price for a commodity. These are usually found
in a pricing history file (see the @option{-Q} option). The syntax
is:
@example
P DATE SYMBOL PRICE
@end example
@item 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 @file{~/.pricedb}. The syntax for this command is:
@example
N SYMBOL
@end example
@item D AMOUNT
Specifies the default commodity to use, by specifying an amount in the
expected format. The @command{entry} 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:
@example
D $1,000.00
@end example
@item 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:
@example
C 1.00 Kb = 1024 bytes
@end example
@item 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.
@end table
@node Some typical queries, Budgeting and forecasting, File format, Running Ledger
@section Some typical queries
A query such as the following shows all expenses since last
October, sorted by total:
@example
ledger -b "last oct" -s -S T bal ^expenses
@end example
From left to right the options mean: Show entries since October, 2003;
show all sub-accounts; sort by the absolute value of the total; and
report the balance for all expenses.
@subsection Reporting monthly expenses
The following query makes it easy to see monthly expenses, with each
month's expenses sorted by the amount:
@example
ledger -M --period-sort t reg ^expenses
@end example
Now, you might wonder where the money came from to pay for these
things. To see that report, add @option{-r}, which shows the
``related account'' transactions:
@example
ledger -M --period-sort t -r reg ^expenses
@end example
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 transactions
calculated must match @samp{^expenses}, while the transactions
displayed must match @samp{mastercard}. The command would be:
@example
ledger -M -r -d /mastercard/ reg ^expenses
@end example
This query says: Report monthly subtotals; report the ``related
account'' transactions; display only related transactions whose
account matches @samp{mastercard}, and base the calculation on
transactions matching @samp{^expenses}.
This works just as well for report the overall total, too:
@example
ledger -s -r -d /mastercard/ reg ^expenses
@end example
The @option{-s} option subtotals all transactions, just as @option{-M}
subtotaled by the month. The running total in both cases is off,
however, since a display expression is being used.
@subsection Visualizing with Gnuplot
If you have @command{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 @file{scripts/report}. Install
@file{report} anywhere along your @env{PATH}, and then use
@command{report} instead of @command{ledger} when doing a register
report. The only thing to keep in mind is that you must specify
@option{-j} or @option{-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.
@example
report -j -M -r -d /mastercard/ reg ^expenses
@end example
The @command{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.
@subsubsection Typical plots
Here are some useful plots:
@smallexample
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-$ transactions
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
@end smallexample
The last report uses both a calculation predicate (@option{-l}) and a
display predicate (@option{-d}). The calculation predicates limits
the report to transactions whose amount is greater than $1 (which can
only happen if the transaction amount is in dollars). The display
predicate limits the entries @emph{displayed} to just those since last
February, even those entries from before then will be computed as part
of the balance.
@node Budgeting and forecasting, , Some typical queries, Running Ledger
@section Budgeting and forecasting
@subsection 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 entries at the top of your
ledger file. A period entry is almost identical to a regular entry,
except that it begins with a tilde and has a period expression in
place of a payee. For example:
@smallexample
~ 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
@end smallexample
These two period entries 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:
@example
ledger -p "this year" -MAs bal ^expenses
@end example
The reported totals are the current year's average for each account.
Once these period entries are defined, creating a budget report is as
easy as adding @option{--budget} to the command-line. For example, a
typical monthly expense report would be:
@example
ledger -M reg ^exp
@end example
To see the same report balanced against your budget, use:
@example
ledger --budget -M reg ^exp
@end example
A budget report includes only those accounts that appear in the
budget. To see all expenses balanced against the budget, use
@option{--add-budget}. You can even see only the unbudgeted expenses
using @option{--unbudgeted}:
@example
ledger --unbudgeted -M reg ^exp
@end example
You can also use these flags with the @command{balance} command.
@subsection 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 entries as are used for
budgeting. An example forecast report can be generated with:
@example
ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
@end example
This report continues outputting transactions until the running total
is greater than $-500.00. A final transaction 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:
@example
ledger --forecast "d<[2010]" bal ^assets ^liabilities
@end example
@node Keeping a ledger, Using XML, Running Ledger, Top
@chapter Keeping a ledger
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 entry 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 entry 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 entries.
For example, you do not need to tell Ledger about the accounts you
use. Any time Ledger sees a transaction 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
transaction.
Here is the Pacific Bell example from above, given as a Ledger
transaction:
@smallexample
9/29 (100) Pacific Bell
Expenses:Utilities:Phone $23.00
Assets:Checking $-23.00
@end smallexample
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:
@smallexample
9/29 (100) Pacific Bell
Expenses:Utilities:Phone $23.00
Assets:Checking
@end smallexample
For this entry, Ledger will figure out that $-23.00 must come from
@samp{Assets:Checking} in order to balance the entry.
@menu
* Stating where money goes::
* Assets and Liabilities::
* Commodities and Currencies::
* Accounts and Inventories::
* Understanding Equity::
* Dealing with Petty Cash::
* Working with multiple funds and accounts::
* Archiving previous years::
* Virtual transactions::
* Automated transactions::
* Using Emacs to Keep Your Ledger::
* Using GnuCash to Keep Your Ledger::
* Using timeclock to record billable time::
@end menu
@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger
@section 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 transaction will involve two or more accounts.
Money is transferred from one or more accounts to one or more other
accounts. To record the transaction, an amount is @emph{subtracted}
from the source accounts, and @emph{added} to the target accounts.
In order to write a Ledger entry 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:
@smallexample
9/29 My Employer
Assets:Checking $500.00
Income:Salary $-500.00
@end smallexample
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 that when you started your ledger. Make sense?
@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger
@section 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 entry:
@smallexample
2004/09/29 My Employer
Assets:Checking $500.00
Income:Salary
@end smallexample
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:
@smallexample
2004/09/30 Restaurant
Expenses:Dining $25.00
Liabilities:MasterCard
@end smallexample
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:
@example
ledger balance ^assets ^liabilities
@end example
Relatedly, your Income accounts show up negative, because they
transfer money @emph{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:
@example
ledger balance ^income ^expenses
@end example
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:
@example
ledger -M register expenses:auto
@end example
This assumes, of course, that you use account names like
@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.
@subsection 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 @emph{to} your Assets:Reimbursements, using a different account for
each person or business that you spend money for. For example:
@smallexample
2004/09/29 Circuit City
Assets:Reimbursements:Company XYZ $100.00
Liabilities:MasterCard
@end smallexample
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:
@smallexample
2004/09/29 Company XYZ
Assets:Checking $100.00
Assets:Reimbursements:Company XYZ
@end smallexample
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 transaction is best handled with mirrored transactions 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 transactions, so those are what is shown here. First, the
personal entry, which shows the need for reimbursement:
@smallexample
2004/09/29 Circuit City
Assets:Reimbursements:Company XYZ $100.00
Liabilities:MasterCard
@end smallexample
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 entry
should be immediately followed by an equivalent entry, which shows the
kind of expense, and also notes the fact that $100.00 is now payable
to you:
@smallexample
2004/09/29 Circuit City
Company XYZ:Expenses:Computer:Software $100.00
Company XYZ:Accounts Payable:Your Name
@end smallexample
This second entry 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 entries can also be merged, to make things a little clearer.
Note that all amounts must be specified now:
@smallexample
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
@end smallexample
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:
@smallexample
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
@end smallexample
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 @samp{Assets:Reimbursements:Company
XYZ}, and @samp{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 entries 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 transactions in
separate files, just separate the two entries that were joined above.
For example, for both the expense and the pay-back shown above, the
following four entries would be created. Two in your personal ledger
file:
@smallexample
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
@end smallexample
And two in your company ledger file:
@smallexample
!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
@end smallexample
(Note: The @samp{!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 entries, 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.
@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger
@section 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:
@example
$20.00 ; currency: twenty US dollars
40 AAPL ; commodity: 40 shares of Apple stock
60 DM ; currency: 60 Deutsch Mark
<EFBFBD>50 ; currency: 50 British pounds
50 EUR ; currency: 50 Euros (or use appropriate symbol)
@end example
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:
@smallexample
$200.00
100.00 AU
AAPL 40
BORL 100
FEQTX 50 Assets:Brokerage
@end smallexample
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:
@smallexample
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
@end smallexample
Specify the price history to use with the @option{--price-db} option,
with the @option{-V} option to report in terms of current market
value:
@example
ledger --price-db prices.db -V balance brokerage
@end example
The balance for your brokerage account will be reported in US dollars,
since the prices database uses that currency.
@smallexample
$40880.00 Assets:Brokerage
@end smallexample
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:
@example
ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking
@end example
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:
@smallexample
14.01 AU Assets:Checking
@end smallexample
@subsection 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 entries might look like those below:
@smallexample
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
@end smallexample
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.
@subsection 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 transactions, one which
transfers an hour of time into a @samp{Billable} account, and another
which decreases the same account by ten minutes. The resulting report
will indicate that fifty minutes remain:
@smallexample
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
@end smallexample
Reporting the balance for this ledger file produces:
@smallexample
50.0m Billable:Client
-50.0m Project:XYZ
@end smallexample
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:
@smallexample
C 1.00 Kb = 1024 b
C 1.00 Mb = 1024 Kb
C 1.00 Gb = 1024 Mb
C 1.00 Tb = 1024 Gb
@end smallexample
Each of these definitions correlates a commodity (such as @samp{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 @samp{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.
@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger
@section 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:
@smallexample
9/29 Get some stuff at the Inn
Places:Black's Tavern -3 Apples
Places:Black's Tavern -5 Steaks
EverQuest:Inventory
@end smallexample
Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The
amounts are negative, because you are taking @emph{from} Black's
Tavern in order to add to your Inventory account. Note that you don't
have to use @samp{Places:Black's Tavern} as the source account. You
could use @samp{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 entry
would look like:
@smallexample
10/2 Sturm Brightblade
EverQuest:Inventory -2 Steaks
EverQuest:Inventory 15 Gold
@end smallexample
Now you've turned 2 steaks into 15 gold, courtesy of your customer,
Sturm Brightblade.
@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Keeping a ledger
@section Understanding Equity
The most confusing entry 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 an entry to your ledger to reflect this amount.
Where will money come from? The answer: your equity.
@smallexample
10/2 Opening Balance
Assets:Checking $100.00
Equity:Opening Balances
@end smallexample
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
@samp{-Equity} at the end of your balance command, to remove the
confusing figure from the total.
@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Keeping a ledger
@section 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 transactions, 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 @samp{Expenses:Cash} category:
@smallexample
2004/03/15 ATM
Expenses:Cash $100.00
Assets:Checking
@end smallexample
If at some point you make a large cash expense that you want to track,
just ``move'' the amount of the expense from @samp{Expenses:Cash} into
the target account:
@smallexample
2004/03/20 Somebody
Expenses:Food $65.00
Expenses:Cash
@end smallexample
This way, you can still track large cash expenses, while ignoring all
of the smaller ones.
@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Keeping a ledger
@section 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:
@itemize
@item Checking
@item Savings
@item Credit Card
@end itemize
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:
@itemize
@item School fund
@item Building fund
@item Community fund
@end itemize
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 @samp{$500.00}, but
@samp{$400.00} of that comes from Checking, and @samp{$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 transactions to represent the fact that money is moving to and
from two kind of accounts at the same time:
@smallexample
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
@end smallexample
The use of square brackets in the second entry ensures that the
virtual transactions balance to zero. Now money can be spent directly
from a fund at the same time as money is drawn from a physical
account:
@smallexample
2004/03/25 Payment for books (paid from Checking)
Expenses:Books $100.00
Assets:Checking $-100.00
(Funds:School) $-100.00
@end smallexample
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
@samp{Assets} account, because otherwise the balance won't make much
sense:
@example
ledger bal -^Assets
@end example
If the @option{--real} option is used, the report will be in terms of
the real accounts:
@example
ledger --real bal
@end example
If more asset accounts are needed as the source of a transaction, just
list them as you would normally, for example:
@smallexample
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
@end smallexample
The second way of tracking funds is to use entry codes. In this
respect the codes become like virtual accounts that embrace the entire
set of transactions. Basically, we are associating an entry with a
fund by setting its code. Here are two entries that desposit money
into, and spend money from, the @samp{Funds:School} fund:
@smallexample
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
@end smallexample
Note how the accounts now relate only to the real accounts, and any
balance or registers reports will reflect this. That the entries
relate to a particular fund is kept only in the code.
How does this become a fund report? By using the
@option{--code-as-payee} option, you can generate a register report
where the payee for each transaction shows the code. Alone, this is
not terribly interesting; but when combined with the
@option{--by-payee} option, you will now see account subtotals for any
transactions related to a specific fund. So, to see the current
monetary balances of all funds, the command would be:
@smallexample
ledger --code-as-payee -P reg ^Assets
@end smallexample
Or to see a particular funds expenses, the @samp{School} fund in this
case:
@smallexample
ledger --code-as-payee -P reg ^Expenses -- School
@end smallexample
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 entries. Your own tastes will decide which
is best for your situation.
@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Keeping a ledger
@section 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: @command{print}, and @command{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
@command{print} to output all the earlier entries to a file called
@file{ledger-old.dat}:
@smallexample
ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat
@end smallexample
To delete older data from the current ledger file, use @command{print}
again, this time specifying year 2002 as the starting date:
@example
ledger -f ledger.dat -b 2002 print > x
mv x ledger.dat
@end example
However, now the current file contains @emph{only} transactions 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:
@example
ledger -f ledger-old.dat equity > equity.dat
cat equity.dat ledger.dat > x
mv x ledger.dat
rm equity.dat
@end example
Now the balances reported from @file{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.
@node Virtual transactions, Automated transactions, Archiving previous years, Keeping a ledger
@section Virtual transactions
A virtual transaction 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 transaction, surround the account name in
parentheses. This form of usage does not need to balance. However,
if you want to ensure the virtual transaction balances with other
virtual transactions in the same entry, use square brackets. For
example:
@smallexample
10/2 Paycheck
Assets:Checking $1000.00
Income:Salary $-1000.00
(Debt:Alimony) $200.00
@end smallexample
In this example, after receiving a paycheck an alimony debt is
increased---even though no money has moved around yet.
@smallexample
10/2 Paycheck
Assets:Checking $1000.00
Income:Salary $-1000.00
[Savings:Trip] $200.00
[Assets:Checking] $-200.00
@end smallexample
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 @samp{Savings:Trip}, although no money has actually
moved anywhere.
When balances are displayed, virtual transactions will be factored in.
To view balances without any virtual balances factored in, using the
@option{-R} flag, for ``reality''.
@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Keeping a ledger
@section Automated transactions
As a Bah<61>'<27>, I need to compute Huq<75>qu'll<6C>h whenever I acquire assets.
It is similar to tithing for Jews and Christians, or to Zak<61>t for
Muslims. The exact details of computing Huq<75>qu'll<6C>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 transaction at the top of your ledger file:
@smallexample
; This automated entry will compute Huq<75>qu'll<6C>h based on this
; journal's transactions. Any that match will affect the
; Liabilities:Huququ'llah account by 19% of the value of that
; transaction.
= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
(Liabilities:Huququ'llah) 0.19
@end smallexample
This automated transaction works by looking at each transaction in the
ledger file. If any match the given value expression, 19% of the
transaction's value is applied to the @samp{Liabilities:Huququ'llah}
account. So, if $1000 is earned from @samp{Income:Salary}, $190 is
added to @samp{Liabilities:Huq<75>qu'll<6C>h}; if $1000 is spent on Rent,
$190 is subtracted. The ultimate balance of Huq<75>qu'll<6C>h reflects how
much is owed in order to fulfill one's obligation to Huq<75>qu'll<6C>h.
When ready to pay, just write a check to cover the amount shown in
@samp{Liabilities:Huququ'llah}. That entry would look like:
@smallexample
2003/01/01 (101) Baha'i Huq<75>qu'll<6C>h Trust
Liabilities:Huququ'llah $1,000.00
Assets:Checking
@end smallexample
That's it. To see how much Huq<75>q is currently owed based on your
ledger entries, use:
@example
ledger balance Liabilities:Huquq
@end example
This works fine, but omits one aspect of the law: that Huquq is only
due once the liability exceeds the value of 19 mithq<68>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:
@smallexample
ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab
@end smallexample
With this command, the current price for gold is downloaded, and the
Huq<EFBFBD>qu'll<6C>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:
@smallexample
ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab
@end smallexample
In some cases, you may wish to refer to the account of whichever
transaction matched your automated entry's value expression. To do
this, use the special account name @samp{$account}:
@smallexample
= /^Some:Long:Account:Name/
[$account] -0.10
[Savings] 0.10
@end smallexample
This example causes 10% of the matching account's total to be deferred
to the @samp{Savings} account---as a balanced virtual transaction,
which may be excluded from reports by using @option{--real}.
@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Keeping a ledger
@section Using Emacs to Keep Your Ledger
In the Ledger tarball is an Emacs module, @file{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:
@example
; -*-ledger-*-
@end example
And this in your @file{.emacs} file, after copying @file{ledger.el} to
your @file{site-lisp} directory:
@example
(load "ledger")
@end example
Now when you edit your ledger file, it will be in
@command{ledger-mode}. @command{ledger-mode} adds these commands:
@table @strong
@item C-c C-a
For quickly adding new entries based on the form of older ones (see
previous section).
@item C-c C-c
Toggles the ``cleared'' flag of the transaction under point.
@item C-c C-d
Delete the entry under point.
@item C-c C-r
Reconciles an account by displaying the transactions in another
buffer, where simply hitting the spacebar will toggle the pending flag
of the transaction in the ledger. Once all the appropriate
transactions have been marked, press C-c C-c in the reconcile buffer
to ``commit'' the reconciliation, which will mark all of the entries
as cleared, and display the new cleared balance in the minibuffer.
@item C-c C-m
Set the default month for new entries added with C-c C-a. This is
handy if you have a large number of transactions to enter from a
previous month.
@item C-c C-y
Set the default year for new entries added with C-c C-a. This is
handy if you have a large number of transactions to enter from a
previous year.
@end table
Once you enter the reconcile buffer, there are several key commands
available:
@table @strong
@item RET
Visit the ledger file entry corresponding to the reconcile entry.
@item C-c C-c
Commit the reconcialation. This marks all of the marked transactions
as ``cleared'', saves the ledger file, and then displays the new
cleared balance.
@item C-l
Refresh the reconcile buffer by re-reading transactions from the
ledger data file.
@item SPC
Toggle the transaction under point as cleared.
@item a
Add a new entry to the ledger data file, and refresh the reconcile
buffer to include its transactions (if the entry is added to the same
account as the one being reconciled).
@item d
Delete the entry related to the transaction under point. Note: This
may result in multiple transactions being deleted.
@item n
Move to the next line.
@item p
Move to the previous line.
@item C-c C-r
@item r
Attempt to auto-reconcile the transactions to the entered balance. If
it can do so, it will mark all those transactions as pending that
would yield the specified balance.
@item C-x C-s
@item s
Save the ledger data file, and show the current cleared balance for
the account being reconciled.
@item q
Quit the reconcile buffer.
@end table
There is also an @command{emacs} command which can be used to output
reports in a format directly @code{read}-able from Emacs Lisp.
@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Keeping a ledger
@section 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. Perhaps an Emacs mode will appear someday
soon to make editing Ledger's data files much easier.
Until then, you are 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, 35 megabyte behemoth
to edit their data, and a one megabyte binary to query it?
@node Using timeclock to record billable time, , Using GnuCash to Keep Your Ledger, Keeping a ledger
@section 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 transactions, 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:
@example
export TIMELOG=$HOME/.timelog
ti ClientOne category
sleep 10
to waited for ten seconds
@end example
The @file{.timelog} file now contains:
@smallexample
i 2004/10/06 15:21:00 ClientOne category
o 2004/10/06 15:21:10 waited for ten seconds
@end smallexample
Ledger parses this directly, as if it had seen the following entry:
@smallexample
2004/10/06 category
(ClientOne) 10s
@end smallexample
In other words, the timelog event pair is seen as adding 0.00277h (ten
seconds) worth of time to the @samp{ClientOne} account. This would be
considered billable time, which later could be invoiced and credited
to accounts receivable:
@smallexample
2004/11/01 (INV#1) ClientOne, Inc.
Receivable:ClientOne $0.10
ClientOne -0.00277h @@ $35.00
@end smallexample
The above transaction 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:
@smallexample
2004/12/01 ClientOne, Inc.
Assets:Checking $0.10
Receivable:ClientOne
@end smallexample
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 @samp{!include} my timelog at the top of my company's
accounting ledger, with the attached prefix @samp{Billable}:
@smallexample
; -*-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 transactions 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
@end smallexample
@node Using XML, , Keeping a ledger, Top
@chapter 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 chapter documents that format.
The general format used for Ledger data is:
@smallexample
<?xml version="1.0"?>
<ledger>
<entry>...</entry>
<entry>...</entry>
<entry>...</entry>...
</ledger>
@end smallexample
The data stream is enclosed in a @samp{ledger} tag, which contains a
series of one or more entries. Each @samp{entry} describes the entry
and contains a series of one or more transactions:
@smallexample
<entry>
<en:date>2004/03/01</en:date>
<en:cleared/>
<en:code>100</en:code>
<en:payee>John Wiegley</en:payee>
<en:transactions>
<transaction>...</transaction>
<transaction>...</transaction>
<transaction>...</transaction>...
</en:transactions>
</entry>
@end smallexample
The date format for @samp{en:date} is always @samp{YYYY/MM/DD}. The
@samp{en:cleared} tag is optional, and indicates whether the
transaction has been cleared or not. There is also an
@samp{en:pending} tag, for marking pending transactions. The
@samp{en:code} and @samp{en:payee} tags both contain whatever text the
user wishes.
After the initial entry data, there must follow a set of transactions
marked with @samp{en:transactions}. Typically these transactions will
all balance each other, but if not they will be automatically balanced
into an account named @samp{<Unknown>}.
Within the @samp{en:transactions} tag is a series of one or more
@samp{transaction}'s, which have the following form:
@smallexample
<transaction>
<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>
</transaction>
@end smallexample
This is a basic transaction. It may also be begin with
@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual
and auto-generated transactions. Then follows the @samp{tr:account}
tag, which contains the full name of the account the transaction is
related to. Colons separate parent from child in an account name.
Lastly follows the amount of the transaction, indicated by
@samp{tr:amount}. Within this tag is a @samp{value} tag, of which
there are four different kinds, each with its own format:
@enumerate
@item boolean
@item integer
@item amount
@item balance
@end enumerate
The format of a boolean value is @samp{true} or @samp{false}
surrounded by a @samp{boolean} tag, for example:
@smallexample
<boolean>true</boolean>
@end smallexample
The format of an integer value is the numerical value surrounded by an
@samp{integer} tag, for example:
@smallexample
<integer>12036</integer>
@end smallexample
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:
@table @strong
@item P
The commodity is prefixed to the value.
@item S
The commodity is separated from the value by a space.
@item T
Thousands markers are used to display the amount.
@item E
The format of the amount is European, with period used as a thousands
marker, and comma used as the decimal point.
@end table
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:
@smallexample
<value type="amount">
<amount>
<commodity flags="PT">$</commodity>
<quantity>90.00</quantity>
</amount>
</value>
@end smallexample
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:
@smallexample
<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>
@end smallexample
That is the extent of the XML data format used by Ledger. It will
output such data if the @command{xml} command is used, and can read
the same data as long as the @file{expat} library was available
when Ledger was built.
@bye
Reference in a new issue View git blame Copy permalink