3079 lines
116 KiB
Text
3079 lines
116 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
|
|
@setfilename ledger3.info
|
|
@settitle Ledger: Command-Line Accounting
|
|
|
|
@dircategory User Applications
|
|
@copying
|
|
Copyright (c) 2003-2010, John Wiegley. All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are
|
|
met:
|
|
|
|
- Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
|
|
- Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
|
|
- Neither the name of New Artisans LLC nor the names of its
|
|
contributors may be used to endorse or promote products derived from
|
|
this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@end copying
|
|
|
|
@documentencoding UTF-8
|
|
|
|
@iftex
|
|
@finalout
|
|
@end iftex
|
|
|
|
|
|
@titlepage
|
|
@title LEDGER: Command-Line Accounting
|
|
@subtitle For Version 3.0 of LEDGER
|
|
@subtitle Draft Manual 2011-10-03
|
|
@author John Wiegley
|
|
@end titlepage
|
|
|
|
@direntry
|
|
* Ledger3: (ledger). Command-Line Accounting
|
|
@end direntry
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top, Copying, (dir), (dir)
|
|
@top Overview
|
|
LEDGER is a command line accounting tool that provides double-entry
|
|
accounting based on a text journal. It provides no bells or whistles,
|
|
and returns the user to the days before user interfaces were even a
|
|
twinkling in their father's CRT.
|
|
@c @insertcopying
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Copying::
|
|
* Introduction to Ledger::
|
|
* Ledger Tutorial ::
|
|
* Principles of Accounting::
|
|
* Keeping a Journal::
|
|
* Command-line Syntax::
|
|
* Basic Reporting Commands::
|
|
* Budgeting and Forecasting::
|
|
* Value Expressions::
|
|
* Format Strings::
|
|
* Journal File Format::
|
|
* Extending with Python::
|
|
* Example Data File::
|
|
* Miscellaneous Notes::
|
|
@end menu
|
|
|
|
@node Copying, Introduction to Ledger, Top, Top
|
|
@chapter Copying
|
|
@insertcopying
|
|
|
|
@node Introduction to Ledger, Ledger Tutorial , Copying, Top
|
|
@chapter Introduction to Ledger
|
|
@menu
|
|
* Fat-free Accounting::
|
|
* Building the Program::
|
|
* Getting Help::
|
|
@end menu
|
|
|
|
@node Fat-free Accounting, Building the Program, Introduction to Ledger, Introduction to Ledger
|
|
@section Fat-free Accounting
|
|
LEDGER is an accounting tool with the moxie to exist. It provides no
|
|
bells or whistles, and returns the user to the days before user
|
|
interfaces were even a twinkling in their father's CRT.
|
|
|
|
What it does offer is a double-entry accounting journal with all the
|
|
flexibility and muscle of its modern day cousins, without any of the
|
|
fat. Think of it as the Bran Muffin of accounting tools.
|
|
|
|
To use it, you need to start keeping a journal. This is the basis of
|
|
all accounting, and if you haven't started yet, now is the time to
|
|
learn. The little booklet that comes with your checkbook is a journal,
|
|
so we'll describe double-entry accounting in terms of that. If you use
|
|
another GUI accounting program like GNUCash, the vast majority of its
|
|
functionality is geared towards helping you keep a journal.
|
|
|
|
A checkbook journal records debits (subtractions, or withdrawals) and
|
|
credits (additions, or deposits) with reference to a single account:
|
|
the checking account. Where the money comes from, and where it goes
|
|
to, are described in the payee field, where you write the person or
|
|
company's name. The ultimate aim of keeping a checkbook journal is to
|
|
know how much money is available to spend. That's really the aim of
|
|
all journals.
|
|
|
|
What computers add is the ability to walk through these postings,
|
|
and tell you things about your spending habits; to let you devise
|
|
budgets and get control over your spending; to squirrel away money
|
|
into virtual savings account without having to physically move money
|
|
around; etc. As you keep your journal, you are recording information
|
|
about your life and habits, and sometimes that information can start
|
|
telling you things you aren't aware of. Such is the aim of all good
|
|
accounting tools.
|
|
|
|
The next step up from a checkbook journal, is a journal that keeps track
|
|
of all your accounts, not just checking. In such a journal, you record
|
|
not only who gets paid---in the case of a debit---but where the money
|
|
came from. In a checkbook journal, its assumed that all the money
|
|
comes from your checking account. But in a general journal, you write
|
|
posting two-lines: the source account and target account.
|
|
@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 journal must always balance to zero,
|
|
with an equal number of debits and credits.
|
|
|
|
|
|
For example, let's say you have a checking account and a brokerage
|
|
account, and you can write checks from both of them. Rather than keep
|
|
two checkbooks, you decide to use one journal for both. In this general
|
|
journal you need to record a payment to Pacific Bell for your monthly
|
|
phone bill, and a transfer (via check) from your brokerage account to
|
|
your checking account. The Pacific Bell bill is $23.00, let's say, and
|
|
you want to pay it from your checking account. In the general journal
|
|
you need to say where the money came from, in addition to where it's
|
|
going to. These transactions might look like this:
|
|
|
|
@smallexample
|
|
9/29 Pacific Bell $23.00 $23.00
|
|
Checking $-23.00 0
|
|
9/30 Checking $100.00 $100.00
|
|
(123) Brokerage $-100.00 0
|
|
@end smallexample
|
|
|
|
The posting must balance to $0: $23 went to Pacific Bell, $23 came from
|
|
Checking. The next entry shows check number 123 written against your
|
|
brokerage account, transfering money to your checking account. There is
|
|
nothing left over to be accounted for, since the money has simply moved
|
|
from one account to another in both cases. This is the basis of
|
|
double-entry accounting: money never pops in or out of existence; it is
|
|
always a posting from one account to another.
|
|
|
|
Keeping a general journal is the same as keeping two separate journals:
|
|
One for Pacific Bell and one for Checking. In that case, each time a
|
|
payment is written into one, you write a corresponding withdrawal into
|
|
the other. This makes it easier to write in a ``running balance'',
|
|
since you don't have to look back at the last time the account was
|
|
referenced---but it also means having a lot of journal books, if you
|
|
deal with multiple accounts.
|
|
|
|
Here is a good place for an aside on the use of the word `account'.
|
|
Most private people consider an account to be something that holds money
|
|
at an institution for them. LEDGER uses a more general definition
|
|
of the word. An account is anywhere money can go. Other finance
|
|
programs use ``categories'', LEDGER uses accounts. So, for
|
|
example, if you buy some groceries at Trader Joe's then more groceries
|
|
at Whole Foods Markets you might assign the transactions like this
|
|
@smallexample
|
|
2011/03/15 Trader Joe's
|
|
Expenses:Groceries $100.00
|
|
Assets:Checking
|
|
2011/03/15 Whole Food Market
|
|
Expenses:Groceries $75.00
|
|
Assets:Checking
|
|
@end smallexample
|
|
In both cases the money goes to the ``Groceries'' account, even though
|
|
the payees were different. You can set up your accounts in any way you
|
|
choose.
|
|
|
|
Enter the beauty of computerized accounting. The purpose of the
|
|
LEDGER program is to make general journal accounting simple, by keeping
|
|
track of the balances for you. Your only job is to enter the
|
|
postings. If an individual posting does not balance, LEDGER displays an
|
|
error and indicates the incorrect posting.@footnote{In some
|
|
special cases, it automatically balances this transaction for you.}
|
|
|
|
In summary, there are two aspects of LEDGER use: updating the journal
|
|
data file, and using the LEDGER tool to view the summarized result of
|
|
your transactions.
|
|
|
|
And just for the sake of example---as a starting point for those who
|
|
want to dive in head-first---here are the journal transactions from above,
|
|
formatted as the LEDGER program wishes to see them:
|
|
|
|
@smallexample
|
|
2004/09/29 Pacific Bell
|
|
Expenses:Pacific Bell $23.00
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
The account balances and registers in this file, if saved as
|
|
@file{ledger.dat}, could be reported using:
|
|
|
|
@smallexample
|
|
$ ledger -f ledger.dat balance
|
|
$ ledger -f ledger.dat register checking
|
|
$ ledger -f ledger.dat register Bell
|
|
@end smallexample
|
|
|
|
An important difference between LEDGER and other finance packages is
|
|
that journal will never alter your input file. You can create and edit
|
|
that file in any way you prefer, but journal is only for analyzing the
|
|
data, not for altering it.
|
|
|
|
|
|
@node Building the Program, Getting Help, Fat-free Accounting, Introduction to Ledger
|
|
@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:
|
|
|
|
@smallexample
|
|
./configure && make install
|
|
@end smallexample
|
|
|
|
@node Getting Help, , Building the Program, Introduction to Ledger
|
|
@section Getting help
|
|
|
|
If you need help on how to use LEDGER, or run into problems, you can
|
|
join the LEDGER mailing list at the following Web address:
|
|
|
|
@smallexample
|
|
http://groups.google.com/group/ledger-cli
|
|
@end smallexample
|
|
|
|
You can also find help at the @samp{#ledger} channel on the IRC server
|
|
@samp{irc.freenode.net}.
|
|
|
|
@node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top
|
|
@chapter Ledger Tutorial
|
|
|
|
@menu
|
|
* Start a Journal::
|
|
* Run Some Reports::
|
|
* Command Line Quick Reference::
|
|
@end menu
|
|
|
|
@node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial
|
|
@section Start a Journal File
|
|
|
|
A journal is a record of your financial transactions and will be central
|
|
to using LEDGER. For now we just want to get a taste of what LEDGER can
|
|
do. An example journal is included with the source code distribution,
|
|
called @file{drewr3.dat} (@pxref{Example Data File}).
|
|
Copy it someplace convenient and open up a terminal window in that
|
|
directory.
|
|
|
|
If you would rather start with your own journal right away please skip
|
|
to @xref{Keeping a Journal}.
|
|
|
|
@node Run Some Reports, Command Line Quick Reference, Start a Journal, Ledger Tutorial
|
|
@section Run a Few Reports
|
|
|
|
@menu
|
|
* Balance Report::
|
|
* Register Report::
|
|
* Cleared Report::
|
|
@end menu
|
|
|
|
@node Balance Report, Register Report, Run Some Reports, Run Some Reports
|
|
@subsection Balance Report
|
|
|
|
To find the balances of all of your accounts, run this command:
|
|
|
|
@smallexample
|
|
ledger -f drewr3.dat balance
|
|
@end smallexample
|
|
|
|
LEDGER will generate:
|
|
|
|
@smallexample
|
|
$ -3,804.00 Assets
|
|
$ 1,396.00 Checking
|
|
$ 30.00 Business
|
|
$ -5,200.00 Savings
|
|
$ -1,000.00 Equity:Opening Balances
|
|
$ 6,654.00 Expenses
|
|
$ 5,500.00 Auto
|
|
$ 20.00 Books
|
|
$ 300.00 Escrow
|
|
$ 334.00 Food:Groceries
|
|
$ 500.00 Interest:Mortgage
|
|
$ -2,030.00 Income
|
|
$ -2,000.00 Salary
|
|
$ -30.00 Sales
|
|
$ -63.60 Liabilities
|
|
$ -20.00 MasterCard
|
|
$ 200.00 Mortgage:Principal
|
|
$ -243.60 Tithe
|
|
--------------------
|
|
$ -243.60
|
|
@end smallexample
|
|
|
|
@noindent Showing you the balance of all accounts. Options and search terms can pare this down to show only the accounts you want.
|
|
|
|
A more useful report is to show only your Assets and Liabilities:
|
|
|
|
@smallexample
|
|
$ ledger -f drewr3.dat balance Assets Liabilities
|
|
$ -3,804.00 Assets
|
|
$ 1,396.00 Checking
|
|
$ 30.00 Business
|
|
$ -5,200.00 Savings
|
|
$ -63.60 Liabilities
|
|
$ -20.00 MasterCard
|
|
$ 200.00 Mortgage:Principal
|
|
$ -243.60 Tithe
|
|
--------------------
|
|
$ -3,867.60
|
|
@end smallexample
|
|
|
|
|
|
@node Register Report, Cleared Report, Balance Report, Run Some Reports
|
|
@subsection Register Report
|
|
|
|
To show all transactions and a running total:
|
|
@smallexample
|
|
ledger -f drewr3.dat register
|
|
@end smallexample
|
|
|
|
LEDGER will generate:
|
|
|
|
@smallexample
|
|
10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00
|
|
Equity:Opening Balances $ -1,000.00 0
|
|
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
|
Expense:Food:Groceries $ 37.50 $ 75.00
|
|
Expense:Food:Groceries $ 37.50 $ 112.50
|
|
Expense:Food:Groceries $ 37.50 $ 150.00
|
|
Expense:Food:Groceries $ 37.50 $ 187.50
|
|
Expense:Food:Groceries $ 37.50 $ 225.00
|
|
Assets:Checking $ -225.00 0
|
|
10-Dec-28 Acme Mortgage Lia:Mortgage:Principal $ 200.00 $ 200.00
|
|
Expe:Interest:Mortgage $ 500.00 $ 700.00
|
|
Expenses:Escrow $ 300.00 $ 1,000.00
|
|
Assets:Checking $ -1,000.00 0
|
|
11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 65.00
|
|
Assets:Checking $ -65.00 0
|
|
11-Jan-05 Employer Assets:Checking $ 2,000.00 $ 2,000.00
|
|
Income:Salary $ -2,000.00 0
|
|
(Liabilities:Tithe) $ -240.00 $ -240.00
|
|
11-Jan-14 Bank Assets:Savings $ 300.00 $ 60.00
|
|
Assets:Checking $ -300.00 $ -240.00
|
|
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ -196.00
|
|
Assets:Checking $ -44.00 $ -240.00
|
|
11-Jan-25 Bank Assets:Checking $ 5,500.00 $ 5,260.00
|
|
Assets:Savings $ -5,500.00 $ -240.00
|
|
11-Jan-25 Tom's Used Cars Expenses:Auto $ 5,500.00 $ 5,260.00
|
|
Assets:Checking $ -5,500.00 $ -240.00
|
|
11-Jan-27 Book Store Expenses:Books $ 20.00 $ -220.00
|
|
Liabilities:MasterCard $ -20.00 $ -240.00
|
|
11-Dec-01 Sale Asse:Checking:Business $ 30.00 $ -210.00
|
|
Income:Sales $ -30.00 $ -240.00
|
|
(Liabilities:Tithe) $ -3.60 $ -243.60
|
|
@end smallexample
|
|
|
|
@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for:
|
|
|
|
@smallexample
|
|
$ ledger -f drewr3.dat register Groceries
|
|
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
|
Expense:Food:Groceries $ 37.50 $ 75.00
|
|
Expense:Food:Groceries $ 37.50 $ 112.50
|
|
Expense:Food:Groceries $ 37.50 $ 150.00
|
|
Expense:Food:Groceries $ 37.50 $ 187.50
|
|
Expense:Food:Groceries $ 37.50 $ 225.00
|
|
11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 290.00
|
|
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00
|
|
@end smallexample
|
|
|
|
@noindent Which matches the balance reported for the @samp{Groceries} account:
|
|
|
|
@smallexample
|
|
$ ledger -f drewr3.dat balance Groceries
|
|
$ 334.00 Expenses:Food:Groceries
|
|
@end smallexample
|
|
|
|
@noindent If you would like to find transaction to only a certain payee use @samp{payee} or @@:
|
|
@smallexample
|
|
$ ledger -f drewr3.dat register payee "Organic"
|
|
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
|
Expense:Food:Groceries $ 37.50 $ 75.00
|
|
Expense:Food:Groceries $ 37.50 $ 112.50
|
|
Expense:Food:Groceries $ 37.50 $ 150.00
|
|
Expense:Food:Groceries $ 37.50 $ 187.50
|
|
Expense:Food:Groceries $ 37.50 $ 225.00
|
|
Assets:Checking $ -225.00 0
|
|
@end smallexample
|
|
|
|
@node Cleared Report, , Register Report, Run Some Reports
|
|
@subsection Cleared Report
|
|
|
|
A very useful report is to show what your obligations are versus what
|
|
expenditures have actually been recorded. It can take several days for
|
|
a check to clear, but you should treat it as money spent. The
|
|
@samp{cleared} report shows just that:
|
|
|
|
@smallexample
|
|
$ ledger -f drewr3.dat cleared
|
|
$ -3,804.00 $ 775.00 Assets
|
|
$ 1,396.00 $ 775.00 10-Dec-20 Checking
|
|
$ 30.00 0 Business
|
|
$ -5,200.00 0 Savings
|
|
$ -1,000.00 $ -1,000.00 10-Dec-01 Equity:Opening Balances
|
|
$ 6,654.00 $ 225.00 Expenses
|
|
$ 5,500.00 0 Auto
|
|
$ 20.00 0 Books
|
|
$ 300.00 0 Escrow
|
|
$ 334.00 $ 225.00 10-Dec-20 Food:Groceries
|
|
$ 500.00 0 Interest:Mortgage
|
|
$ -2,030.00 0 Income
|
|
$ -2,000.00 0 Salary
|
|
$ -30.00 0 Sales
|
|
$ -63.60 0 Liabilities
|
|
$ -20.00 0 MasterCard
|
|
$ 200.00 0 Mortgage:Principal
|
|
$ -243.60 0 Tithe
|
|
---------------- ---------------- ---------
|
|
$ -243.60 0
|
|
@end smallexample
|
|
|
|
@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance.
|
|
|
|
@node Command Line Quick Reference, , Run Some Reports, Ledger Tutorial
|
|
@section Command Line Quick Reference
|
|
|
|
@menu
|
|
* Reporting Commands Quick Reference::
|
|
* Basic Options Quick Reference::
|
|
* Report Filtering Quick Reference::
|
|
* Output Customization Quick Reference::
|
|
* Commodity Reporting Quick Reference::
|
|
@end menu
|
|
|
|
@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference
|
|
@subsection Reporting Commands
|
|
@multitable @columnfractions .2 .8
|
|
@item @strong{Report} @tab @strong{Description}
|
|
@item @code{balance} @tab Show account balances
|
|
@item @code{register} @tab Show all transactions with running total
|
|
@item @code{print} @tab Print transaction in a ledger readable format
|
|
@item @code{output} @tab Similar to print without included transactions
|
|
@item @code{xml} @tab Produce XML output of the register command
|
|
@item @code{emacs} @tab Produce emacs lisp output
|
|
@item @code{equity} @tab Print account balances as transactions
|
|
@item @code{prices} @tab Print price history for matching commodities
|
|
@item @code{pricesdb} @tab Print price history for matching commodities in ledger readable format
|
|
@item @code{xact} @tab Used to generate transactions based on previous postings
|
|
@end multitable
|
|
|
|
@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference
|
|
@subsection Basic Options
|
|
@multitable @columnfractions .1 .25 .65
|
|
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
|
@item @code{-h} @tab @code{--help} @tab prints summary of all options
|
|
@item @code{-v} @tab @code{--version} @tab prints version of ledger executable
|
|
@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file
|
|
@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE}
|
|
@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file
|
|
@item @tab @code{--cache FILE} @tab specify binary cache file
|
|
@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings
|
|
@end multitable
|
|
|
|
@node Report Filtering Quick Reference, Output Customization Quick Reference, Basic Options Quick Reference, Command Line Quick Reference
|
|
@subsection Report Filtering
|
|
@multitable @columnfractions .1 .25 .65
|
|
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
|
@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date
|
|
@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE}
|
|
@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date od transactions for report
|
|
@item @code{-p STR} @tab @code{--period} @tab Set report period to STR
|
|
@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period
|
|
@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings
|
|
@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings
|
|
@item @code{-R} @tab @code{--real} @tab Display only real postings
|
|
@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated
|
|
@item @code{-r} @tab @code{--related} @tab Display related postings
|
|
@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget
|
|
@item @code{} @tab @code{--add-budget} @tab Shows unbudgeted postings
|
|
@item @code{} @tab @code{--unbedgeted} @tab Shows only unbudgeted postings
|
|
@item @code{} @tab @code{--forecast} @tab Project balances into the future
|
|
@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations
|
|
@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report
|
|
@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports
|
|
@end multitable
|
|
|
|
@node Output Customization Quick Reference, Commodity Reporting Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference
|
|
@subsection Output Customization
|
|
@multitable @columnfractions .15 .4 .45
|
|
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
|
@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings
|
|
@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal
|
|
@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee
|
|
@item @code{-x} @tab @code{--comm-as-payee} @tab Change the payee of every posting to be the commodity used in that posting
|
|
@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report
|
|
@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week
|
|
@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year
|
|
@item @code{} @tab @code{--dow} @tab report Posting totals by day of week
|
|
@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR}
|
|
@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80
|
|
@item @code{} @tab @code{--head N} @tab Report the first N postings
|
|
@item @code{} @tab @code{--tail N} @tab Report the last N postings
|
|
@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program
|
|
@item @code{-A} @tab @code{--average} @tab Reports average posting value
|
|
@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average
|
|
@item @code{-%} @tab @code{--percentage} @tab Show subtotals in the balance report as percentages
|
|
@item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report
|
|
@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column
|
|
@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals
|
|
@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings
|
|
@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports
|
|
@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format
|
|
@item @code{} @tab @code{--balance-format STR} @tab
|
|
@item @code{} @tab @code{--register-format STR} @tab
|
|
@item @code{} @tab @code{--print-format STR} @tab
|
|
@item @code{-j register} @tab @code{--plot-amount-format STR} @tab
|
|
@item @code{-J register} @tab @code{--plot-total-format STR} @tab
|
|
@item @code{} @tab @code{--equity-format STR} @tab
|
|
@item @code{} @tab @code{--prices-format STR} @tab
|
|
@item @code{-w register} @tab @code{--wide-register-format STR} @tab
|
|
@end multitable
|
|
|
|
@node Commodity Reporting Quick Reference, , Output Customization Quick Reference, Command Line Quick Reference
|
|
@subsection Commodity Reporting
|
|
|
|
@multitable @columnfractions .1 .25 .65
|
|
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
|
@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving downloaded commodity prices
|
|
@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes
|
|
@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote}
|
|
@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion
|
|
@item @code{-B} @tab @code{--basis} @tab Report cost basis
|
|
@item @code{-V} @tab @code{--market} @tab Report last known market value
|
|
@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history
|
|
@end multitable
|
|
|
|
@node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top
|
|
@chapter Principles of Accounting
|
|
|
|
@node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top
|
|
@chapter Keeping a Journal
|
|
|
|
The most important part of accounting is keeping a good journal. If you
|
|
have a good journal, tools can be written to work whatever mathematical
|
|
tricks you need to better understand your spending patterns. Without a
|
|
good journal, no tool, however smart, can help you.
|
|
|
|
The LEDGER program aims at making journal transactions as simple as
|
|
possible. Since it is a command-line tool, it does not provide a user
|
|
interface for keeping a journal. If you like, you may use GnuCash to
|
|
maintain your journal, in which case LEDGER will read
|
|
GnuCash's data files directly. In that case, read the GnuCash manual
|
|
now, and skip to the next chapter.
|
|
|
|
If you are not using GnuCash, but a text editor to maintain your
|
|
journal, read on. LEDGER has been designed to make data transactions as
|
|
simple as possible, by keeping the journal format easy, and also by
|
|
automagically determining as much information as possible based on the
|
|
nature of your transactions.
|
|
|
|
For example, you do not need to tell LEDGER about the accounts you
|
|
use. Any time LEDGER sees a posting involving an account it knows
|
|
nothing about, it will create it@footnote{This also means if you
|
|
misspell an account it will end up getting counted separately from what
|
|
you intended. The provided Emacs major mode provides for automatically
|
|
filling in account names.}. If you use a commodity that is new to
|
|
LEDGER, it will create that commodity, and determine its display
|
|
characteristics (placement of the symbol before or after the amount,
|
|
display precision, etc) based on how you used the commodity in the
|
|
posting.
|
|
|
|
@menu
|
|
* Most Basic Entry::
|
|
* Currency and Commodities::
|
|
* Structuring Your Accounts::
|
|
* Advanced Transactions::
|
|
* File Format::
|
|
* Archiving Previous Years ::
|
|
@end menu
|
|
|
|
@node Most Basic Entry, Currency and Commodities, Keeping a Journal, Keeping a Journal
|
|
@section The Most Basic Entry
|
|
|
|
Here is the Pacific Bell example from above, given as a LEDGER
|
|
posting, with the additional of a check number:
|
|
|
|
@smallexample
|
|
9/29 (1023) 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 (1023) Pacific Bell
|
|
Expenses:Utilities:Phone $23.00
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
For this transaction, LEDGER will figure out that $-23.00 must come from
|
|
@samp{Assets:Checking} in order to balance the transaction.
|
|
|
|
Also note the structure of the account entries. There is an implied
|
|
hierarchy established by separating with colons (see @pxref{Structuring Your Accounts}).
|
|
|
|
|
|
|
|
@strong{The format is very flexible and it isn't necessary that you
|
|
indent and space out things exactly as shown. The only requirements are
|
|
that the start of the transaction (the date typically) is at the
|
|
beginning of the first line of the transaction, and the accounts are
|
|
indented by at least one space. If you omit the leading spaces in the
|
|
account lines LEDGER will not count the transaction and will not
|
|
give an error. There must be at least two spaces, or a tab, between the
|
|
amount and the account. If you do not have adequate separation between
|
|
the amount and the account LEDGER will give an error and stop
|
|
calculating}
|
|
|
|
@node Currency and Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
|
|
@section Currency and Commodities
|
|
|
|
LEDGER is agnostic when it comes to how you value your accounts.
|
|
Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''.
|
|
Holdings in stocks, bonds, mutual funds and other financial instruments
|
|
can be labelled using whatever is convenient for you (stock ticker
|
|
symbols are suggested for publicly traded assets).@footnote{you can
|
|
track ANYTHING, even time or distance travelled. As long as it cannot be
|
|
created or destroyed inside your accounting system.}
|
|
|
|
For the rest of this manual, we will only use the word ``commodities''
|
|
when refering to the units on a transaction value.
|
|
|
|
This is fundamentally different than many common accounting packages,
|
|
which assume the same currency throughout all of your accounts. This
|
|
means if you typically operate in Euros, but travel to the US and have
|
|
some expenses, you would have to do the currency conversion BEFORE you
|
|
made the entry into your financial system. With ledger this is not
|
|
required. In the same journal you can have entries in any or all
|
|
commodities you actually hold. You can use the reporting capabilities
|
|
to convert all commodities to a single commodity for reporting purposes
|
|
without ever changing the underlying entry.
|
|
|
|
For example, the following entries reflect transaction made for a
|
|
business trip to Europe from the US:
|
|
|
|
@smallexample
|
|
2011/09/23 Cash in Munich
|
|
Assets:Cash E50.00
|
|
Assets:Checking $-66.00
|
|
|
|
2011/09/24 Dinner in Munich
|
|
Expenses:Business:Travel E35.00
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
This says that $66.00 came out of checking and turned into 50 Euros. The
|
|
implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner
|
|
in Munich.
|
|
|
|
Running a ledger balance report shows:
|
|
@smallexample
|
|
$ ledger -f example.dat bal
|
|
$-66.00
|
|
E15.00 Assets
|
|
E15.00 Cash
|
|
$-66.00 Checking
|
|
E35.00 Expenses:Business:Travel
|
|
--------------------
|
|
$-66.00
|
|
E50.00
|
|
@end smallexample
|
|
|
|
The top two lines show my current assets as $-66.00 in checking (in this
|
|
very short example I didn't establish opening an opening balance for the
|
|
checking account) and E15.00. After spending on dinner i have E15.00 in
|
|
my wallet. The bottom line balances to zero, but is shown in two lines
|
|
since we haven't told ledger to convert commodities.
|
|
|
|
|
|
@node Structuring Your Accounts, Advanced Transactions, Currency and Commodities, Keeping a Journal
|
|
@section Structuring your Accounts
|
|
|
|
There really are no requirements for how you do this, but to preserve
|
|
your sanity we suggest some very basic structure to your accounting
|
|
system.
|
|
|
|
At the highest level you have five sorts of accounts:
|
|
@enumerate
|
|
@item
|
|
Expenses: where money goes
|
|
@item
|
|
Assets: where money sits
|
|
@item
|
|
Income: where moeny comes from
|
|
@item
|
|
Liabilities: money you owe
|
|
@item
|
|
Equity: the real value of your property.
|
|
@end enumerate
|
|
|
|
Starting the structure off this way will make it simpler for you to get
|
|
answers to the questions you really need to ask about your finances.
|
|
|
|
Beneath these top level accounts you can have any level of detail you
|
|
desire. For example, if you want to keep specific track of how much you spend on
|
|
burgers and fries, you could have the following:
|
|
@smallexample
|
|
Expenses:Food:Hamburgers and Fries
|
|
@end smallexample
|
|
|
|
|
|
|
|
|
|
@node Advanced Transactions, File Format, Structuring Your Accounts, Keeping a Journal
|
|
@section Advanced Transactions
|
|
@menu
|
|
* Transaction Notes and Tags::
|
|
* Multiple Account Transactions::
|
|
* Virtual Transactions::
|
|
* Automatic Transactions::
|
|
* Periodic Transactions::
|
|
* Recording Commodity Lot Prices::
|
|
* Commodity Pricing Problem::
|
|
@end menu
|
|
|
|
@node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions
|
|
@subsection Transaction Notes and Tags
|
|
|
|
LEDGER 3.0 supports entry and transaction ``notes'', which may
|
|
contain new metadata and tag markers. Here's an example:
|
|
|
|
@smallexample
|
|
2004/05/27 (100) Credit card company
|
|
; This is an entry note!
|
|
; Sample: Value
|
|
Liabilities:MasterCard $20.00
|
|
; This is a transaction note!
|
|
; Sample: Another Value
|
|
; :MyTag:
|
|
Assets:Bank:Checking
|
|
; :AnotherTag:
|
|
@end smallexample
|
|
|
|
An indented paragraph starting with `;' is parsed as a persistent note
|
|
for its preceding category. These notes will get printed back to you
|
|
with the ``print'' command. They are accessible to value expressions
|
|
using the ``note'' variable.
|
|
|
|
Further, any occurrence of ``:foo:'' in a note will cause a metadata tag
|
|
for "foo" to be registered for that entry. You can then search for
|
|
such transactions using:
|
|
|
|
@smallexample
|
|
ledger reg %foo
|
|
ledger reg tag foo
|
|
@end smallexample
|
|
|
|
Also, if any word in the note ends (but does not start) with a colon,
|
|
the remainder of that line will be taken to be the metadata value for
|
|
that tag. That is:
|
|
|
|
@smallexample
|
|
; :foo:bar:baz: <-- These are three tags
|
|
; name: value <-- this is a tag with a value
|
|
@end smallexample
|
|
|
|
Tags with value can be searched for just like tags. In addition, you
|
|
can further limit your tag search by looking for only those tags that
|
|
have specific values:
|
|
|
|
@smallexample
|
|
ledger reg %name=value
|
|
ledger reg tag name=value
|
|
@end smallexample
|
|
|
|
The group-by and sort functions also support tags:
|
|
@smallexample
|
|
ledger --group-by "tag('foo')" bal
|
|
@end smallexample
|
|
Will produce a balance summary of all transanction with tag `foo' group
|
|
by transactions wiht the same value for `foo'.
|
|
|
|
@smallexample
|
|
ledger reg --sort "tag('foo')" %foo
|
|
@end smallexample
|
|
Produces a register view with the transaction have tag `foo' sorted by
|
|
the tags value.
|
|
|
|
Comments that occur before an entry, or which starts at column zero, are
|
|
always ignored and are neither searched nor printed back.
|
|
|
|
If a posting comment is a date (with brackets), it modifies the date for that posting:
|
|
@smallexample
|
|
2010/02/01 Sample
|
|
Assets:Bank $400.00
|
|
Income:Check $-400.00 ; [2010/01/01]
|
|
@end smallexample
|
|
You can use metadata to override the payee field for individual postings within a transaction: (source)
|
|
|
|
@smallexample
|
|
2010/06/17 Sample
|
|
Assets:Bank $400.00
|
|
Income:Check1 $-100.00 ; Payee: Person One
|
|
Income:Check2 $-100.00 ; Payee: Person Two
|
|
Income:Check3 $-100.00 ; Payee: Person Three
|
|
Income:Check4 $-100.00 ; Payee: Person Four
|
|
@end smallexample
|
|
Metadata are normally strings, but you can create metadata of other types:
|
|
|
|
@smallexample
|
|
2010/06/17 Sample
|
|
Assets:Bank $400.00
|
|
Income:Check1 $-100.00
|
|
; Date:: [2010/09/01]
|
|
; Amount:: $100.00
|
|
@end smallexample
|
|
(Note that this Date tag is not the same as the posting date.)
|
|
|
|
There are now tag/pop directives, to apply metadata to a range of transactions (and their postings). For example, if you wanted a conceptual "page" of transactions relating to business trip to Chicago, you could do this:
|
|
|
|
@smallexample
|
|
tag Location: Chicago
|
|
tag Purpose: Business
|
|
|
|
... transactions go here
|
|
|
|
pop
|
|
pop
|
|
@end smallexample
|
|
It would be as if you'd applied "; Location: Chicago", etc., to every transaction.
|
|
|
|
@node Multiple Account Transactions, Virtual Transactions, Transaction Notes and Tags, Advanced Transactions
|
|
@subsection Multiple Account Transactions
|
|
|
|
Often times a transaction needs to be split across several accounts. This is trivially simple in a LEDGER journal:
|
|
|
|
@smallexample
|
|
2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck
|
|
Income:Taxable:Acme Bytepumps Inc. $-2500.00
|
|
Assets:Brokerage:Checking $175.00
|
|
Assets:Investments:401K Deferred $250.00
|
|
Expenses:Tax:Medicare $36.25
|
|
Expenses:Tax:Federal Tax $200.00
|
|
Expenses:Tax:State Tax $20.00
|
|
Expenses:Insurance:Life $18.75
|
|
Assets:Credit Union:Joint Checking
|
|
@end smallexample
|
|
|
|
This is an example of a paycheck entry. THe money comes OUT of your
|
|
income account, and is spent into several other accounts. The last line
|
|
doesn't require an amount, as ledger will automatically balance the
|
|
transaction (it will be $1800 into the Joint Checking account)
|
|
|
|
|
|
@node Virtual Transactions, Automatic Transactions, Multiple Account Transactions, Advanced Transactions
|
|
@subsection Virtual Transactions
|
|
|
|
|
|
A virtual posting is when you, in your mind, see money as moving
|
|
to a certain place, when in reality that money has not moved at all.
|
|
There are several scenarios in which this type of tracking comes in
|
|
handy, and each of them will be discussed in detail.
|
|
|
|
To enter a virtual posting, surround the account name in
|
|
parentheses. This form of usage does not need to balance. However,
|
|
if you want to ensure the virtual posting balances with other
|
|
virtual postings in the same transaction, use square brackets. For
|
|
example:
|
|
|
|
@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 postings will be factored in.
|
|
To view balances without any virtual balances factored in, using the
|
|
@option{-R} flag, for ``reality''.
|
|
|
|
|
|
@node Automatic Transactions, Periodic Transactions, Virtual Transactions, Advanced Transactions
|
|
@subsection Automatic Transactions
|
|
|
|
As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets.
|
|
It is similar to tithing for Jews and Christians, or to Zakát for
|
|
Muslims. The exact details of computing Huqúqu'lláh are somewhat
|
|
complex, but if you have further interest, please consult the Web.
|
|
|
|
Ledger makes this otherwise difficult law very easy. Just set up an
|
|
automated posting at the top of your ledger file:
|
|
|
|
@smallexample
|
|
; This automated transaction will compute Huqúqu'lláh based on this
|
|
; journal's postings. Any that match will affect the
|
|
; Liabilities:Huququ'llah account by 19% of the value of that posting.
|
|
|
|
= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
|
|
(Liabilities:Huququ'llah) 0.19
|
|
@end smallexample
|
|
|
|
This automated posting works by looking at each posting in the
|
|
ledger file. If any match the given value expression, 19% of the
|
|
posting's value is applied to the @samp{Liabilities:Huququ'llah}
|
|
account. So, if $1000 is earned from @samp{Income:Salary}, $190 is
|
|
added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent,
|
|
$190 is subtracted. The ultimate balance of Huqúqu'lláh reflects how
|
|
much is owed in order to fulfill one's obligation to Huqúqu'lláh.
|
|
When ready to pay, just write a check to cover the amount shown in
|
|
@samp{Liabilities:Huququ'llah}. That transaction would look like:
|
|
|
|
@smallexample
|
|
2003/01/01 (101) Baha'i Huqúqu'lláh Trust
|
|
Liabilities:Huququ'llah $1,000.00
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
That's it. To see how much Huqúq is currently owed based on your
|
|
ledger transactions, use:
|
|
|
|
@smallexample
|
|
ledger balance Liabilities:Huquq
|
|
@end smallexample
|
|
|
|
This works fine, but omits one aspect of the law: that Huquq is only
|
|
due once the liability exceeds the value of 19 mithqáls of gold (which
|
|
is roughly 2.22 ounces). So what we want is for the liability to
|
|
appear in the balance report only when it exceeds the present day
|
|
value of 2.22 ounces of gold. This can be accomplished using the
|
|
command:
|
|
|
|
@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úqu'lláh is reported only if its value exceeds that of 2.22 ounces
|
|
of gold. If you wish the liability to be reflected in the parent
|
|
subtotal either way, use this instead:
|
|
|
|
@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
|
|
posting matched your automated transaction'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 posting,
|
|
which may be excluded from reports by using @option{--real}.
|
|
|
|
Automated transactions can use the full range of value expressions in
|
|
their predicate. If you wanted to specify a transaction only occur to
|
|
certain accounts that meet cetain value criteria you could specify:
|
|
|
|
@smallexample
|
|
= /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000)
|
|
Expenses:Tax 0.27
|
|
@end smallexample
|
|
In this case, @samp{amount} is tied to the amount of the posting being
|
|
tested.
|
|
|
|
But, wait! There's more!
|
|
|
|
In the short example above we calculated the taxes due for income within
|
|
a certain bracket. But in reality this calculation is more difficult.
|
|
There are different rate for difference marginal incomes and those taxes
|
|
are not easily descirbe by a simple multiplicative coefficient.
|
|
Automated transaction can use value expressions in there posting to
|
|
determine the ammounts. So to expand the example above for a three tax
|
|
bracket system we could enter:
|
|
|
|
@smallexample
|
|
= /Employees:.*:Payroll$/ and expr (amount < $10000.00)
|
|
(Expenses:Tax) 0.1
|
|
= /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 )
|
|
(Expenses:Tax) ($1000.00 + .15 * (amount - $10000.00))
|
|
= /Employees:.*:Payroll$/ and expr (amount > $100000.00)
|
|
(Expenses:Tax) ($13500.00 + .20 * (amount-$100000.00))
|
|
@end smallexample
|
|
|
|
|
|
@node Periodic Transactions, Recording Commodity Lot Prices, Automatic Transactions, Advanced Transactions
|
|
@subsection Periodic Transactions
|
|
|
|
A periodic transaction starts with a ~ followed by a period expression.
|
|
Periodic transactions are used for budgeting and forecasting only, they
|
|
have no effect withouth the @samp{--budget} option specified.
|
|
|
|
See @ref{Budgeting and Forecasting} for examples and details.
|
|
|
|
@node Recording Commodity Lot Prices, Commodity Pricing Problem, Periodic Transactions, Advanced Transactions
|
|
@subsection Recording Commodity Lot Prices
|
|
|
|
If you are tracking investments it is often necessary to keep track of
|
|
specific purchases of a commodity bought at difference prices. These
|
|
specific purchases are referred to as ``lots''. Tracking lots using ledger
|
|
requires some additional info in the journal as well as additional
|
|
command-line options when generating reports.
|
|
|
|
Say you want to record purchase of two separate lots of ACME, then sell
|
|
some shares. The correct way to do this is:
|
|
|
|
@smallexample
|
|
2010-09-01 * Buy 2 shares of ACME @@ $100
|
|
Assets:Broker 2 ACME @@ $100.00
|
|
Assets:Cash
|
|
|
|
2010-09-10 * Buy 2 share of ACME @@ $110
|
|
Assets:Broker 2 ACME @@ $110.00
|
|
Assets:Cash
|
|
|
|
2011-09-20 * Sell 2 shares of ACME @@ $150
|
|
Assets:Broker -1 ACME @{$100.00@} @@ $150.00
|
|
Assets:Broker -1 ACME @{$200.00@} @@ $150.00
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
To report which lots of commodities you hold, use the
|
|
@samp{--lot-prices} option. For example, after buying the 2 shares at
|
|
$100 and 1 at $200 it would show you:
|
|
@smallexample
|
|
$ ledger balance --lot-prices Assets:Broker until 2011-09-15
|
|
2 ACME @{$100.00@}
|
|
1 ACME @{$200.00@} Assets:Broker
|
|
@end smallexample
|
|
@noindent without the @samp{--lot-prices} option you would only see the total number of shares you held:
|
|
@smallexample
|
|
$ ledger balance Assets:Broker until 2011-09-15
|
|
3 ACME Assets:Broker
|
|
@end smallexample
|
|
@noindent and after the sale on @samp{2011-09-20} it would show you:
|
|
@smallexample
|
|
$ ledger balance --lot-prices Assets:Broker
|
|
1 ACME @{$100.00@} Assets:Broker
|
|
@end smallexample
|
|
|
|
@node Commodity Pricing Problem, , Recording Commodity Lot Prices, Advanced Transactions
|
|
@subsection Commodity Valuation
|
|
|
|
[THIS SUBSECTION COULD BELONG IN REPORTING SECTION, OR MAYBE EVEN SPLIT BETWEEN THE TWO]
|
|
|
|
|
|
Often you will be more interested in the value of your entire holdings, in
|
|
your preferred currency. It might be nice to know you hold 10,000 shares
|
|
of PENNY, but you are more interested in whether or not that is worth
|
|
$1000.00 or $10,000.00. However, the current day value of a commodity can
|
|
mean different things to different people, depending on the accounts
|
|
involved, the commodities, the nature of the transactions, etc.
|
|
|
|
When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that
|
|
some or all of the commodities be valuated as of today (or whatever
|
|
@samp{--now} is set to). But what does such a valuation mean? This
|
|
meaning is governed by the presence of a @samp{VALUE} metadata
|
|
property, whose content is an expression used to compute that value.
|
|
|
|
If no VALUE property is specified, each posting is assumed to have a default,
|
|
as if you'd specified a global, automated transaction as follows:
|
|
|
|
@smallexample
|
|
= expr true
|
|
; VALUE:: market(amount, date, exchange)
|
|
@end smallexample
|
|
This definition emulates the present day behavior of -V and -X (in the case of
|
|
-X, the requested commodity is passed via the string 'exchange' above).
|
|
|
|
One thing many people have wanted to do is to fixate the valuation of old
|
|
European currencies in terms of the Euro after a certain date:
|
|
|
|
@smallexample
|
|
= expr commodity == "DM"
|
|
; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR
|
|
@end smallexample
|
|
|
|
This says: If --now is some old date, use market prices as they were at that
|
|
time; but if --now is past June 2008, use a fixed price for converting Deutsch
|
|
Mark to Euro.
|
|
|
|
Or how about never re-valuating commodities used in Expenses, since they
|
|
cannot have a different future value:
|
|
|
|
@smallexample
|
|
= /^Expenses:/
|
|
; VALUE:: market(amount, post.date, exchange)
|
|
@end smallexample
|
|
|
|
This says the future valuation is the same as the valuation at the time of
|
|
posting. post.date equals the posting's date, while just 'date' is the value
|
|
of --now (defaults to today).
|
|
|
|
Or how about valuating miles based on a reimbursement rate during a specific
|
|
time period:
|
|
|
|
|
|
@smallexample
|
|
= expr commodity == "miles" and date >= [2007] and date < [2008]
|
|
; VALUE:: market($1.05, date, exchange)
|
|
@end smallexample
|
|
|
|
In this case, miles driven in 2007 will always be valuated at $1.05 each. If
|
|
you use -X EUR to expressly request all amounts in Euro, Ledger shall convert
|
|
$1.05 to Euro by whatever means are appropriate for dollars.
|
|
|
|
Note that you can have a valuation expression specific to a particular posting
|
|
or transaction, by overriding these general defaults using specific metadata:
|
|
|
|
@smallexample
|
|
|
|
2010-12-26 Example
|
|
Expenses:Food $20
|
|
; Just to be silly, always valuate *these* $20 as 30 DM, no matter what
|
|
; the user asks for with -V or -X
|
|
; VALUE:: 30 DM
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
This example demonstrates that your VALUE expression should be as symbolic as
|
|
possible, using terms like 'amount' and 'date', rather than specific amounts
|
|
and dates. Also, you should pass the amount along to the function 'market' so
|
|
it can be further revalued if the user has asked for a specific currency.
|
|
|
|
Or, if it better suits your accounting, you can be less symbolic, which allows
|
|
you to report most everything in EUR if you use -X EUR, except for certain
|
|
accounts or postings which should always be valuated in another currency. For
|
|
example:
|
|
|
|
@smallexample
|
|
= /^Assets:Brokerage:CAD$/
|
|
; Always report the value of commodities in this account in
|
|
; terms of present day dollars, despite what was asked for
|
|
; on the command-line VALUE:: market(amount, date, '$')
|
|
@end smallexample
|
|
|
|
I think this scheme, of using predicated value expressions which can be
|
|
generalized in automated transactions, and made specific via transaction and
|
|
posting-based metadata, provides sufficient flexibility to express most of the
|
|
use cases which have occurred on this topic.
|
|
|
|
|
|
Ledger presently has no way of handling such things as FIFO and LIFO.
|
|
|
|
If you specify an unadorned commodity name, like AAPL, it will balance
|
|
against itself. If --lots are not being displayed, then it will appear
|
|
to balance against any lot of AAPL.
|
|
|
|
If you specify an adorned commodity, like AAPL @{$10.00@}, it will also
|
|
balance against itself, and against any AAPL if --lots is not specified.
|
|
But if you do specify --lot-prices, for example, then it will balance
|
|
against that specific price for AAPL.
|
|
|
|
I may, for the sake of reporting *only*, be able to implement some sort
|
|
of guessing strategy, based on the order in which transactions appear in
|
|
the data file... But I'll have to think about this a lot more, and it
|
|
would be a 3.1 thing.
|
|
|
|
@smallexample
|
|
> b) I don't see how this VALUE property can differentiate between -V
|
|
> and -B. Does this imply that you want to get rid of the -B option and
|
|
> simply let users define what VALUE they get with -V? If so, I think
|
|
> this would be a bad idea... I really like the ability to see different
|
|
> valuation methods using command line options (i.e. -B for cost basis
|
|
> and -V for market value). (Incidentally, while I initially liked your
|
|
> example of using the posting date for Expenses, I later realized that
|
|
> I sometimes use -V to see what my expenses (in a foreign currency)
|
|
> would have been if I bought everything at today's exchange rate.)
|
|
@end smallexample
|
|
-V and -B are entirely unrelated. Perhaps I could support a BASIS
|
|
property setting, for customizing -B in the same way VALUE
|
|
customizes -V...
|
|
|
|
@smallexample
|
|
> c) I never fully understood what -X does exactly but afaik -X is a
|
|
> special version of -V. However, I believe that -X should _only_ do
|
|
> conversion. This would allow -X to be combined with other options,
|
|
> such as -X and -V. Example: let's say I bought 10 shares for 10.00
|
|
> GBP and they are now worth 15.00. Because my main assets are in EUR,
|
|
> I want to see what those shares are worth in EUR. Since I'm
|
|
> conservative I want to see the cost basis, i.e. I want to use -B and
|
|
> -X EUR together. (This actually works today but I'm told this is an
|
|
> accident and won't work in all cases.)
|
|
@end smallexample
|
|
-V asks for the present day value of all commodities, and lets Ledger
|
|
pick the target commodity based on its own hueristics. -X is the same
|
|
as -V, except that it overrides those hueristics and forces the target
|
|
commodity. (Although, as you've seen, the VALUE property could now
|
|
countermand that).
|
|
|
|
There are reasons why -X can't be applied to any report. Mainly it has
|
|
to do with rounding. For example, let's say I have 10 postings that
|
|
each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all
|
|
10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each
|
|
1 DM and *then* total them, I get 0.00 EUR.
|
|
|
|
This becomes very important to Ledger because -X is applied to totals,
|
|
not just to individual amounts. I'm going to have to use some magic
|
|
internally to avoid this problem with the VALUE property (in most, but
|
|
not all, cases).
|
|
|
|
And so, -X gets applied after, when the posting-origin of the
|
|
commodities has been lost -- required information if a basis cost
|
|
calculation is to be deferred.
|
|
|
|
The alternative would involve ever-growing lists of individual amounts,
|
|
which would slow many parts of Ledger from O(N) to O(N^2). Plus, it
|
|
still wouldn't solve the rounding problem.
|
|
|
|
|
|
> Ledger presently has no way of handling such things as FIFO and LIFO.
|
|
|
|
Yeah, I know... but I think it's a feature that ledger should
|
|
eventually get (obviously not for 3.0).
|
|
|
|
@smallexample
|
|
> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also
|
|
> balance against itself, and against any AAPL if --lots is not specified.
|
|
> But if you do specify --lot-prices, for example, then it will balance
|
|
> against that specific price for AAPL.
|
|
>
|
|
> I may, for the sake of reporting *only*, be able to implement some sort
|
|
> of guessing strategy, based on the order in which transactions appear in
|
|
> the data file...
|
|
@end smallexample
|
|
Why for reporting only? It seems to me that ledger has all the
|
|
information to do FIFO and LIFO properly (i.e. to remove the right
|
|
commodities from the list). Let's take this example:
|
|
|
|
@smallexample
|
|
|
|
2011-01-01 * Buy AAA
|
|
Assets:Shares 5 AAA @ 10.00 EUR
|
|
Assets:Cash
|
|
|
|
2011-01-03 * Buy AAA
|
|
Assets:Shares 2 AAA @ 10.00 EUR
|
|
Assets:Cash
|
|
|
|
2011-01-11 * Buy AAA
|
|
Assets:Shares 5 AAA @ 12.00 EUR
|
|
Assets:Cash
|
|
|
|
2011-01-21 * Buy AAA
|
|
Assets:Shares 5 AAA @ 13.00 EUR
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
So we end up with (ledger --lots):
|
|
|
|
@smallexample
|
|
5 AAA @{10.00 EUR@} [2011/01/01]
|
|
2 AAA @{10.00 EUR@} [2011/01/03]
|
|
5 AAA @{12.00 EUR@} [2011/01/11]
|
|
5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares
|
|
@end smallexample
|
|
|
|
So if I sell 6 shares now, according to FIFO, I would do:
|
|
|
|
@smallexample
|
|
2011-02-01 * Sell AAA
|
|
Assets:Shares -5 AAA @{10.00 EUR@} [2011/01/01] @
|
|
13.50 EUR
|
|
Assets:Shares -1 AAA @{10.00 EUR@} [2011/01/03] @
|
|
13.50 EUR
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
ledger --lots:
|
|
|
|
@smallexample
|
|
1 AAA @{10.00 EUR@} [2011/01/03]
|
|
5 AAA @{12.00 EUR@} [2011/01/11]
|
|
5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares
|
|
@end smallexample
|
|
|
|
According to LIFO, I would do this instead:
|
|
|
|
@smallexample
|
|
2011-02-01 * Sell AAA
|
|
Assets:Shares -5 AAA @{13.00 EUR@} [2011/01/21] @
|
|
13.50 EUR
|
|
Assets:Shares -1 AAA @{12.00 EUR@} [2011/01/11] @
|
|
13.50 EUR
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
In other words, you can manually do FIFO and LIFO with ledger already.
|
|
However, it would be great if ledger would make this easier, e.g. that
|
|
you could specify:
|
|
|
|
@smallexample
|
|
2011-02-01 * Sell AAA
|
|
Assets:Shares -6 AAA @{FIFO@} @ 13.50 EUR
|
|
Assets:Cash
|
|
@end smallexample
|
|
|
|
and ledger would iterate through all AAA commodities and take out the
|
|
right ones (after all, it knows the date and price).
|
|
|
|
The only thing I don't think is possible with ledger at the moment is
|
|
average cost. I'm also not sure how --lot-dates should behave for
|
|
average cost.
|
|
|
|
@smallexample
|
|
> There are reasons why -X can't be applied to any report. Mainly it has
|
|
> to do with rounding. For example, let's say I have 10 postings that
|
|
> each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all
|
|
> 10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each
|
|
> 1 DM and *then* total them, I get 0.00 EUR.
|
|
@end smallexample
|
|
Thanks for the explanation... what I was thinking of is that ledger
|
|
would just produce a report according to -V or -B or whatever and
|
|
*then* convert it with -X. I use a shell script to do this for now:
|
|
|
|
@smallexample
|
|
GBP2EUR="117/100"
|
|
|
|
eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets"
|
|
"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2)
|
|
eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//')
|
|
gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//')
|
|
eur=$(echo "$eur" | sed 's/\..*//')
|
|
gbp=$(echo "$gbp" | sed 's/\..*//')
|
|
gbpineur=$(($gbp*$GBP2EUR))
|
|
echo " " $(($eur + $gbpineur)) " EUR Total"
|
|
@end smallexample
|
|
|
|
I'm kinda surprised that you no longer think it's a good idea to split
|
|
-X from -V. Last time I brought this up on IRC, you thought it was a
|
|
good idea:
|
|
|
|
@smallexample
|
|
10:44 < johnw> I think having -H, in addition to -X, may make what you want
|
|
to see both natural and simple
|
|
10:45 < johnw> you'd use -H for income/expense accounts, and -X for
|
|
assets/liabilities
|
|
10:45 < johnw> -H = historical values
|
|
10:45 < johnw> -X = current exchange values
|
|
10:45 < tbm> so what's the difference between -X and -V again?
|
|
10:45 < johnw> -V is an automated version of -X
|
|
10:45 < johnw> it tries to figure out what the reported commodity should be
|
|
10:45 < johnw> we may then need an automated version of -H, to complete the
|
|
reflection
|
|
10:46 < johnw> btw, this is just an inside-out version of my "final"
|
|
feature :)
|
|
10:46 < tbm> why not change the meaning of -X to _only do conversion_? And
|
|
then you could combine -X with -B, -V or -H
|
|
10:46 < johnw> instead of having it be syntactic, we're moving the semantic
|
|
difference to a difference in options
|
|
10:46 < johnw> oh HMM
|
|
10:46 < johnw> -X with -B, -V and -I
|
|
10:46 < johnw> (and -O, incidentally)
|
|
10:46 < johnw> O = amount, B = cost, V = market value, I = price
|
|
10:47 < johnw> that's really an excellent suggestion
|
|
10:48 < johnw> i'd still need a flag to mean "historical" vs "current"
|
|
10:48 < johnw> as well as "target commodity" (-X)
|
|
@end smallexample
|
|
|
|
@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal
|
|
@section File Format for Users
|
|
|
|
The ledger file format is quite simple, but also very flexible. It
|
|
supports many options, though typically the user can ignore most of
|
|
them. They are summarized below.
|
|
|
|
The initial character of each line determines what the line means, and
|
|
how it should be interpreted. Allowable initial characters are:
|
|
|
|
@table @code
|
|
@item NUMBER
|
|
A line beginning with a number denotes a transaction. It may be followed
|
|
by any number of lines, each beginning with whitespace, to denote the
|
|
transaction's account postings. The format of the first line is:
|
|
|
|
@smallexample
|
|
DATE[=EDATE] [*|!] [(CODE)] DESC
|
|
@end smallexample
|
|
|
|
If @samp{*} appears after the date (with optional effective date), it
|
|
indicates the transaction is ``cleared'', which can mean whatever the user
|
|
wants it to mean. If @samp{!} appears after the date, it indicates d
|
|
the transaction is ``pending''; i.e., tentatively cleared from the user's
|
|
point of view, but not yet actually cleared. If a @samp{CODE} appears
|
|
in parentheses, it may be used to indicate a check number, or the type
|
|
of the posting. Following these is the payee, or a description of
|
|
the posting.
|
|
|
|
The format of each following posting is:
|
|
|
|
@smallexample
|
|
ACCOUNT AMOUNT [; NOTE]
|
|
@end smallexample
|
|
|
|
The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
|
|
posting, or square brackets if it is a virtual posting that
|
|
must balance. The @samp{AMOUNT} can be followed by a per-unit
|
|
posting cost, by specifying @samp{@@ AMOUNT}, or a complete
|
|
posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may
|
|
specify an actual and/or effective date for the posting by using
|
|
the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
|
|
@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual Transactions})
|
|
|
|
@item =
|
|
An automated transaction. A value expression must appear after the equal
|
|
sign.
|
|
|
|
After this initial line there should be a set of one or more
|
|
postings, just as if it were normal transaction. If the amounts of the
|
|
postings have no commodity, they will be applied as modifiers to
|
|
whichever real posting is matched by the value expression(See @pxref{Automatic Transactions}).
|
|
|
|
@item ~
|
|
A period transaction. A period expression must appear after the tilde.
|
|
|
|
After this initial line there should be a set of one or more
|
|
postings, just as if it were normal transaction.
|
|
|
|
@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 journal file.
|
|
|
|
@item !account
|
|
The account name is given is taken to be the parent of all
|
|
postings 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. Comments will not be returned in a ``print'' response.
|
|
@item indented ;
|
|
If the semi colon is indented and occurs inside a transaction, it is
|
|
parsed as a persistent note for its preceding category. These notes or
|
|
tags can be used to augment to reporting and filtering capabilities of
|
|
LEDGER.
|
|
@item Y
|
|
If a line begins with a capital Y, it denotes the year used for all
|
|
subsequent transactions that give a date without a year. The year should
|
|
appear immediately after the Y, for example: @samp{Y2004}. This is
|
|
useful at the beginning of a file, to specify the year for that file.
|
|
If all transactions specify a year, however, this command has no effect.
|
|
|
|
@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:
|
|
@smallexample
|
|
P DATE SYMBOL PRICE
|
|
@end smallexample
|
|
|
|
@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:
|
|
@smallexample
|
|
N SYMBOL
|
|
@end smallexample
|
|
|
|
@item D AMOUNT
|
|
Specifies the default commodity to use, by specifying an amount in the
|
|
expected format. The @command{transaction} command will use this commodity
|
|
as the default when none other can be determined. This command may be
|
|
used multiple times, to set the default flags for different
|
|
commodities; whichever is seen last is used as the default commodity.
|
|
For example, to set US dollars as the default commodity, while also
|
|
setting the thousands flag and decimal flag for that commodity, use:
|
|
@smallexample
|
|
D $1,000.00
|
|
@end smallexample
|
|
|
|
@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:
|
|
@smallexample
|
|
C 1.00 Kb = 1024 bytes
|
|
@end smallexample
|
|
|
|
@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 Archiving Previous Years , , File Format, Keeping a Journal
|
|
@section Archiving Previous Years
|
|
|
|
|
|
After a while, your journal can get to be pretty large. While this will
|
|
not slow down LEDGER---it's designed to process journals very
|
|
quickly---things can start to feel ``messy''; and it's a universal
|
|
complaint that when finances feel messy, people avoid them.
|
|
|
|
Thus, archiving the data from previous years into their own files can
|
|
offer a sense of completion, and freedom from the past. But how to best
|
|
accomplish this with the ledger program? There are two commands that
|
|
make it very simple: @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 transactions 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:
|
|
|
|
@smallexample
|
|
ledger -f ledger.dat -b 2002 print > x
|
|
mv x ledger.dat
|
|
@end smallexample
|
|
|
|
However, now the current file contains @emph{only} postings from 2002
|
|
onward, which will not yield accurate present-day balances, because the
|
|
net income from previous years is no longer being tallied. To
|
|
compensate for this, we must append an equity report for the old ledger
|
|
at the beginning of the new one:
|
|
|
|
@smallexample
|
|
ledger -f ledger-old.dat equity > equity.dat
|
|
cat equity.dat ledger.dat > x
|
|
mv x ledger.dat
|
|
rm equity.dat
|
|
@end smallexample
|
|
|
|
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 Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top
|
|
@chapter Command-line Syntax
|
|
|
|
|
|
@menu
|
|
* Basic Usage::
|
|
* Detailed Options Description::
|
|
* Period Expressions::
|
|
@end menu
|
|
|
|
@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax
|
|
@section Basic Usage
|
|
|
|
This chapter describes LEDGER's features and options. You may wish to
|
|
survey this to get an overview before diving in to the @ref{Ledger
|
|
Tutorial} and more detailed examples that follow.
|
|
|
|
LEDGER has a very simple command-line interface, named---enticingly
|
|
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:
|
|
|
|
@smallexample
|
|
ledger [OPTIONS...] COMMAND [ARGS...]
|
|
@end smallexample
|
|
|
|
After the command word there may appear any number of arguments. For
|
|
most commands, these arguments are regular expressions that cause the
|
|
output to relate only to postings matching those regular expressions.
|
|
For the @command{transaction} command, the arguments have a special
|
|
meaning, described below.
|
|
|
|
The regular expressions arguments always match the account name that a
|
|
posting refers to. To match on the payee of the transaction instead,
|
|
precede the regular expression with @samp{payee} or @@. For example, the
|
|
following balance command reports account totals for rent, food and
|
|
movies, but only those whose payee matches Freddie:
|
|
|
|
@smallexample
|
|
ledger bal rent food movies payee freddie
|
|
@end smallexample
|
|
@noindent or
|
|
@smallexample
|
|
ledger bal rent food movies @@freddie
|
|
@end smallexample
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax
|
|
@section Detailed Option Description
|
|
|
|
With all of the reports, command-line options are useful to modify the
|
|
output generated. The basic form for most commands is:
|
|
|
|
@smallexample
|
|
ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
|
|
@end smallexample
|
|
|
|
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.
|
|
|
|
@subsection Basic options
|
|
|
|
These are the most basic command options. Most likely, the user will
|
|
want to set them using environment variables (see @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.
|
|
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
|
|
postings, but it may contain option settings. To specify options
|
|
in the init file, use the same syntax as the command-line, but put each
|
|
option on it's own line. Here's an example init file:
|
|
|
|
@smallexample
|
|
--price-db ~/finance/.pricedb
|
|
--cache /tmp/ledger-cache
|
|
|
|
; ~/.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 postings are assumed to relate to.
|
|
|
|
@subsection Report filtering
|
|
|
|
These options change which postings affect the outcome of a
|
|
report, in ways other than just using regular expressions:
|
|
|
|
@option{--current}(@option{-c}) displays only transactions occurring on or
|
|
before the current date.
|
|
|
|
@option{--begin DATE} (@option{-b DATE}) constrains the report to
|
|
transactions on or after @var{DATE}. Only transactions after that date will be
|
|
calculated, which means that the running total in the balance report
|
|
will always start at zero with the first matching transaction. (Note: This
|
|
is different from using @option{--display} to constrain what is
|
|
displayed).
|
|
|
|
@option{--end DATE} (@option{-e DATE}) constrains the report so that
|
|
transactions 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 transactions within each
|
|
period separately, making it easy to see weekly, monthly, quarterly,
|
|
etc., posting totals. A period string can even specify the
|
|
beginning and end of the report range, using simple terms like ``last
|
|
june'' or ``next month''. For more using period expressions, see
|
|
@ref{Period Expressions}.
|
|
|
|
@option{--period-sort EXPR} sorts the postings 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:
|
|
|
|
@smallexample
|
|
ledger -M --period-sort -At reg ^Expenses
|
|
@end smallexample
|
|
|
|
@option{--cleared} (@option{-C}) displays only postings whose transaction
|
|
has been marked ``cleared'' (by placing an asterix to the right of the
|
|
date).
|
|
|
|
@option{--uncleared} (@option{-U}) displays only postings whose
|
|
transaction 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 postings, not virtual.
|
|
(A virtual posting is indicated by surrounding the account name with
|
|
parentheses or brackets; see @ref{Virtual Transactions} for more
|
|
information).
|
|
|
|
@option{--actual} (@option{-L}) displays only actual postings, and
|
|
not those created due to automated postings.
|
|
|
|
@option{--related} (@option{-r}) displays postings that are
|
|
related to whichever postings would otherwise have matched the
|
|
filtering criteria. In the register report, this shows where money
|
|
went to, or the account it came from. In the balance report, it shows
|
|
all the accounts affected by transactions having a related posting.
|
|
For example, if a file had this transaction:
|
|
|
|
@smallexample
|
|
2004/03/20 Safeway
|
|
Expenses:Food $65.00
|
|
Expenses:Cash $20.00
|
|
Assets:Checking $-85.00
|
|
@end smallexample
|
|
|
|
And the register command was:
|
|
|
|
@smallexample
|
|
ledger -r register food
|
|
@end smallexample
|
|
|
|
The following would be output, showing the postings related to the
|
|
posting 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 postings
|
|
meet your budget. @option{--add-budget} also shows unbudgeted
|
|
postings, 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 postings
|
|
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.
|
|
|
|
@menu
|
|
* Search Terms::
|
|
* Output Customization::
|
|
* Commodity Reporting::
|
|
* Environment Variables::
|
|
@end menu
|
|
|
|
@node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description
|
|
@subsection Search Terms
|
|
|
|
Valid LEDGER invocations look like:
|
|
@smallexample
|
|
ledger [OPTIONS] <COMMAND> <SEARCH-TERMS>
|
|
@end smallexample
|
|
|
|
Where @samp{COMMAND} is any command verb (@pxref{Basic Reporting Commands}), @samp{OPTIONS} can occur
|
|
anywhere, and @samp{SEARCH-TERM} is one or more of the following:
|
|
|
|
@smallexample
|
|
word search for any account containing 'word'
|
|
TERM and TERM boolean AND between terms
|
|
TERM or TERM boolean OR between terms
|
|
not TERM invert the meaning of the term
|
|
payee word search for any payee containing 'word'
|
|
@@word shorthand for 'payee word'
|
|
desc word alternate for 'payee word'
|
|
note word search for any note containing 'word'
|
|
&word shorthand for 'note word'
|
|
tag word search for any metadata tag containing 'word'
|
|
tag word=value search for any metadata tag containing 'word'
|
|
whose value contains 'value'
|
|
%word shorthand for 'tag word'
|
|
%word=value shorthand for 'tag word=value'
|
|
meta word alternate for 'tag word'
|
|
meta word=value alternate for 'tag word=value'
|
|
expr 'EXPR' apply the given value expression as a predicate
|
|
'=EXPR' shorthand for 'expr EXPR'
|
|
\( TERMS \) group terms; useful if using and/or/not
|
|
@end smallexample
|
|
|
|
So, to list all transaction that charged to ``ffod'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent:
|
|
|
|
@smallexample
|
|
ledger reg food not dining @@chang
|
|
ledger reg food and not dining and not payee chang
|
|
ledger reg food not dining expr 'payee =~ /chang/'
|
|
@end smallexample
|
|
|
|
@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description
|
|
@subsection Output Customization
|
|
|
|
These options affect only the output, but not which postings are
|
|
used to create it:
|
|
|
|
@option{--collapse} (@option{-n}) causes transactions in a
|
|
@command{register} report with multiple postings to be collapsed
|
|
into a single, subtotaled transaction.
|
|
|
|
@option{--subtotal} (@option{-s}) causes all transactions in a
|
|
@command{register} report to be collapsed into a single, subtotaled
|
|
transaction.
|
|
|
|
@option{--by-payee} (@option{-P}) reports subtotals by payee.
|
|
|
|
@option{--comm-as-payee} (@option{-x}) changes the payee of every
|
|
posting to be the commodity used in that posting. This can be
|
|
useful when combined with other options, such as @option{-s}.
|
|
|
|
@option{--empty} (@option{-E}) includes even empty accounts in the
|
|
@command{balance} report.
|
|
|
|
@option{--weekly} (@option{-W}) reports posting totals by the
|
|
week. The week begins on whichever day of the week begins the month
|
|
containing that posting. To set a specific begin date, use a
|
|
period string, such as @samp{weekly from DATE}. @option{--monthly}
|
|
(@option{-M}) reports posting totals by month; @option{--yearly}
|
|
(@option{-Y}) reports posting totals by year. For more complex
|
|
period, using the @option{--period} option described above.
|
|
|
|
@option{--dow} reports postings totals for each day of the week.
|
|
This is an easy way to see if weekend spending is more than on
|
|
weekdays.
|
|
|
|
@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 transactions to be printed. This
|
|
is different from using the command-line utility @command{head}, which
|
|
would limit to the first N postings. @option{--tail} outputs only
|
|
the last N transactions. Both options may be used simultaneously. If a
|
|
negative amount is given, it will invert the meaning of the flag
|
|
(instead of the first five transactions being printed, for example, it
|
|
would print all but the first five).
|
|
|
|
@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 posting
|
|
value.
|
|
|
|
@option{--deviation} (@option{-D}) reports each posting'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 outputs nothing but the date and the value column,
|
|
and the latter without commodities. This is only meaningful if the
|
|
report uses a single commodity. This data can then be fed to other
|
|
programs, which could plot the date, analyze it, etc.
|
|
|
|
@option{--total-data} (@option{-J}) changes the @command{register}
|
|
report so that it outputs nothing but the date and totals column,
|
|
without commodities.
|
|
|
|
@option{--display EXPR} (@option{-d EXPR}) limits which postings
|
|
or accounts or actually displayed in a report. They might still be
|
|
calculated, and be part of the running total of a register report, for
|
|
example, but they will not be displayed. This is useful for seeing
|
|
last month's checking postings, against a running balance which
|
|
includes all posting values:
|
|
|
|
@smallexample
|
|
ledger -d "d>=[last month]" reg checking
|
|
@end smallexample
|
|
|
|
The output from this command is very different from the following,
|
|
whose running total includes only postings from the last month
|
|
onward:
|
|
|
|
@smallexample
|
|
ledger -p "last month" reg checking
|
|
@end smallexample
|
|
|
|
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, Detailed Options Description
|
|
@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:
|
|
|
|
@smallexample
|
|
; Don't download quotes for the dollar, or timelog values
|
|
N $
|
|
N h
|
|
@end smallexample
|
|
|
|
@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 postings.
|
|
|
|
@item -V, --market
|
|
Reports the last known market value for all commodities.
|
|
|
|
@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, Detailed Options Description
|
|
@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:
|
|
|
|
@smallexample
|
|
--cache /tmp/.mycache
|
|
--pager /bin/cat
|
|
|
|
@end smallexample
|
|
|
|
@node Period Expressions, , Detailed Options Description, Command-line Syntax
|
|
@section Period Expressions
|
|
|
|
A period expression indicates a span of time, or a reporting interval,
|
|
or both. The full syntax is:
|
|
|
|
@smallexample
|
|
[INTERVAL] [BEGIN] [END]
|
|
@end smallexample
|
|
|
|
The optional @var{INTERVAL} part may be any one of:
|
|
|
|
@smallexample
|
|
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 smallexample
|
|
|
|
After the interval, a begin time, end time, both or neither may be
|
|
specified. As for the begin time, it can be either of:
|
|
|
|
@smallexample
|
|
from <SPEC>
|
|
since <SPEC>
|
|
@end smallexample
|
|
|
|
The end time can be either of:
|
|
|
|
@smallexample
|
|
to <SPEC>
|
|
until <SPEC>
|
|
@end smallexample
|
|
|
|
Where @var{SPEC} can be any of:
|
|
|
|
@smallexample
|
|
2004
|
|
2004/10
|
|
2004/10/1
|
|
10/1
|
|
october
|
|
oct
|
|
this week # or day, month, quarter, year
|
|
next week
|
|
last week
|
|
@end smallexample
|
|
|
|
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:
|
|
|
|
@smallexample
|
|
<SPEC>
|
|
in <SPEC>
|
|
@end smallexample
|
|
|
|
Here are a few examples of period expressions:
|
|
|
|
@smallexample
|
|
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 smallexample
|
|
|
|
|
|
@node Basic Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top
|
|
@chapter Basic Reporting Commands
|
|
@menu
|
|
* balance::
|
|
* register::
|
|
* print::
|
|
* output::
|
|
* xml::
|
|
* emacs::
|
|
* equity::
|
|
* prices::
|
|
* xact::
|
|
@end menu
|
|
|
|
@node balance, register, Basic Reporting Commands, Basic Reporting Commands
|
|
@section 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.
|
|
|
|
@node register, print, balance, Basic Reporting Commands
|
|
@section register
|
|
|
|
The @command{register} command displays all the postings occurring
|
|
in a single account, line by line. The account regexp must be
|
|
specified as the only argument to this command. If any regexps occur
|
|
after the required account name, the register will contain only those
|
|
postings that match. Very useful for hunting down a particular
|
|
posting.
|
|
|
|
The output from @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.
|
|
|
|
@node print, output, register, Basic Reporting Commands
|
|
@section print
|
|
|
|
The @command{print} command prints out ledger transactions in a textual
|
|
format that can be parsed by LEDGER. They will be properly formatted,
|
|
and output in the most economic form possible. The ``print'' command
|
|
also takes a list of optional regexps, which will cause only those
|
|
postings which match in some way to be printed.
|
|
|
|
The @command{print} command can be a handy way to clean up a ledger
|
|
file whose formatting has gotten out of hand.
|
|
|
|
@node output, xml, print, Basic Reporting Commands
|
|
@section 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:
|
|
|
|
@smallexample
|
|
ledger -f FILENAME output FILENAME
|
|
@end smallexample
|
|
|
|
Where @file{FILENAME} is the name of the ledger file to output. The
|
|
reason for specifying this command is that only transactions contained
|
|
within that file will be output, and not an included transactions (as can
|
|
happen with the @command{print} command).
|
|
|
|
@node xml, emacs, output, Basic Reporting Commands
|
|
@section 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
|
|
posting.
|
|
|
|
@node emacs, equity, xml, Basic Reporting Commands
|
|
@section emacs
|
|
|
|
The @command{emacs} command outputs results in a form that can be read
|
|
directly by Emacs Lisp. The format of the sexp is:
|
|
|
|
@smallexample
|
|
((BEG-POS CLEARED DATE CODE PAYEE
|
|
(ACCOUNT AMOUNT)...) ; list of postings
|
|
...) ; list of transactions
|
|
@end smallexample
|
|
|
|
@node equity, prices, emacs, Basic Reporting Commands
|
|
@section equity
|
|
|
|
The @command{equity} command prints out accounts balances as if they
|
|
were transactions. This makes it easy to establish the starting balances
|
|
for an account, such as when @ref{Archiving Previous Years}.
|
|
|
|
@node prices, xact, equity, Basic Reporting Commands
|
|
@section 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.
|
|
|
|
@node xact, , prices, Basic Reporting Commands
|
|
@section xact
|
|
|
|
The @command{xact} commands simplifies the creation of new transactions.
|
|
It works on the principle that 80% of all postings are variants of
|
|
earlier postings. Here's how it works:
|
|
|
|
Say you currently have this posting in your ledger file:
|
|
|
|
@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{xact} command you can type:
|
|
|
|
@smallexample
|
|
ledger xact 2004/4/9 viva food 11 tips 2.50
|
|
@end smallexample
|
|
|
|
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 posting matching the regular expression
|
|
@samp{viva}, and assuming that any accounts or amounts specified will
|
|
be similar to that earlier posting. If LEDGER does not succeed in
|
|
generating a new transaction, an error is printed and the exit code is set
|
|
to @samp{1}.
|
|
|
|
There is a shell script in the distribution's @file{scripts} directory
|
|
called @file{xact}, which simplifies the task of adding a new transaction
|
|
to your ledger. It launches @command{vi} to confirm that the transaction
|
|
looks appropriate.
|
|
|
|
Here are a few more examples of the @command{xact} command, assuming
|
|
the above journal transaction:
|
|
|
|
@smallexample
|
|
ledger xact 4/9 viva 11.50
|
|
ledger xact 4/9 viva 11.50 checking # (from `checking')
|
|
ledger xact 4/9 viva food 11.50 tips 8
|
|
ledger xact 4/9 viva food 11.50 tips 8 cash
|
|
ledger xact 4/9 viva food $11.50 tips $8 cash
|
|
ledger xact 4/9 viva dining "DM 11.50"
|
|
@end smallexample
|
|
|
|
|
|
@menu
|
|
* Budgeting and Forecasting::
|
|
@end menu
|
|
|
|
@node Budgeting and Forecasting, Value Expressions, Basic Reporting Commands, Top
|
|
@chapter Budgeting and Forecasting
|
|
|
|
|
|
@node Value Expressions, Format Strings, Budgeting and Forecasting, Top
|
|
@chapter 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
|
|
postings 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 postings.
|
|
@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:
|
|
|
|
@smallexample
|
|
ledger -d /^Liabilities/?T<0:UT>100 balance
|
|
@end smallexample
|
|
|
|
The effect is that account totals are displayed only if: 1) A
|
|
Liabilities account has a total less than zero; or 2) the absolute
|
|
value of the account's total exceeds 100 units of whatever commodity
|
|
contains. If it contains multiple commodities, only one of them must
|
|
exceed 100 units.
|
|
|
|
Display predicates are also very handy with register reports, to
|
|
constrain which transactions are printed. For example, the following
|
|
command shows only transactions from the beginning of the current month,
|
|
while still calculating the running balance based on all transactions:
|
|
|
|
@smallexample
|
|
ledger -d "d>[this month]" register checking
|
|
@end smallexample
|
|
|
|
This advantage to this command's complexity is that it prints the
|
|
running total in terms of all transactions in the register. The following,
|
|
simpler command is similar, but totals only the displayed
|
|
postings:
|
|
|
|
@smallexample
|
|
ledger -b "this month" register checking
|
|
@end smallexample
|
|
|
|
@menu
|
|
* Variables::
|
|
@end menu
|
|
|
|
@node Variables, , Value Expressions, Value Expressions
|
|
@section Variables
|
|
|
|
Below are the one letter variables available in any value expression.
|
|
For the register and print commands, these variables relate to
|
|
individual postings, and sometimes the account affected by a
|
|
posting. For the balance command, these variables relate to
|
|
accounts---often with a subtle difference in meaning. The use of each
|
|
variable for both is specified.
|
|
|
|
@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
|
|
|
|
@subsection Posting/account details
|
|
|
|
@table @code
|
|
@item d
|
|
A posting's date, as the number of seconds past the epoch. This
|
|
is always ``today'' for an account.
|
|
|
|
@item a
|
|
The posting's amount; the balance of an account, without
|
|
considering children.
|
|
|
|
@item b
|
|
The cost of a posting; the cost of an account, without its
|
|
children.
|
|
|
|
@item v
|
|
The market value of a posting, or an account without its children.
|
|
|
|
@item g
|
|
The net gain (market value minus cost basis), for a posting 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 posting, or the count of postings affecting an
|
|
account.
|
|
|
|
@item X
|
|
1 if a posting's transaction has been cleared, 0 otherwise.
|
|
|
|
@item R
|
|
1 if a posting is not virtual, 0 otherwise.
|
|
|
|
@item Z
|
|
1 if a posting is not automated, 0 otherwise.
|
|
@end table
|
|
|
|
@subsection Calculated totals
|
|
|
|
@table @code
|
|
@item O
|
|
The total of all postings seen so far, or the total of an account
|
|
and all its children.
|
|
|
|
@item N
|
|
The total count of postings affecting an account and all its
|
|
children.
|
|
|
|
@item B
|
|
The total cost of all postings seen so far; the total cost of an
|
|
account and all its children.
|
|
|
|
@item V
|
|
The market value of all postings 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
|
|
postings, or an account and its children. It is the same as
|
|
@samp{V-B}.
|
|
@end table
|
|
|
|
@section 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
|
|
|
|
@section Operators
|
|
|
|
The binary and ternary operators, in order of precedence, are:
|
|
|
|
@enumerate
|
|
@item @samp{* /}
|
|
@item @samp{+ -}
|
|
@item @samp{! < > =}
|
|
@item @samp{& | ?:}
|
|
@end enumerate
|
|
|
|
@section 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 posting, this will match against the account affected by the
|
|
posting.
|
|
|
|
@item //REGEXP/
|
|
@item p/REGEXP/
|
|
A regular expression that matches against a transaction's payee name.
|
|
|
|
@item ///REGEXP/
|
|
@item w/REGEXP/
|
|
A regular expression that matches against an account's base name. If
|
|
a posting, this will match against the account affected by the
|
|
posting.
|
|
|
|
@item c/REGEXP/
|
|
A regular expression that matches against the transaction code (the text
|
|
that occurs between parentheses before the payee name).
|
|
|
|
@item e/REGEXP/
|
|
A regular expression that matches against a posting'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 Format Strings, Journal File Format, Value Expressions, Top
|
|
@chapter 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 posting in custom ways.
|
|
|
|
Within a format strings, a substitution is specified using a percent
|
|
character (@samp{%}). The basic format of all substitutions is:
|
|
|
|
@smallexample
|
|
%[-][MIN WIDTH][.MAX WIDTH]EXPR
|
|
@end smallexample
|
|
|
|
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:
|
|
|
|
@smallexample
|
|
%-P a transaction's payee, left justified
|
|
%20P The same, right justified, at least 20 chars wide
|
|
%.20P The same, no more than 20 chars wide
|
|
%-.20P Left justified, maximum twenty chars wide
|
|
@end smallexample
|
|
|
|
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 posting'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 transaction's data was read.
|
|
|
|
@item B
|
|
Inserts the beginning character position of that transaction within the file.
|
|
|
|
@item b
|
|
Inserts the beginning line of that transaction within the file.
|
|
|
|
@item E
|
|
Inserts the ending character position of that transaction within the file.
|
|
|
|
@item e
|
|
Inserts the ending line of that transaction 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 transaction has an
|
|
effective date, in which case it prints
|
|
@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.
|
|
|
|
@item X
|
|
If a posting 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 postings have the same state.
|
|
|
|
@item C
|
|
Inserts the checking number for a transaction, in parentheses, followed by
|
|
a space; if none was specified, nothing is inserted.
|
|
|
|
@item P
|
|
Inserts the payee related to a posting.
|
|
|
|
@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
|
|
posting's state @emph{if the transaction's posting states are not
|
|
all the same}, followed by the full account name. This is offered as
|
|
a printing optimization, so that combined with @samp{%Y}, only the
|
|
minimum amount of state detail is printed.
|
|
|
|
@item o
|
|
Inserts the ``optimized'' form of a posting's amount. This is
|
|
used by the print report. In some cases, this inserts nothing; in
|
|
others, it inserts the posting amount and its cost. It's use is
|
|
not recommend unless you are modifying the print report.
|
|
|
|
@item n
|
|
Inserts the note associated with a posting, preceded by two spaces
|
|
and a semi-colon, if it exists. Thus, no none becomes an empty
|
|
string, while the note @samp{foo} is substituted as @samp{ ; foo}.
|
|
|
|
@item N
|
|
Inserts the note associated with a posting, if one exists.
|
|
|
|
@item /
|
|
The @samp{%/} construct is special. It separates a format string
|
|
between what is printed for the first posting of a transaction, and
|
|
what is printed for all subsequent postings. If not used, the
|
|
same format string is used for all postings.
|
|
@end table
|
|
|
|
|
|
@node Journal File Format, Extending with Python, Format Strings, Top
|
|
@chapter Journal File Format for Developers
|
|
|
|
This chapter offers a complete description of the journal data format,
|
|
suitable for implementors in other languages to follow. For users,
|
|
the chapter on keeping a journal is less extensive, but more typical
|
|
of common usage (@pxref{Keeping a Journal}).
|
|
|
|
Data is collected in the form of @dfn{transactions} which occur in one
|
|
or more @dfn{journal files}. Each transaction, in turn, is made up of
|
|
one or more @dfn{postings}, which describe how @dfn{amounts} flow from
|
|
one @dfn{account} to another. Here is an example of the simplest of
|
|
journal files:
|
|
|
|
@smallexample
|
|
2010/05/31 Just an example
|
|
Expenses:Some:Account $100.00
|
|
Income:Another:Account
|
|
@end smallexample
|
|
|
|
In this example, there is a transaction date, a payee, or description
|
|
of the transaction, and two postings. The postings show movement of
|
|
one hundred dollars from an account within the Income hierarchy, to
|
|
the specified expense account. The name and meaning of these accounts
|
|
in arbitrary, with no preferences implied, although you will find it
|
|
useful to follow standard accounting practice (@pxref{Principles of
|
|
Accounting}).
|
|
|
|
Since an amount is missing from the second posting, it is assumed to
|
|
be the inverse of the first. This guarantee the cardinal rule of
|
|
double-entry accounting: the sum of every transaction must balance to
|
|
zero, or it is in error. Whenever Ledger encounters a @dfn{null
|
|
posting} in a transaction, it uses it to balance the remainder.
|
|
|
|
It is also typical---though not enforced---to think of the first
|
|
posting as the destination, and the final as the source. Thus, the
|
|
amount of the first posting is typically positive. Consider:
|
|
|
|
@smallexample
|
|
2010/05/31 An income transaction
|
|
Assets:Checking $1,000.00
|
|
Income:Salary
|
|
|
|
2010/05/31 An expense transaction
|
|
Expenses:Dining $100.00
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
@emph{Note:} It is important to note that there must be at least two spaces between
|
|
the end of the post and the beginning of the amount (including and
|
|
commdity designator).
|
|
|
|
@section Specifying amounts
|
|
|
|
The heart of a journal is the amounts it records, and this fact is
|
|
reflected in the diversity of amount expressions allowed. All of them
|
|
are covered here, though it must be said that sometimes, there are
|
|
multiple ways to achieve a desired result.
|
|
|
|
@subsection Integer amounts
|
|
|
|
In the simplest form, bare decimal numbers are accepted:
|
|
|
|
@smallexample
|
|
2010/05/31 An income transaction
|
|
Assets:Checking 1000.00
|
|
Income:Salary
|
|
@end smallexample
|
|
|
|
Such amounts may only use an optional period for a decimal point.
|
|
These are referred to as @dfn{integer amounts} or @dfn{uncommoditized
|
|
amounts}. In most ways they are similar to @dfn{commoditized
|
|
amounts}, but for one signficant difference: They always display in
|
|
reports with @dfn{full precision}. More on this in a moment. For
|
|
now, a word must be said about how Ledger stores numbers.
|
|
|
|
Every number parsed by Ledger is stored internally as an
|
|
infinite-precision rational value. Floating-point math is never used,
|
|
as it cannot be trusted to maintain precision of values. So, in the
|
|
case of @samp{1000.00} above, the internal value is @samp{100000/100}.
|
|
|
|
While rational numbers are great at not losing precision, the question
|
|
arises: How should they be displayed? A number like @samp{100000/100}
|
|
is no problem, since it represents a clean decimal fraction. But what
|
|
about when the number @samp{1/1} is divided by three? How should one
|
|
print @samp{1/3}, an infinitely repeating decimal?
|
|
|
|
Ledger gets around this problem by rendering rationals into decimal at
|
|
the last possible moment, and only for display. As such, some
|
|
rounding must, at times, occur. If this rounding would affect the
|
|
calculation of a running total, special accommodation postings are
|
|
generated to make you aware it has happened. In practice, it happens
|
|
rarely, but even then it does not reflect adjustment of the
|
|
@emph{internal amount}, only the displayed amount.
|
|
|
|
What has still not been answered is how Ledger rounds values. Should
|
|
@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For
|
|
commoditized amounts, the number of decimal places is decided by
|
|
observing how each commodity is used; but in the case of integer
|
|
amounts, an arbitrary factor must be chosen. Initially, this factor
|
|
is six. Thus, @samp{1/3} is printed back as @samp{0.333333}.
|
|
Further, this rounding factor becomes associated with each particular
|
|
value, and is carried through mathematical operations. For example,
|
|
if that particular number were multiplied by itself, the decimal
|
|
precision of the result would be twelve. Addition and subtraction do
|
|
not affect precision.
|
|
|
|
Since each integer amount retains its own display precision, this is
|
|
called @dfn{full precision}, as opposed to commoditized amounts, which
|
|
always look to their commodity to know what precision they should
|
|
round to, and so use @dfn{commodity precision}.
|
|
|
|
@subsection Commoditized amounts
|
|
|
|
A @dfn{commoditized amount} is an integer amount which has an
|
|
associated commodity. This commodity can appear before or after the
|
|
amount, and may or may not be separated from it by a space. Most
|
|
characters are allowed in a commodity name, except for the following:
|
|
|
|
@itemize
|
|
@item Any kind of whitespace
|
|
@item Numerical digits
|
|
@item Punctuation: @samp{.,;:?!}
|
|
@item Mathematical and logical operators: @samp{-+*/^&|=}
|
|
@item Bracketing characters: @samp{<>[]()}@{@}
|
|
@item The at symbol: @samp{@@}
|
|
@end itemize
|
|
|
|
And yet, any of these may appear in a commodity name if it is
|
|
surrounded by double quotes, for example:
|
|
|
|
@smallexample
|
|
100 "EUN+133"
|
|
@end smallexample
|
|
|
|
If a @dfn{quoted commodity} is found, it is displayed in quotes as
|
|
well, to avoid any confusion as to which part is the amount, and which
|
|
part is the commodity.
|
|
|
|
Another feature of commoditized amounts is that they are reported back
|
|
in the same form as parsed. If you specify dollar amounts using
|
|
@samp{$100}, they will print the same; likewise with @samp{100 $} or
|
|
@samp{$100.000}. You may even use decimal commas, such as
|
|
@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}.
|
|
|
|
These display characteristics become associated with the commodity,
|
|
with the result being that all amounts of the same commodity are
|
|
reported consistently. Where this is most noticeable is the
|
|
@dfn{display precision}, which is determined by the most precise value
|
|
seen for a given commodity. In most cases.
|
|
|
|
Ledger makes a distinction by @dfn{observed amounts} and unobserved
|
|
amounts. An observed amount is critiqued by Ledger to determine how
|
|
amounts using that commodity should be displayed; unobserved amounts
|
|
are significant in their value only---no matter how they are
|
|
specified, it does not change how other amounts in that commodity will
|
|
be displayed.
|
|
|
|
An example of this is found in cost expressions, covered next.
|
|
|
|
@section Posting costs
|
|
|
|
You have seen how to specify either a commoditized or an integer
|
|
amount for a posting. But what if the amount you paid for something
|
|
was in one commodity, and the amount received was another? There are
|
|
two main ways to express this:
|
|
|
|
@smallexample
|
|
2010/05/31 Farmer's Market
|
|
Assets:My Larder 100 apples
|
|
Assets:Checking $20.00
|
|
@end smallexample
|
|
|
|
In this example, you have paid twenty dollars for one hundred apples.
|
|
The cost to you is twenty cents per apple, and Ledger calculates this
|
|
implied cost for you. You can also make the cost explicit using a
|
|
@dfn{cost amount}:
|
|
|
|
@smallexample
|
|
2010/05/31 Farmer's Market
|
|
Assets:My Larder 100 apples @@ $0.200000
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
Here the @dfn{per-unit cost} is given explicitly in the form of a cost
|
|
amount; and since cost amount are @emph{unobserved}, the use of six
|
|
decimal places has no effect on how dollar amounts are displayed in
|
|
the final report. You can also specify the @dfn{total cost}:
|
|
|
|
@smallexample
|
|
2010/05/31 Farmer's Market
|
|
Assets:My Larder 100 apples @@@@ $20
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
These three forms have identical meaning. In most cases the first is
|
|
preferred, but the second two are necessary when more than two
|
|
postings are involved:
|
|
|
|
@smallexample
|
|
2010/05/31 Farmer's Market
|
|
Assets:My Larder 100 apples @@ $0.200000
|
|
Assets:My Larder 100 pineapples @@ $0.33
|
|
Assets:My Larder 100 "crab apples" @@ $0.04
|
|
Assets:Checking
|
|
@end smallexample
|
|
|
|
Here the implied cost is @samp{$57.00}, which is entered into the null
|
|
posting automatically so that the transaction balances.
|
|
|
|
@subsection Primary commodities
|
|
|
|
In every transaction involving more than one commodity, there is
|
|
always one which is the @dfn{primary commodity}. This commodity
|
|
should be thought of as the exchange commodity, or the commodity used
|
|
to buy and sells units of the other commodity. In the fruit examples
|
|
above, dollars are the primary commodity. This is decided by Ledger
|
|
on the placement of the commodity in the transaction:
|
|
|
|
@smallexample
|
|
2010/05/31 Sample Transaction
|
|
Expenses 100 secondary
|
|
Assets 50 primary
|
|
|
|
2010/05/31 Sample Transaction
|
|
Expenses 100 secondary @@ 0.5 primary
|
|
Assets
|
|
|
|
2010/05/31 Sample Transaction
|
|
Expenses 100 secondary @@@@ 50 primary
|
|
Assets
|
|
@end smallexample
|
|
|
|
The only case where knowledge of primary versus secondary comes into
|
|
play is in reports that use the @option{-V} or @option{-B} options.
|
|
With these, only primary commodities are shown.
|
|
|
|
If a transaction uses only one commodity, this commodity is also
|
|
considered a primary. In fact, when Ledger goes about ensures that
|
|
all transactions balance to zero, it only ever asks this of primary
|
|
commodities.
|
|
|
|
@node Extending with Python, Example Data File, Journal File Format, Top
|
|
@chapter Extending with Python
|
|
|
|
@node Example Data File, Miscellaneous Notes, Extending with Python, Top
|
|
@appendix Example Journal File: drewr.dat
|
|
The following journal file is included with the source distribution of
|
|
ledger. It is called @file{drewr.dat} and exhibits many ledger
|
|
features, include automatic and virtual transactions,
|
|
@smallexample
|
|
; -*- ledger -*-
|
|
|
|
= /^Income/
|
|
(Liabilities:Tithe) 0.12
|
|
|
|
~ Monthly
|
|
Assets:Checking $500.00
|
|
Income:Salary
|
|
|
|
2003/12/01 * Checking balance
|
|
Assets:Checking $1,000.00
|
|
Equity:Opening Balances
|
|
|
|
2003/12/20 Organic Co-op
|
|
Expenses:Food:Groceries $ 37.50 ; [=2004/01/01]
|
|
Expenses:Food:Groceries $ 37.50 ; [=2004/02/01]
|
|
Expenses:Food:Groceries $ 37.50 ; [=2004/03/01]
|
|
Expenses:Food:Groceries $ 37.50 ; [=2004/04/01]
|
|
Expenses:Food:Groceries $ 37.50 ; [=2004/05/01]
|
|
Expenses:Food:Groceries $ 37.50 ; [=2004/06/01]
|
|
Assets:Checking $ -225.00
|
|
|
|
2003/12/28=2004/01/01 Acme Mortgage
|
|
Liabilities:Mortgage:Principal $ 200.00
|
|
Expenses:Interest:Mortgage $ 500.00
|
|
Expenses:Escrow $ 300.00
|
|
Assets:Checking $ -1000.00
|
|
|
|
2004/01/02 Grocery Store
|
|
Expenses:Food:Groceries $ 65.00
|
|
Assets:Checking
|
|
|
|
2004/01/05 Employer
|
|
Assets:Checking $ 2000.00
|
|
Income:Salary
|
|
|
|
2004/01/14 Bank
|
|
; Regular monthly savings transfer
|
|
Assets:Savings $ 300.00
|
|
Assets:Checking
|
|
|
|
2004/01/19 Grocery Store
|
|
Expenses:Food:Groceries $ 44.00
|
|
Assets:Checking
|
|
|
|
2004/01/25 Bank
|
|
; Transfer to cover car purchase
|
|
Assets:Checking $ 5,500.00
|
|
Assets:Savings
|
|
; :nobudget:
|
|
|
|
2004/01/25 Tom's Used Cars
|
|
Expenses:Auto $ 5,500.00
|
|
; :nobudget:
|
|
Assets:Checking
|
|
|
|
2004/01/27 Book Store
|
|
Expenses:Books $20.00
|
|
Liabilities:MasterCard
|
|
|
|
2004/02/01 Sale
|
|
Assets:Checking:Business $ 30.00
|
|
Income:Sales
|
|
|
|
@end smallexample
|
|
|
|
@node Miscellaneous Notes, , Example Data File, Top
|
|
@appendix Miscellaneous Notes
|
|
|
|
Various notes from the discussion list that I haven't incorporated in to the main body of the documentation.
|
|
|
|
@menu
|
|
* Cookbook::
|
|
@end menu
|
|
|
|
@node Cookbook, , Miscellaneous Notes, Miscellaneous Notes
|
|
@section Cookbook
|
|
|
|
@subsection Invoking Ledger
|
|
|
|
@smallexample
|
|
ledger --group-by "tag('trip')" bal
|
|
legder reg --sort "tag('foo')" %foo
|
|
ledger cleared VWCU NFCU Tithe Misentry
|
|
ledger register Joint --uncleared
|
|
ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25
|
|
@end smallexample
|
|
@subsection Ledger Files
|
|
|
|
@smallexample
|
|
= /^Income:Taxable/
|
|
(Liabilities:Tithe Owed) -0.1
|
|
= /Noah/
|
|
(Liabilities:Tithe Owed) -0.1
|
|
= /Jonah/
|
|
(Liabilities:Tithe Owed) -0.1
|
|
= /Tithe/
|
|
(Liabilities:Tithe Owed) -1.0
|
|
@end smallexample
|
|
|
|
@bye
|