2104 lines
75 KiB
Text
2104 lines
75 KiB
Text
\input texinfo @c -*-texinfo-*-
|
||
|
||
@setfilename ledger.info
|
||
@settitle Ledger: Command-Line Accounting
|
||
|
||
@documentencoding iso-8859-1
|
||
|
||
@iftex
|
||
@finalout
|
||
@end iftex
|
||
|
||
@titlepage
|
||
@title Ledger: Command-Line Accounting
|
||
@author John Wiegley
|
||
@end titlepage
|
||
|
||
@node Top, Introduction, (dir), (dir)
|
||
@top Overview
|
||
@c Page published by Emacs Muse begins here
|
||
|
||
|
||
|
||
@menu
|
||
* Introduction::
|
||
* Running Ledger::
|
||
* Keeping a ledger::
|
||
@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:
|
||
|
||
@example
|
||
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 example
|
||
|
||
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 will display
|
||
an error and indicate which transaction is wrong.@footnote{In some
|
||
special cases, it will automatically balance the 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:
|
||
|
||
@example
|
||
; Set the year for subsequent entries to 2004
|
||
Y 2004
|
||
|
||
9/29 Pacific Bell
|
||
Payable:Pacific Bell $-200.00
|
||
Equity:Opening Balances
|
||
|
||
9/29 Checking
|
||
Accounts:Checking $100.00
|
||
Equity:Opening Balances
|
||
|
||
9/29 Pacific Bell
|
||
Payable:Pacific Bell $23.00
|
||
Accounts:Checking
|
||
@end example
|
||
|
||
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::
|
||
@end menu
|
||
|
||
@node Building the program, , Introduction, Introduction
|
||
@section Building the program
|
||
|
||
Ledger is written in ANSI C++, and should compile on any platform. It
|
||
depends only on the GNU multiprecision integer library (libgmp), and
|
||
the Perl regular expression library (libpcre). It was developed using
|
||
GNU make and gcc 3.3.
|
||
|
||
To build and install once you have these libraries on your system,
|
||
enter these commands:
|
||
|
||
@example
|
||
make
|
||
cp ledger /usr/local/bin
|
||
@end example
|
||
|
||
Note that when building GNUmp, make sure to pass the
|
||
@option{--enable-cxx} flag to configure, otherwise it will not build
|
||
@file{libgmpxx.a}. And in case it is not already on your system,
|
||
@file{xmlparse.h} is part of the libxmltok package, and not expat.
|
||
|
||
@node Running Ledger, Keeping a ledger, Introduction, Top
|
||
@chapter Running Ledger
|
||
|
||
@menu
|
||
* Commands::
|
||
* Options::
|
||
* Format strings::
|
||
* Value expressions::
|
||
* Interval expressions::
|
||
* Plotting register data::
|
||
* Typical queries::
|
||
* File format::
|
||
@end menu
|
||
|
||
@node Commands, Options, Running Ledger, Running Ledger
|
||
@section Commands
|
||
|
||
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.
|
||
|
||
@sp 1
|
||
|
||
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 ``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.
|
||
|
||
@sp 1
|
||
|
||
The @command{print} command prints out ledger entries just as they appear in
|
||
the original 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.
|
||
|
||
@sp 1
|
||
|
||
The @command{equity} commands print out accounts balance as if they were
|
||
transactions. This makes it easy to establish the starting balances
|
||
for an account, when @ref{Archiving previous years}.
|
||
|
||
@sp 1
|
||
|
||
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:
|
||
|
||
Let's say you have an old transaction of the following form:
|
||
|
||
@example
|
||
2004/03/15 * Viva Italiano
|
||
Expenses:Food $12.45
|
||
Expenses:Tips $2.55
|
||
Liabilities:MasterCard $-15.00
|
||
@end example
|
||
|
||
Now it's 2004/4/9, and you've just eating at Viva Italiano again. The
|
||
exact amounts are different, but the overall form is the same. With
|
||
the ``entry'' command you can type:
|
||
|
||
@example
|
||
ledger entry 2004/4/9 viva food 11.00 tips 2.50
|
||
@end example
|
||
|
||
This will produce the following output:
|
||
|
||
@example
|
||
2004/04/09 Viva Italiano
|
||
Expenses:Food $11.00
|
||
Expenses:Tips $2.50
|
||
Liabilities:MasterCard $-13.50
|
||
@end example
|
||
|
||
This works by finding a transaction that matches the regexp ``viva'',
|
||
and then assuming that any accounts or amounts you specify will be the
|
||
same as that earlier transaction. If Ledger does not succeed in
|
||
generating a new entry for you, it will print an error and set the
|
||
exit code to 1.
|
||
|
||
There is a shell script in the distribution called ``entry'', which
|
||
simplifies the task of adding a new entry to your ledger, and then
|
||
launches @command{vi} to let you confirm that the entry looks appropriate.
|
||
|
||
@node Options, Format strings, Commands, Running Ledger
|
||
@section Options
|
||
|
||
With all of the reports, command-line options are useful for modifying
|
||
the output generated. You will often find yourselves adding option
|
||
flags to the command-line to modify those commands.
|
||
|
||
Command-line options always occur before the command word. This is
|
||
done to distinguish them from exclusive matching expressions, which
|
||
also begin with a desh. The basic form for most commands is:
|
||
|
||
@example
|
||
ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
|
||
@end example
|
||
|
||
The @var{OPTIONS} and @var{REGEXPS} expressions are optional. You
|
||
could use just ``ledger balance'' without any options, which would
|
||
print the summarized total for all accounts. But for more specific
|
||
reporting, or to change the appearance of the output, options are
|
||
needed.
|
||
|
||
@subsection Basic 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.
|
||
|
||
@sp 1
|
||
|
||
@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.
|
||
|
||
@sp 1
|
||
|
||
@option{--init 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:
|
||
|
||
@example
|
||
--price-db ~/finance/.pricedb
|
||
@end example
|
||
|
||
Option settings on the command-line or in the environment always take
|
||
precedence over settings in the init file.
|
||
|
||
@sp 1
|
||
|
||
@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
|
||
@var{LEDGER_FILE} is set, rather than using this command-line option.
|
||
|
||
@sp 1
|
||
|
||
@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 @var{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 @var{LEDGER_CACHE}, or by putting the option into
|
||
your init file.
|
||
|
||
@sp 1
|
||
|
||
@option{--output FILE} (@option{-o FILE}) redirects output from any command to
|
||
@var{FILE}. By default, all output goes to standard output.
|
||
|
||
@sp 1
|
||
|
||
@option{--set-price CONV} (@option{-z CONV}) specifies a forced
|
||
commodity conversion. If a setting like @samp{COMM=$1.20} is used,
|
||
the commodity @var{COMM} is reported in terms of the conversion
|
||
factor. This can be useful for performing arbitrary value
|
||
substitutions. For example, to report dollars in terms of the ounces
|
||
of gold they would buy, use: @samp{-z "$=0.00280112 AU"} (or whatever
|
||
the current exchange rate is).
|
||
|
||
@sp 1
|
||
|
||
@option{--account NAME} (@option{-a NAME}) specifies the default
|
||
account which QIF file transactions are assumed to relate to.
|
||
|
||
@subsection Report filtering
|
||
|
||
@option{--begin-date 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).
|
||
|
||
@sp 1
|
||
|
||
@option{--end-date DATE} (@option{-e DATE}) contrains the report so that
|
||
entries on or after @var{DATE} are not considered. This ending date
|
||
is not inclusive, therefore always use a date that is later than the
|
||
last entry you want to see.
|
||
|
||
@sp 1
|
||
|
||
@option{--current}(@option{-c}) displays only entries occurring on or
|
||
before the current date.
|
||
|
||
@sp 1
|
||
|
||
@option{--cleared} (@option{-C}) displays only transactions whose entry
|
||
has been marked ``cleared'' (by placing an asterix to the right of the
|
||
date).
|
||
|
||
@sp 1
|
||
|
||
@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).
|
||
|
||
@sp 1
|
||
|
||
@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).
|
||
|
||
@sp 1
|
||
|
||
@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:
|
||
|
||
@example
|
||
2004/03/20 Safeway
|
||
Expenses:Food $65.00
|
||
Expenses:Cash $20.00
|
||
Assets:Checking
|
||
@end example
|
||
|
||
And if the register command was:
|
||
|
||
@example
|
||
ledger -r register food
|
||
@end example
|
||
|
||
This would be the output, to show the transactions related to the
|
||
transaction that matched.
|
||
|
||
@example
|
||
2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00
|
||
Assets:Checking $85.00 $65.00
|
||
@end example
|
||
|
||
@subsection Output customization
|
||
|
||
@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
|
||
@option{--date-format FORMAT} to the initialize file @file{~/.ledgerc}
|
||
(or the file referred to by @var{LEDGER_INIT}).
|
||
|
||
@sp 1
|
||
|
||
@option{--format STR} (@option{-F STR}) sets the reporting format for
|
||
whatever report ledger is about to make. @xref{Format strings}.
|
||
|
||
You can also set the default format for a given report type, usually
|
||
in the initialization file @file{~/.ledgerrc}, by using one of the
|
||
following options:
|
||
|
||
@table @code
|
||
@item --balance-format STR
|
||
Sets the default format for the @command{balance} report.
|
||
|
||
@item --equity-format STR
|
||
Sets the default format for the @command{equity} report.
|
||
|
||
@item --register-format STR
|
||
Sets the default format for the @command{register} report.
|
||
|
||
@item --print-format STR
|
||
Sets the default format for the @command{print} report.
|
||
|
||
@item --plot-value-format STR
|
||
Sets the default format for the @command{register} report, when @option{-j}
|
||
is being used.
|
||
|
||
@item --plot-total-format STR
|
||
Sets the default format for the @command{register} report, when @option{-J}
|
||
is being used.
|
||
@end table
|
||
|
||
@sp 1
|
||
|
||
@option{--empty} (@option{-E}) includes even empty accounts in the
|
||
@command{balance} report.
|
||
|
||
@sp 1
|
||
|
||
@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.
|
||
|
||
@sp 1
|
||
|
||
@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 -AT} 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}.
|
||
|
||
@sp 1
|
||
|
||
@option{--interval STR} (@option{-p STR}) sets the reporting interval to
|
||
@var{STR}. This will subtotal all matching entries within each
|
||
interval separately, making it easy to see weekly, monthly, quarterly,
|
||
etc., transaction totals. An interval string can even specify the
|
||
beginning and end of the report range, using simple terms like ``last
|
||
june'' or ``next month''. For more using interval expressions, see
|
||
@ref{Interval expressions}.
|
||
|
||
@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{--weekly} (@option{-W}) reports transaction totals by the week.
|
||
The week begins on whichever day a transaction is first found, so to
|
||
start each week on a Sunday, specifying a beginning date for the
|
||
report that falls on a Sunday. @option{--monthly} (@option{-M}) reports
|
||
transaction totals by month; @option{--yearly} (@option{-Y}) reports
|
||
transaction totals by year. For more complex interval, using the
|
||
@option{--interval} option described above.
|
||
|
||
@sp 1
|
||
|
||
@option{--limit EXPR} (@option{-l EXPR}) limits which transactions take
|
||
part in the calculations of a report.
|
||
|
||
@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}).
|
||
|
||
@sp 1
|
||
|
||
@option{--value EXPR} (@option{-t EXPR}) changes the value expression used
|
||
to calculate the ``value'' column in the @command{register} report,
|
||
and the totals in the @command{equity} report. @xref{Value
|
||
expressions}.
|
||
|
||
@option{--total EXPR} (@option{-T EXPR}) sets the value expression used by
|
||
the ``total'' column in the @command{register} report, and also the
|
||
@command{balance} report.
|
||
|
||
@sp 1
|
||
|
||
@option{--value-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.
|
||
|
||
@subsection Commodity reporting
|
||
|
||
@option{--price-db FILE} (@option{-P 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
|
||
|
||
@sp 1
|
||
|
||
@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 @var{LEDGER_PRICE_DB}.
|
||
|
||
@sp 1
|
||
|
||
@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.
|
||
|
||
@sp 1
|
||
|
||
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 --quantity
|
||
(@option{-O}) reports commodity totals (this is the default)
|
||
|
||
@item --basis
|
||
(@option{-B}) reports the cost basis for all transactions.
|
||
|
||
@item --market
|
||
(@option{-V}) reports the last known market value for all commodities.
|
||
|
||
@item --gain
|
||
(@option{-G}) reports the net gain/loss for all commodity with a price
|
||
history.
|
||
|
||
@item --average
|
||
(@option{-A}) reports the average transaction value.
|
||
|
||
@item --deviation
|
||
(@option{-D}) reports each transaction's deviation from the average.
|
||
This is only meaningful in the @command{register} report.
|
||
|
||
@item --trend
|
||
(@option{-X}) reports the basic trend of all transaction values. This
|
||
can indicate whether spending is on the increase, or decrease, based
|
||
on the way the trend values change in the totals column of the
|
||
@command{register} report.
|
||
|
||
@item --weighted-trend
|
||
(@option{-Z}) reports the trend, like @option{--trend}, but factors in the
|
||
passage of time. Older transactions do not swing the trend numbers as
|
||
much as recent and future transactions. Thus, recent heavy spending
|
||
will indicate a higher trend, than if time were not considered.
|
||
@end table
|
||
|
||
@subsection Environment variables
|
||
|
||
Every option to ledger may be set using an environment variable. If
|
||
the option has a long option named @option{--this-option}, then setting
|
||
the environment variable @var{LEDGER_THIS_OPTION} will have the same
|
||
affect. Options on the command-line always take precedence over
|
||
environment variable settings.
|
||
|
||
@node Format strings, Value expressions, Options, Running Ledger
|
||
@section Format strings
|
||
|
||
Format strings can 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 subtitution 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 subtituted will be left justified. The default is right
|
||
justified. If a mininum 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 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 X
|
||
If a transaction has been cleared, this inserts @samp{*} followed by a
|
||
space; otherwise nothing is inserted.
|
||
|
||
@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 n
|
||
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, oherwise it just prints the account's name.
|
||
|
||
@item N
|
||
Inserts the full name of an account.
|
||
|
||
@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 tranaction amount and its cost. It's use is
|
||
not recommend unless you are modifying the print report.
|
||
|
||
@item /
|
||
The @samp{%/} construct is special. It separates a format string
|
||
between what should be printed for the first transaction in an entry,
|
||
and what should be printed for all subsequent transactions. If not
|
||
used, the same format string is applied to all transactions.
|
||
@end table
|
||
|
||
Here are default format strings for the balance and print reports,
|
||
just to give an example:
|
||
|
||
@example
|
||
%20T %2_%-n\n
|
||
\n%D %X%C%P\n %-34N %12o\n%/ %-34N %12o\n
|
||
@end example
|
||
|
||
@node Value expressions, Interval expressions, Format strings, Running Ledger
|
||
@section Value expressions
|
||
|
||
A value expression is a language used by ledger wherever a value is
|
||
involved. Some examples are:
|
||
|
||
@enumerate
|
||
@item Values displayed in reports
|
||
@item Predicates, or which transactions get calculated/displayed
|
||
@item Sorting criteria, or how transactions are sorted
|
||
@item 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.
|
||
|
||
@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 c
|
||
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-c}.
|
||
|
||
@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.
|
||
@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 C
|
||
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-C}.
|
||
@end table
|
||
|
||
@subsection Functions
|
||
|
||
The available one letter functions are:
|
||
|
||
@table @code
|
||
@item -
|
||
Negates the argument.
|
||
|
||
@item A
|
||
The absolute value of the argument.
|
||
|
||
@item S
|
||
Strips the commodity from the argument.
|
||
|
||
@item M
|
||
The median of the argument; @samp{Mx} is the same as @samp{x/n}.
|
||
|
||
@item D
|
||
The deviation of the argument; @samp{Dx} is the same as @samp{x-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}.
|
||
@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/
|
||
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/
|
||
A regular expression that matches against an entry's payee name.
|
||
|
||
@item ///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 (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 Interval expressions, Plotting register data, Value expressions, Running Ledger
|
||
@section Interval expressions
|
||
|
||
@node Plotting register data, Typical queries, Interval expressions, Running Ledger
|
||
@section Plotting register data
|
||
|
||
@node Typical queries, File format, Plotting register data, Running Ledger
|
||
@section Typical queries
|
||
|
||
Once you have an orderly and well-organized general ledger, the next
|
||
step is to generate orderly and well-organized reports. This is where
|
||
the Ledger command-line tool comes in. With it, you can balance your
|
||
checkbook, see where your money is going, tell whether you've made a
|
||
profit this year, and compute the present value of your retirement
|
||
accounts. And all with the simplest of interfaces, the command-line.
|
||
|
||
The most often used command will be 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.
|
||
|
||
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 -d sep balance expenses:food
|
||
@end example
|
||
|
||
Or maybe I want to see all of my assets, in which case the -s (show
|
||
sub-accounts) option comes in handy:
|
||
|
||
@example
|
||
ledger balance -s
|
||
@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
|
||
|
||
If you want to show all accounts but for one account, remember to use
|
||
``--'' to separate the exclusion pattern from the options list:
|
||
|
||
@example
|
||
ledger balance -- -equity
|
||
@end example
|
||
|
||
@node File format, , Typical queries, Running Ledger
|
||
@section File format
|
||
|
||
The ledger file format is quite simple, but supports many options.
|
||
These are summarized here.
|
||
|
||
The initial character of each line determines what that line means,
|
||
and how it should be parsed. The possibilities are:
|
||
|
||
@table @code
|
||
@item NUMBER
|
||
A line starting with a number denotes a regular ledger entry. It
|
||
may be followed by any number of lines that beginning whitespace, to
|
||
denote account transactions. The format of the header line is:
|
||
@example
|
||
DATE [*] [(CODE)] DESC
|
||
@end example
|
||
|
||
@item +
|
||
If a line begins with plus, it denotes an inclusion regexp that
|
||
will always be considered, as if it had been specified by the user
|
||
at the end of their command-line.
|
||
|
||
@item -
|
||
If a line begins with minus, it denotes an exclusion regexp that
|
||
will always be considered, as if it had been specified by the user
|
||
at the end of their command-line.
|
||
|
||
@item =
|
||
If a line begins with equals, it denotes an automated transaction.
|
||
The next item on the line must be a regular expression. Any number
|
||
of such lines may appear, with no intervening whitespace.
|
||
Following this block of lines can be a list of account transactions
|
||
preceded by whitespace.
|
||
|
||
@item !WORD
|
||
A line beginning with an exclamation mark denotes a command
|
||
directive. It must be immediately followed by a word specifying
|
||
which directories. At the moment, only @samp{!include} is supported, for
|
||
including the content of other ledger files into the current one.
|
||
|
||
@item whitespace
|
||
A line beginning with whitespace, which is not part of a regular or
|
||
automated transaction, is ignored.
|
||
|
||
@end table
|
||
|
||
@quotation
|
||
If a line begins with semicolon it is ignored. This is the
|
||
preferred method of entering comments.
|
||
@end quotation
|
||
|
||
@table @code
|
||
@item Y NUM
|
||
If a line begins with a capital Y, it denotes the year to be used
|
||
for all subsequent entries that specify a date, whatever their type.
|
||
This sets the ``default year'', which ordinarily is the current year
|
||
at the time the program is run. Useful at the beginning of a file
|
||
to specify the file's year.
|
||
|
||
@item P DATE SYMBOL PRICE
|
||
Capital P specifies a historical price for a commodity. Any such
|
||
number of entries are allowed. These are usually found in a pricing
|
||
history file (see the @option{-Q} option).
|
||
|
||
@item C SYMBOL PRICE
|
||
Capital C specifies a conversion price for a commodity. This has
|
||
no reference to time, and always takes precedence over any
|
||
historical price (even very current prices).
|
||
|
||
@item N SYMBOL
|
||
Capital N indicates that no implicit price conversions should be
|
||
obtained for the given symbol. This means that no quotes will ever
|
||
be downloaded for that symbol. Useful for a home currency, such as
|
||
the dollar ($). Be aware that these pricing options will set the
|
||
default reporting characteristics for a commodity. Thus it is
|
||
recommended that pricing options occur only after all regular ledger
|
||
entries have been parsed.
|
||
|
||
@item i DATE TIME ACCOUNT [DESC]
|
||
Lowercase (and capital) i indicate an time-in event. This will
|
||
start accumulating hours in the account specified. Usually these
|
||
entries are created in a timelog file by the timeclock program,
|
||
which is distributed with ledger. There must be two spaces between
|
||
the account name, and the optional description, if one is used.
|
||
|
||
@item o DATE TIME ACCOUNT [DESC]
|
||
Lowercase (and capital) o indicate an time-out event. This will
|
||
accumulate hours in the account specified. Usually these entries
|
||
are created in a timelog file by the timeclock program, which is
|
||
distributed with ledger. There must be two spaces between the
|
||
account name, and the optional description, if one is used.
|
||
|
||
@item b, h
|
||
Entries beginning with lowercase b and h are ignored. These are
|
||
special entries used by timeclock, but ignored by ledger.
|
||
|
||
@end table
|
||
|
||
@node Keeping a ledger, , 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:
|
||
|
||
@example
|
||
9/29 (100) Pacific Bell
|
||
Expenses:Utilities:Telephone $23.00
|
||
Assets:Checking $-23.00
|
||
@end example
|
||
|
||
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:
|
||
|
||
@example
|
||
9/29 (100) Pacific Bell
|
||
Expenses:Utilities:Telephone $23.00
|
||
Assets:Checking
|
||
@end example
|
||
|
||
For this entry, Ledger will figure out that $-23.00 must come from
|
||
``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::
|
||
* Archiving previous years::
|
||
* Virtual transactions::
|
||
* Automated transactions::
|
||
* Differences to Accounting Conventions::
|
||
* 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 their meaning is
|
||
often different from the layman's definitions. To avoid this semantic
|
||
overloading, we will refer to subtractions and additions. See
|
||
@uref{README.texi#DtAC, ``Differences to Accounting Conventions''} for how to
|
||
reconcile the two systems.
|
||
|
||
Recall that every transaction will involve two or more accounts.
|
||
Money is transferred from one group of accounts to another group. To
|
||
record the transaction, @emph{subtract} an amount from the source
|
||
accounts, and @emph{add} the same amount to the target accounts.
|
||
|
||
In order to write the Ledger entry correctly, you must determine where
|
||
the money comes from, and where it goes to. For example, when you are
|
||
paid, in order to add to your bank account, you must subtract from an
|
||
income account:
|
||
|
||
@example
|
||
9/29 My Employer
|
||
Assets:Checking $500.00
|
||
Income:Salary $-500.00
|
||
@end example
|
||
|
||
But wait, you say, why is the Income a negative figure? And when you
|
||
look at the balance totals for your ledger, you will certainly be
|
||
surprised to see Expenses as a positive figure, and Income as a
|
||
negative figure. Isn't that the opposite of how it should look?
|
||
|
||
It may take getting used to, but to properly use a general ledger you
|
||
will need to think in terms of money flows. 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:
|
||
|
||
@example
|
||
2004/09/29 My Employer
|
||
Assets:Checking $500.00
|
||
Income:Salary
|
||
@end example
|
||
|
||
Money, here, is coming from an Income account belonging to ``My
|
||
Employer'', and is being transferred to an account that belongs to you.
|
||
The money is now yours, which makes it an asset.
|
||
|
||
Liability accounts track money you owe to others. They come into play
|
||
whenever you borrow money to buy something, or if you owe someone
|
||
money. The usual way a liability is changed is by expending money,
|
||
thus transferring it to an Expenses account. For example:
|
||
|
||
@example
|
||
2004/09/30 Restaurant
|
||
Expenses:Dining $25.00
|
||
Liabilities:MasterCard
|
||
@end example
|
||
|
||
Your account balance will now show $25 spent on Dining, and a
|
||
corresponding $25 owed on your MasterCard. The MasterCard liability
|
||
will show up as negative, since it offsets the value of your assets.
|
||
@emph{The combined total of your Assets and Liabilities is your net
|
||
worth}. To see your current net worth, use this command:
|
||
|
||
@example
|
||
$ ledger balance ^assets ^liabilities
|
||
@end example
|
||
|
||
Relatedly, your Income accounts will show up negative, because they
|
||
transfer money @emph{from} an account in order to increase your
|
||
assets. Your Expenses accounts will show up positive, because that is
|
||
where the money went. The combined total your Income and Expenses is
|
||
your cash flow. A negative cash flow means that you are spending more
|
||
cash than you make. To see your current cash flow, use this command:
|
||
|
||
@example
|
||
$ ledger balance ^income ^expenses
|
||
@end example
|
||
|
||
Often, it is only important to view your income and expenses when
|
||
asking questions like, ``Where did my money go? Am I spending too
|
||
much on X? Am I making enough to cover my expenses?'' But most of
|
||
the time, you will usually want to ask other questions like, ``Is
|
||
there enough money in my checking account to cover my next credit card
|
||
bill?'' For these reasons, I recommend creating a script that removes
|
||
Income, Expenses, and Equity by default from your basic balance
|
||
report. The provided script ``bal'' does this for you, as well as
|
||
making it easier to run the balance command:
|
||
|
||
@example
|
||
$ bal
|
||
@end example
|
||
|
||
To use this script, it must be copied from the @strong{scripts}
|
||
directory in the ledger distribution, to a directory along your
|
||
@var{PATH}. Also, you must set the environment variable @var{LEDGER}
|
||
to point to your main ledger file.
|
||
|
||
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
|
||
monthly automobile expenses:
|
||
|
||
@example
|
||
$ ledger -M register expenses:auto
|
||
@end example
|
||
|
||
This assumes, of course, that you use accounts like Expenses:Auto:Gas
|
||
and Expenses:Auto:Repair.
|
||
|
||
@menu
|
||
* Tracking reimbursable expenses::
|
||
@end menu
|
||
|
||
@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities
|
||
@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:
|
||
|
||
@example
|
||
2004/09/29 Circuit City
|
||
Assets:Reimbursements:Company XYZ $100.00
|
||
Liabilities:MasterCard
|
||
@end example
|
||
|
||
This shows that you spent $100.00 on your MasterCard at Circuit City,
|
||
but that the expense was made on behalf of Company XYZ. Later, when
|
||
Company XYZ pays you back, you will transfer the money from your
|
||
reimbursement account to a regular asset account:
|
||
|
||
@example
|
||
2004/09/29 Company XYZ
|
||
Assets:Checking $100.00
|
||
Assets:Reimbursements:Company XYZ
|
||
@end example
|
||
|
||
This deposits the money owed from Company XYZ into your checking
|
||
account, presumably because they paid you 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:
|
||
|
||
@example
|
||
2004/09/29 Circuit City
|
||
Assets:Reimbursements:Company XYZ $100.00
|
||
Liabilities:MasterCard
|
||
@end example
|
||
|
||
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:
|
||
|
||
@example
|
||
2004/09/29 Circuit City
|
||
Company XYZ:Expenses:Computer:Software $100.00
|
||
Company XYZ:Accounts Payable:Your Name
|
||
@end example
|
||
|
||
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:
|
||
|
||
@example
|
||
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 example
|
||
|
||
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:
|
||
|
||
@example
|
||
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 example
|
||
|
||
And now the reimbursements account is paid off, accounts payable is
|
||
paid off, and the $100.00 has been effectively transferred from the
|
||
company's checking account to your personal checking account. The
|
||
money simply ``waited''---in both Assets:Reimbursements:Company XYZ,
|
||
and Company XYZ:Accounts Payable:Your Name---until such time as it
|
||
could be paid off.
|
||
|
||
The value of tracking expenses from both sides like that is that you
|
||
do not contaminate your personal expense report with expenses made on
|
||
behalf of others, while at the same time making it possible to
|
||
generate accurate reports of your company's expenditures. It is more
|
||
verbose than just paying for things with your personal assets, but it
|
||
gives you a very accurate information trail.
|
||
|
||
The advantage to keep these doubled 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:
|
||
|
||
@example
|
||
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 example
|
||
|
||
And two in your company ledger file:
|
||
|
||
@example
|
||
@@ 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 example
|
||
|
||
(Note: The @ above command means that all accounts mentioned in the
|
||
file are children of the specified account. In this case it means
|
||
that all activity in 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
|
||
50e ; currency: 50 Euros (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:
|
||
|
||
@example
|
||
$200.00
|
||
100.00 AU
|
||
AAPL 40
|
||
BORL 100
|
||
FEQTX 50 Assets:Brokerage
|
||
@end example
|
||
|
||
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 in any commodity, in which case the balance will be computed in
|
||
terms of that commodity. The usual way to specify prices is with a
|
||
file of price settings, which might look like this:
|
||
|
||
@example
|
||
AU=$357.00
|
||
AAPL=$37
|
||
BORL=$19
|
||
FEQTX=$32
|
||
@end example
|
||
|
||
Specify the prices file using the @option{-p} option:
|
||
|
||
@example
|
||
ledger -p prices.db balance brokerage
|
||
@end example
|
||
|
||
Now the balance for your brokerage account will be given in US
|
||
dollars, since the prices database has specified conversion factors
|
||
from each commodity into dollars:
|
||
|
||
@example
|
||
$40880.00 Assets:Brokerage
|
||
@end example
|
||
|
||
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. If gold is
|
||
currently $357 per ounce, then each dollar is worth 1/357 AU:
|
||
|
||
@example
|
||
ledger -p "$=0.00280112 AU" balance checking
|
||
@end example
|
||
|
||
@example
|
||
14.01 AU Assets:Checking
|
||
@end example
|
||
|
||
$5000 would buy 14 ounces of gold, which becomes the new display
|
||
commodity since a conversion factor was provided.
|
||
|
||
Commodities conversions can also be chained, up to a depth of 10.
|
||
Here is a sample prices database that uses chaining:
|
||
|
||
@example
|
||
AAPL=$15
|
||
$=0.00280112 AU
|
||
AU=300 Euro
|
||
Euro=MD 0.75
|
||
@end example
|
||
|
||
This is a roundabout way of reporting AAPL shares in their Deutsch
|
||
Mark equivalent.
|
||
|
||
@menu
|
||
* Commodity price histories::
|
||
@end menu
|
||
|
||
@node Commodity price histories, , Commodities and Currencies, Commodities and Currencies
|
||
@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:
|
||
|
||
@example
|
||
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 example
|
||
|
||
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, several options are possible:
|
||
|
||
@table @code
|
||
@item @strong{-P FILE}
|
||
With this option, or if the environment variable @var{PRICE_HIST} is
|
||
set, pricing information obtained from the Internet will be kept in
|
||
this file. Also, this file will be read after all other ledger files
|
||
are read, so that full history information is available for reports.
|
||
|
||
@item @strong{-O}
|
||
Report commodity totals only, not their market value or basis cost.
|
||
|
||
@item @strong{-V}
|
||
Report commodity values in terms of their last known market price.
|
||
|
||
@item @strong{-B}
|
||
Report commodities in terms of their ``basis cost'', or what they cost
|
||
at time of purchase. Thus, totals in the register and balance
|
||
report reflect the total amount spent.
|
||
|
||
@item @strong{-G}
|
||
Report commodities in terms of their net gain, which is: the market
|
||
value minus the cost basis. A balance report using this option
|
||
shows very quickly the performance of investments.
|
||
|
||
@item @strong{-Q}
|
||
When needed (see the @option{-L} option) pricing quotes are obtained by
|
||
calling the script @command{getquote} (a sample Perl script is
|
||
provided, but the interface is kept simple so replacements may be
|
||
made).
|
||
|
||
@item @strong{-L MINS}
|
||
When using the @option{-Q} flag, new quotes are obtained only if current
|
||
pricing data is older than MINS minutes. The default is one day,
|
||
or 1440 minutes.
|
||
|
||
@item @strong{-p ARG}
|
||
If a string, such as ``COMM=$1.20'', the commodity COMM will be
|
||
reported only in terms of the conversion factor, which supersedes
|
||
all other pricing histories for that commodity. This can be used to
|
||
perform arbitrary value substitutions. For example, to report the
|
||
value of your dollars in terms of the ounces of gold they would buy,
|
||
use: -p ``$=0.00280112 AU'' (or whatever the current exchange rate
|
||
is).
|
||
|
||
@end table
|
||
|
||
Note that the @option{-B}, @option{-O}, @option{-V}, and @option{-G} are mutually exclusive.
|
||
|
||
@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:
|
||
|
||
@example
|
||
9/29 Get some stuff at the Inn
|
||
Places:Black's Tavern -3 Apples
|
||
Places:Black's Tavern -5 Steaks
|
||
EverQuest:Inventory
|
||
@end example
|
||
|
||
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 ``Places:Black's Tavern'' as the source account. You could use
|
||
``EverQuest:System'' to represent the fact that you acquired them
|
||
online. The only purpose for choosing one kind of source account over
|
||
another is for generate more informative reports later on. The more
|
||
you know, the better analysis you can perform.
|
||
|
||
If you later sell some of these items to another player, the entry
|
||
would look like:
|
||
|
||
@example
|
||
10/2 Strum Brightblade
|
||
EverQuest:Inventory -2 Steaks
|
||
EverQuest:Inventory 15 Gold
|
||
@end example
|
||
|
||
Now you've turned 2 steaks into 15 gold, courtesy of your customer,
|
||
Strum 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.
|
||
|
||
@example
|
||
10/2 Opening Balance
|
||
Assets:Checking $100.00
|
||
Equity:Opening Balances
|
||
@end example
|
||
|
||
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 value. 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 totals.
|
||
|
||
@node Dealing with Petty Cash, Archiving previous years, 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 ``Expenses:Cash'' category:
|
||
|
||
@example
|
||
2004/03/15 ATM
|
||
Expenses:Cash $100.00
|
||
Assets:Checking
|
||
@end example
|
||
|
||
If at some point you make a large cash expense that you want to track,
|
||
just ``move'' the amount of the expense from ``Expenses:Cash'' into the
|
||
target account:
|
||
|
||
@example
|
||
2004/03/20 Somebody
|
||
Expenses:Food $65.00
|
||
Expenses:Cash
|
||
@end example
|
||
|
||
This way, you can still track large cash expenses, while ignoring all
|
||
of the smaller ones.
|
||
|
||
@node Archiving previous years, Virtual transactions, Dealing with Petty Cash, 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: ``print'', and ``equity''.
|
||
|
||
Let's take an example file, with data ranging from year 2000 until
|
||
2004. We want to archive years 2000 and 2001 to their own file,
|
||
leaving just 2003 and 2004 in the current file. So, use ``print'' to
|
||
output all the earlier entries to a file called @file{ledger-old.dat}.
|
||
(Keeping in mind that the ending date is not inclusive, which is why
|
||
2002 is mentioned in the following command):
|
||
|
||
@example
|
||
$ ledger -f ledger.dat -b 2000/1/1 -e 2002/1/1 print \
|
||
> ledger-old.dat
|
||
@end example
|
||
|
||
To delete older data from the current ledger file, use ``print'' again,
|
||
this time specifying year 2002 as the starting date:
|
||
|
||
@example
|
||
$ ledger -f ledger.dat -b 2002/1/1 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:
|
||
|
||
@example
|
||
10/2 Paycheck
|
||
Assets:Checking $1000.00
|
||
Income:Salary $-1000.00
|
||
(Debt:Alimony) $200.00
|
||
@end example
|
||
|
||
In this example, after receiving a paycheck an alimony debt is
|
||
increased---even though no money has moved around yet.
|
||
|
||
@example
|
||
10/2 Paycheck
|
||
Assets:Checking $1000.00
|
||
Income:Salary $-1000.00
|
||
[Savings:Trip] $200.00
|
||
[Assets:Checking] $-200.00
|
||
@end example
|
||
|
||
In this example, $200 has been deducted from checking toward savings
|
||
for a trip. It will appear as though the money has been moved from
|
||
the account into ``Savings:Trip'', although no money has actually moved
|
||
anywhere.
|
||
|
||
When balances are displayed, virtual transactions will be factored in.
|
||
To view balances without any virtual balances factored in, using the
|
||
``-R'' flag, for ``Reality''.
|
||
|
||
Write about: Saving for a Special Occasion; Keeping a Budget; Tracking
|
||
Allocated Funds.
|
||
|
||
@node Automated transactions, Differences to Accounting Conventions, 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.
|
||
The exact details of this are a bit complex, so if you have further
|
||
interest, please consult the Web.
|
||
|
||
For any fellow Bah<61>'<27>s out there who want to track Huq<75>qu'll<6C>h, the
|
||
Ledger tool makes this extremely easy. Just set up the following
|
||
automated transaction at the top of your ledger file:
|
||
|
||
@example
|
||
; These entries will compute Huq<75>qu'll<6C>h based on the
|
||
; contents of the ledger.
|
||
|
||
= ^Income:
|
||
= ^Expenses:Rent$
|
||
= ^Expenses:Furnishings
|
||
= ^Expenses:Business
|
||
= ^Expenses:Taxes
|
||
= ^Expenses:Insurance
|
||
(Liabilities:Huq<75>qu'll<6C>h) 0.19
|
||
@end example
|
||
|
||
This automated transaction works by looking at each transaction
|
||
appearing afterward in the ledger file. If any match the account
|
||
regexps, occurring after the equal signs above, 19% of the value of
|
||
that transaction is applied to the ``Liabilities:Huq<75>qu'll<6C>h'' account.
|
||
So if $1000 is earned through Income:Salary, which is seen as a debit
|
||
from Income, a debit of $190 is applied to ``Liabilities:Huq<75>qu'll<6C>h'';
|
||
if $1000 is spent on Rent---seen as a credit to the Expense account---a credit of $190 is applied to Huq<75>qu'll<6C>h. The ultimate balance
|
||
of Huq<75>qu'll<6C>h reflects how much must be paid to that account in order
|
||
to balance it to zero.
|
||
|
||
When you're ready to pay, just write a check directly to the account
|
||
``Liabilities:Huq<75>qu'll<6C>h'':
|
||
|
||
@example
|
||
2003/01/01 (101) Baha'i Huq<75>qu'll<6C>h Trust
|
||
Liabilities:Huq<75>qu'll<6C>h $1,000.00
|
||
Assets:Checking
|
||
@end example
|
||
|
||
That's it. To see how much Huq<75>q is currently owed based on your
|
||
ledger entries, use:
|
||
|
||
@example
|
||
ledger balance Liabilities:Huq<75>q
|
||
@end example
|
||
|
||
|
||
@node Differences to Accounting Conventions, Using Emacs to Keep Your Ledger, Automated transactions, Keeping a ledger
|
||
@section Differences to Accounting Conventions
|
||
If you are an accountant, or you are familiar with accounting
|
||
terminology, then you might be tearing your hair out after reading the
|
||
above. Please don't!
|
||
|
||
Ledger is intended to make people comfortable with their finances; to
|
||
help them better control the flow of their money. Contemporary
|
||
accounting practices, on the other hand, often seem counter-intuitive
|
||
and confusing to the layman. To make Ledger more accessible, it
|
||
avoids the use of standard accounting conventions and terminology.
|
||
However, Ledger is flexible enough that you may interpret what is
|
||
happening however you wish.
|
||
|
||
Most probably, the following section will confuse you, and you should
|
||
skip it if you've managed to understand everything so far. However,
|
||
if you intend to communicate your accounting practices to a
|
||
professional accountant, the following explanations may be useful.
|
||
|
||
@table @strong
|
||
@item The entity
|
||
The individual or organisation under consideration: the someone or
|
||
something on whose behalf you are accounting. Probably you.
|
||
|
||
@item Assets
|
||
Future economic benefits controlled by the entity as a result of a
|
||
past transaction or event.
|
||
|
||
@item Liabilities
|
||
Future sacrifices of economic benefits that the entity is obliged to
|
||
make as a result of a past transaction or event.
|
||
|
||
@end table
|
||
|
||
The format of the data files used by Ledger is more akin to a general
|
||
journal than a ledger. In an accounting ledger, transactions are
|
||
grouped by account. In a general journal, transactions are commonly
|
||
listed in chronological order.
|
||
|
||
Often ``cash'' is used to refer to a liquid savings account at a bank,
|
||
rather than the physical notes and coins you may withdraw.
|
||
|
||
In general, an ``addition'' in Ledger is an accounting debit, and a
|
||
``subtraction'' in Ledger is an accounting credit. The following table
|
||
shows the ``normal'' balances for the different types of accounts.
|
||
Accountants avoid using negative balances where possible, instead
|
||
prefering a positive amount in ``credit'' balance.
|
||
|
||
@multitable @columnfractions 0.2 0.2 0.2 0.2 0.2
|
||
@item System @tab Asset @tab Liability @tab Income @tab Expense
|
||
@item @strong{Accounting} @tab debit @tab credit @tab credit @tab debit
|
||
@item @strong{Ledger} @tab positive @tab negative @tab negative @tab positive
|
||
@end multitable
|
||
|
||
That's correct: accountants call an addition to their cash a debit!
|
||
However, from the bank's perspective it is a credit: the accountant's
|
||
cash is a liability for the bank. Consequently, payments to the
|
||
account will show up as credits on his bank statement.
|
||
|
||
@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Differences to Accounting Conventions, 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
|
||
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 the following 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-r
|
||
Reconciles an account by displaying the transactions in another
|
||
buffer, where simply hitting the spacebar will toggle the cleared
|
||
flag of the transaction in the ledger. It also displays the current
|
||
cleared balance for the account in the modeline.
|
||
|
||
@end table
|
||
|
||
@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 65 kilobyte 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 (which is
|
||
written in Python) 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 @strong{.timelog} file now contains:
|
||
|
||
@example
|
||
i 2004/10/06 15:21:00 ClientOne category
|
||
o 2004/10/06 15:21:10 waited for ten seconds
|
||
@end example
|
||
|
||
Ledger can parse this directly, as if it had seen the following ledger
|
||
entry:
|
||
|
||
@example
|
||
2004/10/06 category
|
||
(ClientOne) 0.00277h
|
||
@end example
|
||
|
||
In other words, the timelog event pair is seen as adding 0.00277h (ten
|
||
seconds) worth of time to the ClientOne account. This would be
|
||
considered billable time, which later could be invoiced and credited
|
||
to accounts receivable:
|
||
|
||
@example
|
||
2004/11/01 (INV#1) ClientOne, Inc.
|
||
Receivable:ClientOne $0.10
|
||
ClientOne -0.00277h @@ $35.00
|
||
@end example
|
||
|
||
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:
|
||
|
||
@example
|
||
2004/12/01 ClientOne, Inc.
|
||
Assets:Checking $0.10
|
||
Receivable:ClientOne
|
||
@end example
|
||
|
||
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 ``Billable'':
|
||
|
||
@example
|
||
; -*-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".
|
||
|
||
!include /home/johnw/.timelog Billable
|
||
|
||
; 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 example
|
||
|
||
@c Page published by Emacs Muse ends here
|
||
@contents
|
||
@bye
|