diff options
| -rw-r--r-- | ledger.texi | 1885 |
1 files changed, 1885 insertions, 0 deletions
diff --git a/ledger.texi b/ledger.texi new file mode 100644 index 00000000..a1ada658 --- /dev/null +++ b/ledger.texi @@ -0,0 +1,1885 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ledger.info +@settitle Ledger: Command-Line Accounting + +@documentencoding iso-8859-1 + +@iftex +@finalout +@end iftex + +@titlepage +@title Ledger: Command-Line Accounting +@author John Wiegley +@end titlepage + +@node Top, Introduction, (dir), (dir) +@top Overview +@c Page published by Emacs Muse begins here + + + +@menu +* Introduction:: +* Keeping a ledger:: +* Running Ledger:: +@end menu + +@node Introduction, Keeping a ledger, Top, Top +@chapter Introduction + +Ledger is an accounting tool with the moxie to exist. It provides no +bells or whistles, and returns the user to the days before user +interfaces were even a twinkling in their father's CRT. + +What it does offer is a double-entry accounting ledger with all the +flexibility and muscle of its modern day cousins, without any of the +fat. Think of it as the Bran Muffin of accounting tools. + +To use it, you need to start keeping a ledger. This is the basis of +all accounting, and if you haven't started yet, now is the time to +learn. The little booklet that comes with your checkbook is a ledger, +so we'll describe double-entry accounting in terms of that. + +A checkbook ledger records debits (subtractions, or withdrawals) and +credits (additions, or deposits) with reference to a single account: +the checking account. Where the money comes from, and where it goes +to, are described in the payee field, where you write the person or +company's name. The ultimate aim of keeping a checkbook ledger is to +know how much money is available to spend. That's really the aim of +all ledgers. + +What computers add is the ability to walk through these transactions, +and tell you things about your spending habits; to let you devise +budgets and get control over your spending; to squirrel away money +into virtual savings account without having to physically move money +around; etc. As you keep your ledger, you are recording information +about your life and habits, and sometimes that information can start +telling you things you aren't aware of. Such is the aim of all good +accounting tools. + +The next step up from a checkbook ledger, is a ledger that keeps track +of all your accounts, not just checking. In such a ledger, you record +not only who gets paid---in the case of a debit---but where the +money came from. In a checkbook ledger, its assumed that all the +money comes from your checking account. But in a general ledger, you +write transaction two-lines: the source account and target account. +@emph{There must always be a debit from at least one account for every +credit made to another account}. This is what is meant by +``double-entry'' accounting: the ledger must always balance to zero, +with an equal number of debits and credits. + +For example, let's say you have a checking account and a brokerage +account, and you can write checks from both of them. Rather than keep +two checkbooks, you decide to use one ledger for both. In this +general ledger you need to record a payment to Pacific Bell for your +monthly phone bill. The cost is $23.00, let's say, and you want to +pay it from your checking account. In the general ledger you need to +say where the money came from, in addition to where it's going to. +The entry might look like this: + +@example +9/29 BAL Pacific Bell $-200.00 $-200.00 + Equity:Opening Balances $200.00 +9/29 BAL Checking $100.00 $100.00 + Equity:Opening Balances $-100.00 +9/29 100 Pacific Bell $23.00 $223.00 + Checking $-23.00 $77.00 +@end example + +The first line shows a payment to Pacific Bell for $23.00. Because +there is no ``balance'' in a general ledger---it's always zero---we +write in the total balance of all payments to ``Pacific Bell'', which +now is $223.00 (previously the balance was $200.00). This is done by +looking at the last entry for ``Pacific Bell'' in the ledger, adding +$23.00 to that amount, and writing the total in the balance column. +And the money came from ``Checking''---a withdrawal of $23.00---which +leaves the ending balance in ``Checking'' at $77.00. This is a very +manual procedure; but that's where computers come in... + +The transaction must balance to $0: $23 went to Pacific Bell, $23 came +from Checking. There is nothing left over to be accounted for, since +the money has simply moved from one account to another. This is the +basis of double-entry accounting: that money never pops in or out of +existence; it is always a transaction from one account to another. + +Keeping a general ledger is the same as keeping two separate ledgers: +One for Pacific Bell and one for Checking. In that case, each time a +payment is written into one, you write a corresponding withdrawal into +the other. This makes it easier to write in a ``running balance'', +since you don't have to look back at the last time the account was +referenced---but it also means having a lot of ledger books, if you +deal with multiple accounts. + +Enter the beauty of computerized accounting. The purpose of the +Ledger program is to make general ledger accounting simple, by keeping +track of the balances for you. Your only job is to enter the +transactions. If a transaction does not balance, Ledger will display +an error and indicate which transaction is wrong.@footnote{In some +special cases, it will automatically balance the entry for you.} + +In summary, there are two aspects of Ledger use: updating the ledger +data file, and using the Ledger tool to view the summarized result of +your entries. + +And just for the sake of example---as a starting point for those who +want to dive in head-first---here are the ledger entries from above, +formatting as the ledger program wishes to see them: + +@example +; Set the year for subsequent entries to 2004 +Y 2004 + +9/29 Pacific Bell + Payable:Pacific Bell $-200.00 + Equity:Opening Balances + +9/29 Checking + Accounts:Checking $100.00 + Equity:Opening Balances + +9/29 Pacific Bell + Payable:Pacific Bell $23.00 + Accounts:Checking +@end example + +The account balances and registers in this file, if saved as +@samp{ledger.dat}, could be reported using: + +@example +$ ledger -f ledger.dat balance +$ ledger -f ledger.dat register checking +$ ledger -f ledger.dat register bell +@end example + +@menu +* Building the program:: +@end menu + +@node Building the program, , Introduction, Introduction +@section Building the program + +Ledger is written in ANSI C++, and should compile on any platform. It +depends only on the GNU multiprecision integer library (libgmp), and +the Perl regular expression library (libpcre). It was developed using +GNU make and gcc 3.3. + +To build and install once you have these libraries on your system, +enter these commands: + +@example +make +cp ledger /usr/local/bin +@end example + +Note that when building GNUmp, make sure to pass the +@samp{--enable-cxx} flag to configure, otherwise it will not build +@strong{libgmpxx.a}. And in case it is not already on your system, +@strong{xmlparse.h} is part of the libxmltok package, and not expat. + +@node Keeping a ledger, Running Ledger, Introduction, Top +@chapter Keeping a ledger + +The most important part of accounting is keeping a good ledger. If +you have a good ledger, tools can be written to work whatever +mathematically tricks you need to better understand your spending +patterns. Without a good ledger, no tool, however smart, can help +you. + +The Ledger program aims at making ledger entry as simple as possible. +Since it is a command-line tool, it does not provide a user interface +for keeping a ledger. If you like, you may use GnuCash to maintain +your ledger, in which case the Ledger program will read GnuCash's data +files directly. In that case, read the GnuCash manual now, and skip +to the next chapter. + +If you are not using GnuCash, but a text editor to maintain your +ledger, read on. Ledger has been designed to make data entry as +simple as possible, by keeping the ledger format easy, and also by +automagically determining as much information as possible based on the +nature of your entries. + +For example, you do not need to tell Ledger about the accounts you +use. Any time Ledger sees a transaction involving an account it knows +nothing about, it will create it. If you use a commodity that is new +to Ledger, it will create that commodity, and determine its display +characteristics (placement of the symbol before or after the amount, +display precision, etc) based on how you used the commodity in the +transaction. + +Here is the Pacific Bell example from above, given as a Ledger +transaction: + +@example +9/29 (100) Pacific Bell + Expenses:Utilities:Telephone $23.00 + Assets:Checking $-23.00 +@end example + +As you can see, it is very similar to what would be written on paper, +minus the computed balance totals, and adding in account names that +work better with Ledger's scheme of things. In fact, since Ledger is +smart about many things, you don't need to specify the balanced +amount, if it is the same as the first line: + +@example +9/29 (100) Pacific Bell + Expenses:Utilities:Telephone $23.00 + Assets:Checking +@end example + +For this entry, Ledger will figure out that $-23.00 must come from +``Assets:Checking'' in order to balance the entry. + +@menu +* Stating where money goes:: +* Assets and Liabilities:: +* Commodities and Currencies:: +* Accounts and Inventories:: +* Understanding Equity:: +* Dealing with Petty Cash:: +* Archiving previous years:: +* Virtual transactions:: +* Automated transactions:: +* Differences to Accounting Conventions:: +* Using Emacs to Keep Your Ledger:: +* Using GnuCash to Keep Your Ledger:: +* Using timeclock to record billable time:: +@end menu + +@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger +@section Stating where money goes + +Accountants will talk of `credits' and `debits', but their meaning is +often different from the layman's definitions. To avoid this semantic +overloading, we will refer to subtractions and additions. See +@uref{README.texi#DtAC, ``Differences to Accounting Conventions''} for how to +reconcile the two systems. + +Recall that every transaction will involve two or more accounts. +Money is transferred from one group of accounts to another group. To +record the transaction, @emph{subtract} an amount from the source +accounts, and @emph{add} the same amount to the target accounts. + +In order to write the Ledger entry correctly, you must determine where +the money comes from, and where it goes to. For example, when you are +paid, in order to add to your bank account, you must subtract from an +income account: + +@example +9/29 My Employer + Assets:Checking $500.00 + Income:Salary $-500.00 +@end example + +But wait, you say, why is the Income a negative figure? And when you +look at the balance totals for your ledger, you will certainly be +surprised to see Expenses as a positive figure, and Income as a +negative figure. Isn't that the opposite of how it should look? + +It may take getting used to, but to properly use a general ledger you +will need to think in terms of money flows. Rather than Ledger +``fixing'' the minus signs, let's understand why they are there. + +When you earn money, the money has to come from somewhere. Let's call +that somewhere ``society''. In order for society to give you an +income, you must take money away (withdraw) from society in order to +put it into (make a payment to) your bank. When you then spend that +money, it leaves your bank account (a withdrawal) and goes back to +society (a payment). This is why Income will appear negative---it +reflects the money you have drawn from society---and why Expenses will +be positive---it is the amount you've given back. These additions and +subtractions will always cancel each other out in the end, because you +don't have the ability to create new money: it must always come from +somewhere, and in the end must always leave. This is the beginning of +economy, after which the explanation gets terribly difficult. + +Based on that explanation, here's another way to look at your balance +report: every negative figure means that that account or person or +place has less money now than when you started your ledger; and every +positive figure means that that account or person or place has more +money now that when you started your ledger. Make sense? + +@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger +@section Assets and Liabilities + +Assets are money that you have, and Liabilities are money that you +owe. ``Liabilities'' is just a more inclusive name for Debts. + +An Asset is typically increased by transferring money from an Income +account, such as when you get paid. Here is a typical entry: + +@example +2004/09/29 My Employer + Assets:Checking $500.00 + Income:Salary +@end example + +Money, here, is coming from an Income account belonging to ``My +Employer'', and is being transferred to an account that belongs to you. +The money is now yours, which makes it an asset. + +Liability accounts track money you owe to others. They come into play +whenever you borrow money to buy something, or if you owe someone +money. The usual way a liability is changed is by expending money, +thus transferring it to an Expenses account. For example: + +@example +2004/09/30 Restaurant + Expenses:Dining $25.00 + Liabilities:MasterCard +@end example + +Your account balance will now show $25 spent on Dining, and a +corresponding $25 owed on your MasterCard. The MasterCard liability +will show up as negative, since it offsets the value of your assets. +@emph{The combined total of your Assets and Liabilities is your net +worth}. To see your current net worth, use this command: + +@example +$ ledger balance ^assets ^liabilities +@end example + +Relatedly, your Income accounts will show up negative, because they +transfer money @emph{from} an account in order to increase your +assets. Your Expenses accounts will show up positive, because that is +where the money went. The combined total your Income and Expenses is +your cash flow. A negative cash flow means that you are spending more +cash than you make. To see your current cash flow, use this command: + +@example +$ ledger balance ^income ^expenses +@end example + +Often, it is only important to view your income and expenses when +asking questions like, ``Where did my money go? Am I spending too +much on X? Am I making enough to cover my expenses?'' But most of +the time, you will usually want to ask other questions like, ``Is +there enough money in my checking account to cover my next credit card +bill?'' For these reasons, I recommend creating a script that removes +Income, Expenses, and Equity by default from your basic balance +report. The provided script ``bal'' does this for you, as well as +making it easier to run the balance command: + +@example +$ bal +@end example + +To use this script, it must be copied from the @strong{scripts} +directory in the ledger distribution, to a directory along your +@samp{PATH}. Also, you must set the environment variable +@samp{LEDGER} to point to your main ledger file. + +Another common question to ask of your expenses is: How much do I +spend each month on X? Ledger provides a simple way of displaying +monthly totals for any account. Here is an example that summarizes +monthly automobile expenses: + +@example +$ ledger -M register expenses:auto +@end example + +This assumes, of course, that you use accounts like Expenses:Auto:Gas +and Expenses:Auto:Repair. + +@menu +* Tracking reimbursable expenses:: +@end menu + +@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities +@subsection Tracking reimbursable expenses + +Sometimes you will want to spend money on behalf of someone else, +which will eventually get repaid. Since the money is still ``yours'', +it is really an asset. And since the expenditure was for someone +else, you don't want it contaminating your Expenses reports. You will +need to keep an account for tracking reimbursements. + +This is fairly easy to do in ledger. When spending the money, spend +it @emph{to} your Assets:Reimbursements, using a different account for +each person or business that you spend money for. For example: + +@example +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard +@end example + +This shows that you spent $100.00 on your MasterCard at Circuit City, +but that the expense was made on behalf of Company XYZ. Later, when +Company XYZ pays you back, you will transfer the money from your +reimbursement account to a regular asset account: + +@example +2004/09/29 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ +@end example + +This deposits the money owed from Company XYZ into your checking +account, presumably because they paid you back with a check. + +But what to do if you run your own business, and you want to keep +track of expenses made on your own behalf, while still tracking +everything in a single ledger file? This is more complex, because you +need to track two separate things: 1) The fact that the money should +be reimbursed to you, and 2) What the expense account was, so that you +can later determine where your company is spending its money. + +This kind of transaction is best handled with mirrored transactions in +two different files, one for your personal accounts, and one for your +company accounts. But keeping them in one file involves the same +kinds of transactions, so those are what is shown here. First, the +personal entry, which shows the need for reimbursement: + +@example +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard +@end example + +This is the same as above, except that you own Company XYZ, and are +keeping track of its expenses in the same ledger file. This entry +should be immediately followed by an equivalent entry, which shows the +kind of expense, and also notes the fact that $100.00 is now payable +to you: + +@example +2004/09/29 Circuit City + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name +@end example + +This second entry shows that Company XYZ has just spent $100.00 on +software, and that this $100.00 came from Your Name, which must be +paid back. + +These two entries can also be merged, to make things a little clearer. +Note that all amounts must be specified now: + +@example +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard $-100.00 + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name $-100.00 +@end example + +To ``pay back'' the reimbursement, just reverse the order of everything, +except this time drawing the money from a company asset, paying it to +accounts payable, and then drawing it again from the reimbursement +account, and paying it to your personal asset account. It's easier +shown than said: + +@example +2004/10/15 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ $-100.00 + Company XYZ:Accounts Payable:Your Name $100.00 + Company XYZ:Assets:Checking $-100.00 +@end example + +And now the reimbursements account is paid off, accounts payable is +paid off, and the $100.00 has been effectively transferred from the +company's checking account to your personal checking account. The +money simply ``waited''---in both Assets:Reimbursements:Company XYZ, +and Company XYZ:Accounts Payable:Your Name---until such time as it +could be paid off. + +The value of tracking expenses from both sides like that is that you +do not contaminate your personal expense report with expenses made on +behalf of others, while at the same time making it possible to +generate accurate reports of your company's expenditures. It is more +verbose than just paying for things with your personal assets, but it +gives you a very accurate information trail. + +The advantage to keep these doubled entries together is that they +always stay in sync. The advantage to keeping them apart is that it +clarifies the transfer's point of view. To keep the transactions in +separate files, just separate the two entries that were joined above. +For example, for both the expense and the pay-back shown above, the +following four entries would be created. Two in your personal ledger +file: + +@example +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard $-100.00 + +2004/10/15 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ $-100.00 +@end example + +And two in your company ledger file: + +@example +@@ Company XYZ + +2004/09/29 Circuit City + Expenses:Computer:Software $100.00 + Accounts Payable:Your Name $-100.00 + +2004/10/15 Company XYZ + Accounts Payable:Your Name $100.00 + Assets:Checking $-100.00 + +@@@@ +@end example + +(Note: The @ above command means that all accounts mentioned in the +file are children of the specified account. In this case it means +that all activity in file relates to Company XYZ). + +After creating these entries, you will always know that $100.00 was +spent using your MasterCard on behalf of Company XYZ, and that Company +XYZ spent the money on computer software and paid it back about two +weeks later. + +@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger +@section Commodities and Currencies + +Ledger makes no assumptions about the commodities you use; it only +requires that you specify a commodity. The commodity may be any +non-numeric string that does not contain a period, comma, forward +slash or at-sign. It may appear before or after the amount, although +it is assumed that symbols appearing before the amount refer to +currencies, while non-joined symbols appearing after the amount refer +to commodities. Here are some valid currency and commodity +specifiers: + +@example +$20.00 ; currency: twenty US dollars +40 AAPL ; commodity: 40 shares of Apple stock +60 DM ; currency: 60 Deutsch Mark +£50 ; currency: 50 British pounds +50e ; currency: 50 Euros (use appropriate symbol) +@end example + +Ledger will examine the first use of any commodity to determine how +that commodity should be printed on reports. It pays attention to +whether the name of commodity was separated from the amount, whether +it came before or after, the precision used in specifying the amount, +whether thousand marks were used, etc. This is done so that printing +the commodity looks the same as the way you use it. + +An account may contain multiple commodities, in which case it will +have separate totals for each. For example, if your brokerage account +contains both cash, gold, and several stock quantities, the balance +might look like: + +@example + $200.00 +100.00 AU + AAPL 40 + BORL 100 + FEQTX 50 Assets:Brokerage +@end example + +This balance report shows how much of each commodity is in your +brokerage account. + +Sometimes, you will want to know the current street value of your +balance, and not the commodity totals. For this to happen, you must +specify what the current price is for each commodity. The price can +be in any commodity, in which case the balance will be computed in +terms of that commodity. The usual way to specify prices is with a +file of price settings, which might look like this: + +@example +AU=$357.00 +AAPL=$37 +BORL=$19 +FEQTX=$32 +@end example + +Specify the prices file using the @samp{-p} option: + +@example +ledger -p prices.db balance brokerage +@end example + +Now the balance for your brokerage account will be given in US +dollars, since the prices database has specified conversion factors +from each commodity into dollars: + +@example +$40880.00 Assets:Brokerage +@end example + +You can convert from any commodity to any other commodity. Let's say +you had $5000 in your checking account, and for whatever reason you +wanted to know many ounces of gold that would buy. If gold is +currently $357 per ounce, then each dollar is worth 1/357 AU: + +@example +ledger -p "$=0.00280112 AU" balance checking +@end example + +@example +14.01 AU Assets:Checking +@end example + +$5000 would buy 14 ounces of gold, which becomes the new display +commodity since a conversion factor was provided. + +Commodities conversions can also be chained, up to a depth of 10. +Here is a sample prices database that uses chaining: + +@example +AAPL=$15 +$=0.00280112 AU +AU=300 Euro +Euro=MD 0.75 +@end example + +This is a roundabout way of reporting AAPL shares in their Deutsch +Mark equivalent. + +@menu +* Commodity price histories:: +@end menu + +@node Commodity price histories, , Commodities and Currencies, Commodities and Currencies +@subsection Commodity price histories + +Whenever a commodity is purchased using a different commodity (such as +a share of common stock using dollars), it establishes a price for +that commodity on that day. It is also possible, by recording price +details in a ledger file, to specify other prices for commodities at +any given time. Such price entries might look like those below: + +@example +P 2004/06/21 02:17:58 TWCUX $27.76 +P 2004/06/21 02:17:59 AGTHX $25.41 +P 2004/06/21 02:18:00 OPTFX $39.31 +P 2004/06/21 02:18:01 FEQTX $22.49 +P 2004/06/21 02:18:02 AAPL $32.91 +@end example + +By default, ledger will not consider commodity prices when generating +its various reports. It will always report balances in terms of the +commodity total, rather than the current value of those commodities. +To enable pricing reports, several options are possible: + +@table @strong +@item @strong{-P FILE} +With this option, or if the environment variable @samp{PRICE_HIST} is +set, pricing information obtained from the Internet will be kept +in this file. Also, this file will be read after all other ledger +files are read, so that full history information is available for +reports. + +@item @strong{-O} +Report commodity totals only, not their market value or basis cost. + +@item @strong{-V} +Report commodity values in terms of their last known market price. + +@item @strong{-B} +Report commodities in terms of their ``basis cost'', or what they cost +at time of purchase. Thus, totals in the register and balance +report reflect the total amount spent. + +@item @strong{-G} +Report commodities in terms of their net gain, which is: the market +value minus the cost basis. A balance report using this option +shows very quickly the performance of investments. + +@item @strong{-Q} +When needed (see the @samp{-L} option) pricing quotes are obtained by +calling the script @samp{getquote} (a sample Perl script is provided, but +the interface is kept simple so replacements may be made). + +@item @strong{-L MINS} +When using the @samp{-Q} flag, new quotes are obtained only if current +pricing data is older than MINS minutes. The default is one day, +or 1440 minutes. + +@item @strong{-p ARG} +If a string, such as ``COMM=$1.20'', the commodity COMM will be +reported only in terms of the conversion factor, which supersedes +all other pricing histories for that commodity. This can be used to +perform arbitrary value substitutions. For example, to report the +value of your dollars in terms of the ounces of gold they would buy, +use: -p ``$=0.00280112 AU'' (or whatever the current exchange rate +is). + +@end table + +Note that the @samp{-B}, @samp{-O}, @samp{-V}, and @samp{-G} are mutually exclusive. + +@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger +@section Accounts and Inventories + +Since Ledger's accounts and commodity system is so flexible, you can +have accounts that don't really exist, and use commodities that no one +else recognizes. For example, let's say you are buying and selling +various items in EverQuest, and want to keep track of them using a +ledger. Just add items of whatever quantity you wish into your +EverQuest account: + +@example +9/29 Get some stuff at the Inn + Places:Black's Tavern -3 Apples + Places:Black's Tavern -5 Steaks + EverQuest:Inventory +@end example + +Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The +amounts are negative, because you are taking @emph{from} Black's Tavern in +order to add to your Inventory account. Note that you don't have to +use ``Places:Black's Tavern'' as the source account. You could use +``EverQuest:System'' to represent the fact that you acquired them +online. The only purpose for choosing one kind of source account over +another is for generate more informative reports later on. The more +you know, the better analysis you can perform. + +If you later sell some of these items to another player, the entry +would look like: + +@example +10/2 Strum Brightblade + EverQuest:Inventory -2 Steaks + EverQuest:Inventory 15 Gold +@end example + +Now you've turned 2 steaks into 15 gold, courtesy of your customer, +Strum Brightblade. + +@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Keeping a ledger +@section Understanding Equity + +The most confusing entry in any ledger will be your equity account--- +because starting balances can't come out of nowhere. + +When you first start your ledger, you will likely already have money +in some of your accounts. Let's say there's $100 in your checking +account; then add an entry to your ledger to reflect this amount. +Where will money come from? The answer: your equity. + +@example +10/2 Opening Balance + Assets:Checking $100.00 + Equity:Opening Balances +@end example + +But what is equity? You may have heard of equity when people talked +about house mortgages, as ``the part of the house that you own''. +Basically, equity is like the value of something. If you own a car +worth $5000, then you have $5000 in equity in that car. In order to +turn that car (a commodity) into a cash flow, or a credit to your bank +account, you will have to debit the equity by selling it. + +When you start a ledger, you are probably already worth something. +Your net worth is your current equity. By transferring the money in +the ledger from your equity to your bank accounts, you are crediting +the ledger account based on your prior equity value. That is why, +when you look at the balance report, you will see a large negative +number for Equity that never changes: Because that is what you were +worth (what you debited from yourself in order to start the ledger) +before the money started moving around. If the total positive value +of your assets is greater than the absolute value of your starting +equity, it means you are making money. + +Clear as mud? Keep thinking about it. Until you figure it out, put +``@samp{-- -Equity}'' at the end of your balance command, to remove the +confusing figure from the totals. + +@node Dealing with Petty Cash, Archiving previous years, Understanding Equity, Keeping a ledger +@section Dealing with Petty Cash + +Something that stops many people from keeping a ledger at all is the +insanity of tracking small cash expenses. They rarely generate a +receipt, and there are often a lot of small transactions, rather than +a few large ones, as with checks. + +One solution is: don't bother. Move your spending to a debit card, +but in general ignore cash. Once you withdraw it from the ATM, mark +it as already spent to an ``Expenses:Cash'' category: + +@example +2004/03/15 ATM + Expenses:Cash $100.00 + Assets:Checking +@end example + +If at some point you make a large cash expense that you want to track, +just ``move'' the amount of the expense from ``Expenses:Cash'' into the +target account: + +@example +2004/03/20 Somebody + Expenses:Food $65.00 + Expenses:Cash +@end example + +This way, you can still track large cash expenses, while ignoring all +of the smaller ones. + +@node Archiving previous years, Virtual transactions, Dealing with Petty Cash, Keeping a ledger +@section Archiving previous years + +After a while, your ledger can get to be pretty large. While this +will not slow down the ledger program much---it's designed to process +ledger files very quickly---things can start to feel ``messy''; and +it's a universal complaint that when finances feel messy, people avoid +them. + +Thus, archiving the data from previous years into their own files can +offer a sense of completion, and freedom from the past. But how to +best accomplish this with the ledger program? There are two commands +that make it very simple: ``print'', and ``equity''. + +Let's take an example file, with data ranging from year 2000 until +2004. We want to archive years 2000 and 2001 to their own file, +leaving just 2003 and 2004 in the current file. So, use ``print'' to +output all the earlier entries to a file called @samp{ledger-old.dat}. +(Keeping in mind that the ending date is not inclusive, which is why +2002 is mentioned in the following command): + +@example +$ ledger -f ledger.dat -b 2000/1/1 -e 2002/1/1 print \ + > ledger-old.dat +@end example + +To delete older data from the current ledger file, use ``print'' again, +this time specifying year 2002 as the starting date: + +@example +$ ledger -f ledger.dat -b 2002/1/1 print > x +$ mv x ledger.dat +@end example + +However, now the current file contains @emph{only} transactions from 2002 +onward, which will not yield accurate present-day balances, because +the net income from previous years is no longer being tallied. To +compensate for this, we must append an equity report for the old +ledger at the beginning of the new one: + +@example +$ ledger -f ledger-old.dat equity > equity.dat +$ cat equity.dat ledger.dat > x +$ mv x ledger.dat +$ rm equity.dat +@end example + +Now the balances reported from @samp{ledger.dat} are identical to what +they were before the data was split. + +How often should you split your ledger? You never need to, if you +don't want to. Even eighty years of data will not slow down ledger +much---and that's just using present day hardware! Or, you can keep +the previous and current year in one file, and each year before that +in its own file. It's really up to you, and how you want to organize +your finances. For those who also keep an accurate paper trail, it +might be useful to archive the older years to their own files, then +burn those files to a CD to keep with the paper records---along with +any electronic statements received during the year. In the arena of +organization, just keep in mind this maxim: Do whatever keeps you +doing it. + +@node Virtual transactions, Automated transactions, Archiving previous years, Keeping a ledger +@section Virtual transactions + +A virtual transaction is when you, in your mind, see money as moving +to a certain place, when in reality that money has not moved at all. +There are several scenarios in which this type of tracking comes in +handy, and each of them will be discussed in detail. + +To enter a virtual transaction, surround the account name in +parentheses. This form of usage does not need to balance. However, +if you want to ensure the virtual transaction balances with other +virtual transactions in the same entry, use square brackets. For +example: + +@example +10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + (Debt:Alimony) $200.00 +@end example + +In this example, after receiving a paycheck an alimony debt is +increased---even though no money has moved around yet. + +@example +10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + [Savings:Trip] $200.00 + [Assets:Checking] $-200.00 +@end example + +In this example, $200 has been deducted from checking toward savings +for a trip. It will appear as though the money has been moved from +the account into ``Savings:Trip'', although no money has actually moved +anywhere. + +When balances are displayed, virtual transactions will be factored in. +To view balances without any virtual balances factored in, using the +``-R'' flag, for ``Reality''. + +Write about: Saving for a Special Occasion; Keeping a Budget; Tracking +Allocated Funds. + +@node Automated transactions, Differences to Accounting Conventions, Virtual transactions, Keeping a ledger +@section Automated transactions + +As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. +The exact details of this are a bit complex, so if you have further +interest, please consult the Web. + +For any fellow Bahá'ís out there who want to track Huqúqu'lláh, the +Ledger tool makes this extremely easy. Just set up the following +automated transaction at the top of your ledger file: + +@example +; These entries will compute Huqúqu'lláh based on the +; contents of the ledger. + += ^Income: += ^Expenses:Rent$ += ^Expenses:Furnishings += ^Expenses:Business += ^Expenses:Taxes += ^Expenses:Insurance + (Liabilities:Huqúqu'lláh) 0.19 +@end example + +This automated transaction works by looking at each transaction +appearing afterward in the ledger file. If any match the account +regexps, occurring after the equal signs above, 19% of the value of +that transaction is applied to the ``Liabilities:Huqúqu'lláh'' account. +So if $1000 is earned through Income:Salary, which is seen as a debit +from Income, a debit of $190 is applied to ``Liabilities:Huqúqu'lláh''; +if $1000 is spent on Rent---seen as a credit to the Expense account---a credit of $190 is applied to Huqúqu'lláh. The ultimate balance +of Huqúqu'lláh reflects how much must be paid to that account in order +to balance it to zero. + +When you're ready to pay, just write a check directly to the account +``Liabilities:Huqúqu'lláh'': + +@example +2003/01/01 (101) Baha'i Huqúqu'lláh Trust + Liabilities:Huqúqu'lláh $1,000.00 + Assets:Checking +@end example + +That's it. To see how much Huqúq is currently owed based on your +ledger entries, use: + +@example +ledger balance Liabilities:Huqúq +@end example + + +@node Differences to Accounting Conventions, Using Emacs to Keep Your Ledger, Automated transactions, Keeping a ledger +@section Differences to Accounting Conventions +If you are an accountant, or you are familiar with accounting +terminology, then you might be tearing your hair out after reading the +above. Please don't! + +Ledger is intended to make people comfortable with their finances; to +help them better control the flow of their money. Contemporary +accounting practices, on the other hand, often seem counter-intuitive +and confusing to the layman. To make Ledger more accessible, it +avoids the use of standard accounting conventions and terminology. +However, Ledger is flexible enough that you may interpret what is +happening however you wish. + +Most probably, the following section will confuse you, and you should +skip it if you've managed to understand everything so far. However, +if you intend to communicate your accounting practices to a +professional accountant, the following explanations may be useful. + +@table @strong +@item The entity +The individual or organisation under consideration: the someone or +something on whose behalf you are accounting. Probably you. + +@item Assets +Future economic benefits controlled by the entity as a result of a +past transaction or event. + +@item Liabilities +Future sacrifices of economic benefits that the entity is obliged to +make as a result of a past transaction or event. + +@end table + +The format of the data files used by Ledger is more akin to a general +journal than a ledger. In an accounting ledger, transactions are +grouped by account. In a general journal, transactions are commonly +listed in chronological order. + +Often ``cash'' is used to refer to a liquid savings account at a bank, +rather than the physical notes and coins you may withdraw. + +In general, an ``addition'' in Ledger is an accounting debit, and a +``subtraction'' in Ledger is an accounting credit. The following table +shows the ``normal'' balances for the different types of accounts. +Accountants avoid using negative balances where possible, instead +prefering a positive amount in ``credit'' balance. + +@multitable @columnfractions 0.2 0.2 0.2 0.2 0.2 +@item System @tab Asset @tab Liability @tab Income @tab Expense +@item @strong{Accounting} @tab debit @tab credit @tab credit @tab debit +@item @strong{Ledger} @tab positive @tab negative @tab negative @tab positive +@end multitable + +That's correct: accountants call an addition to their cash a debit! +However, from the bank's perspective it is a credit: the accountant's +cash is a liability for the bank. Consequently, payments to the +account will show up as credits on his bank statement. + +@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Differences to Accounting Conventions, Keeping a ledger +@section Using Emacs to Keep Your Ledger + +In the Ledger tarball is an Emacs module, @samp{ledger.el}. This module +makes the process of keeping a text ledger much easier for Emacs +users. I recommend putting this at the top of your ledger file: + +@example +; -*-ledger-*- +@end example + +And this in your @samp{.emacs} file, after copying @samp{ledger.el} to your +site-lisp directory: + +@example +(load "ledger") +@end example + +Now when you edit your ledger file, it will be in @samp{ledger-mode}. +@samp{ledger-mode} adds the following commands: + +@table @strong +@item C-c C-a +For quickly adding new entries based on the form of older ones +(see previous section). + +@item C-c C-c +Toggles the ``cleared'' flag of the transaction under point. + +@item C-c C-r +Reconciles an account by displaying the transactions in another +buffer, where simply hitting the spacebar will toggle the cleared +flag of the transaction in the ledger. It also displays the current +cleared balance for the account in the modeline. + +@end table + +@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Keeping a ledger +@section Using GnuCash to Keep Your Ledger + +The Ledger tool is fast and simple, but it offers no custom method for +actually editing the ledger. It assumes you know how to use a text +editor, and like doing so. Perhaps an Emacs mode will appear someday +soon to make editing Ledger's data files much easier. + +Until then, you are free to use GnuCash to maintain your ledger, and +the Ledger program for querying and reporting on the contents +of that ledger. It takes a little longer to parse the XML data format +that GnuCash uses, but the end result is identical. + +Then again, why would anyone use a Gnome-centric, 35 megabyte behemoth +to edit their data, and a 65 kilobyte binary to query it... + +@node Using timeclock to record billable time, , Using GnuCash to Keep Your Ledger, Keeping a ledger +@section Using timeclock to record billable time + +The timeclock tool makes it easy to track time events, like clocking +into and out of a particular job. These events accumulate in a +timelog file. + +Each in/out event may have an optional description. If the ``in'' +description is a ledger account name, these in/out pairs may be viewed +as virtual transactions, adding time commodities (hours) to that +account. + +For example, the command-line version of the timeclock tool (which is +written in Python) could be used to begin a timelog file like: + +@example +$ export TIMELOG=$HOME/.timelog +$ ti ClientOne category +$ sleep 10 +$ to waited for ten seconds +@end example + +The @strong{.timelog} file now contains: + +@example +i 2004/10/06 15:21:00 ClientOne category +o 2004/10/06 15:21:10 waited for ten seconds +@end example + +Ledger can parse this directly, as if it had seen the following ledger +entry: + +@example +2004/10/06 category + (ClientOne) 0.00277h +@end example + +In other words, the timelog event pair is seen as adding 0.00277h (ten +seconds) worth of time to the ClientOne account. This would be +considered billable time, which later could be invoiced and credited +to accounts receivable: + +@example +2004/11/01 (INV#1) ClientOne, Inc. + Receivable:ClientOne $0.10 + ClientOne -0.00277h @@ $35.00 +@end example + +The above transaction converts the clocked time into an invoice for +the time spent, at an hourly rate of $35. Once the invoice is paid, +the money is deposited from the receivable account into a checking +account: + +@example +2004/12/01 ClientOne, Inc. + Assets:Checking $0.10 + Receivable:ClientOne +@end example + +And now the time spent has been turned into hard cash in the checking +account. + +The advantage to using timeclock and invoicing to bill time is that +you will always know, by looking at the balance report, exactly how +much unbilled and unpaid time you've spent working for any particular +client. + +I like to @samp{!include} my timelog at the top of my company's accounting +ledger, with the attached prefix ``Billable'': + +@example +; -*-ledger-*- + +; This is the ledger file for my company. But first, include the +; timelog data, entering all of the time events within the umbrella +; account "Billable". + +!include /home/johnw/.timelog Billable + +; Here follows this fiscal year's transactions for the company. + +2004/11/01 (INV#1) ClientOne, Inc. + Receivable:ClientOne $0.10 + Billable:ClientOne -0.00277h @@ $35.00 + +2004/12/01 ClientOne, Inc. + Assets:Checking $0.10 + Receivable:ClientOne +@end example + +@node Running Ledger, , Keeping a ledger, Top +@chapter Running Ledger + +@menu +* Commands:: +* Options:: +* Format strings:: +* Value expressions:: +* Interval expressions:: +* Plotting register data:: +* Typical queries:: +* File format:: +* Command summary:: +* Using command options:: +@end menu + +@node Commands, Options, Running Ledger, Running Ledger +@section Commands + +@node Options, Format strings, Commands, Running Ledger +@section Options + +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +the option has a long option named @samp{--this-option}, then setting +the environment variable @samp{LEDGER_THIS_OPTION} will have the same +affect. Options on the command-line always take precedence over +environment variable settings. + +@node Format strings, Value expressions, Options, Running Ledger +@section Format strings + +@node Value expressions, Interval expressions, Format strings, Running Ledger +@section Value expressions + +A value expression is a language used by ledger wherever a value is +involved. Some examples are: + +@itemize +@item Values displayed in reports +@item Predicates, or which transactions get calculated/displayed +@item Sorting criteria, or how transactions are sorted +@end itemize + +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. Here are some value expression +examples: + +@example +t = the transaction's value + +MT = the average total + +t*3+T = three times the amount plus the total + +At>@{$100@}?t:T = if the absolute value of the amount + is in dollars, and greater than $100, use the amount, + otherwise use the total. + +d<N&t+T = if the date is less than today, use the + amount plus the total, otherwise zero. +@end example + +@subsection Variables + +Below are the one letter variables available in any value expression: + +@table @asis +@item a +The transaction's amount; the balance of an account, without +considering children. + +@item B +The balance before the current transaction, which is the same as +@samp{O-a}; the subtotal of an account's children. + +@item C +The total cost of all transactions seen so far; the total cost of an +account and all its children. + +@item c +The cost of a transaction; the cost of an account, without its +children. + +@item d +A transaction's date, as the number of seconds past the epoch. This +is zero for an account. + +@item G +The total net gain (market value minus cost basis), for a series of +transactions, or an account and its children. It is the same as +@samp{V-C}. + +@item g +The net gain (market value minus cost basis), for a transaction or an +account without its children. It is the same as @samp{v-c}. + +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. + +@item N +The present date. + +@item n +The index of a transaction, or the count of transactions affecting an +account (including children). + +@item O +The total of all transactions seen so far, or the total of an account +and all its children. + +@item R +The value one, if a transaction is not virtual. + +@item T +This maps to whatever the user specified using @samp{-T}. + +@item t +This maps to whatever the user specified using @samp{-t}. + +@item V +The market value of all transactions seen so far, or of an account and +all its children. + +@item v +The market value of a transaction, or an account without its children. + +@item X +The value one, if a transaction's entry has been cleared. +@end table + +@subsection Functions + +The available one letter functions are: + +@table @asis +@item - +Negates the argument. + +@item A +The absolute value of the argument. + +@item S +Strips the commodity from the argument. + +@item M +The median of the argument; @samp{Mx} is the same as @samp{x/n}. + +@item D +The deviation of the argument; @samp{Dx} is the same as @samp{x-x/n}. + +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. +@end table + +@subsection Operators + +The binary and ternary operators, in order of precedence, are: + +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate + +@subsection Complex expressions + +More complicated expressions are possible using: + +@table @asis +@item NUM +A plain integer represents a commodity-less amount. + +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. + +@item /REGEXP/ +A regular expression that matches against an account's full name. If +a transaction, this will match against the account affected by the +transaction. + +@item //REGEXP/ +A regular expression that matches against an entry's payee name. + +@item ///REGEXP/ +A regular expression that matches against an account's base name. If +a transaction, this will match against the account affected by the +transaction. + +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. + +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table + +@node Interval expressions, Plotting register data, Value expressions, Running Ledger +@section Interval expressions + +@node Plotting register data, Typical queries, Interval expressions, Running Ledger +@section Plotting register data + +@node Typical queries, File format, Plotting register data, Running Ledger +@section Typical queries + +Once you have an orderly and well-organized general ledger, the next +step is to generate orderly and well-organized reports. This is where +the Ledger command-line tool comes in. With it, you can balance your +checkbook, see where your money is going, tell whether you've made a +profit this year, and compute the present value of your retirement +accounts. And all with the simplest of interfaces, the command-line. + +The most often used command will be the ``balance'' command: + +@example +export LEDGER=/home/johnw/doc/ledger.dat +ledger balance +@end example + +Here I've set my Ledger environment variable to point to where my +ledger file is hiding. Thereafter, I needn't specify it again. + +The balance command prints out the summarized balances of all my +top-level accounts, excluding sub-accounts. In order to see the +balances for a specific account, just specify a regular expression +after the balance command: + +@example +ledger balance expenses:food +@end example + +This will show all the money that's been spent on food, since the +beginning of the ledger. For food spending just this month +(September), use: + +@example +ledger -d sep balance expenses:food +@end example + +Or maybe I want to see all of my assets, in which case the -s (show +sub-accounts) option comes in handy: + +@example +ledger balance -s +@end example + +To exclude a particular account, use a regular expression with a +leading minus sign. The following will show all expenses, but without +food spending: + +@example +ledger balance expenses -food +@end example + +If you want to show all accounts but for one account, remember to use +``--'' to separate the exclusion pattern from the options list: + +@example +ledger balance -- -equity +@end example + +@node File format, Command summary, Typical queries, Running Ledger +@section File format + +The ledger file format is quite simple, but supports many options. +These are summarized here. + +The initial character of each line determines what that line means, +and how it should be parsed. The possibilities are: + +@table @strong +@item NUMBER +A line starting with a number denotes a regular ledger entry. It +may be followed by any number of lines that beginning whitespace, to +denote account transactions. The format of the header line is: +@example +DATE [*] [(CODE)] DESC +@end example + +@item + +If a line begins with plus, it denotes an inclusion regexp that +will always be considered, as if it had been specified by the user +at the end of their command-line. + +@item @strong{-} +If a line begins with minus, it denotes an exclusion regexp that +will always be considered, as if it had been specified by the user +at the end of their command-line. + +@item @strong{=} +If a line begins with equals, it denotes an automated transaction. +The next item on the line must be a regular expression. Any number +of such lines may appear, with no intervening whitespace. +Following this block of lines can be a list of account transactions +preceded by whitespace. + +@item !WORD +A line beginning with an exclamation mark denotes a command +directive. It must be immediately followed by a word specifying +which directories. At the moment, only @samp{!include} is supported, for +including the content of other ledger files into the current one. + +@item whitespace +A line beginning with whitespace, which is not part of a regular or +automated transaction, is ignored. + +@end table + +@quotation +If a line begins with semicolon it is ignored. This is the +preferred method of entering comments. +@end quotation + +@table @strong +@item Y NUM +If a line begins with a capital Y, it denotes the year to be used +for all subsequent entries that specify a date, whatever their type. +This sets the ``default year'', which ordinarily is the current year +at the time the program is run. Useful at the beginning of a file +to specify the file's year. + +@item P DATE SYMBOL PRICE +Capital P specifies a historical price for a commodity. Any such +number of entries are allowed. These are usually found in a pricing +history file (see the @samp{-Q} option). + +@item C SYMBOL PRICE +Capital C specifies a conversion price for a commodity. This has +no reference to time, and always takes precedence over any +historical price (even very current prices). + +@item N SYMBOL +Capital N indicates that no implicit price conversions should be +obtained for the given symbol. This means that no quotes will ever +be downloaded for that symbol. Useful for a home currency, such as +the dollar ($). Be aware that these pricing options will set the +default reporting characteristics for a commodity. Thus it is +recommended that pricing options occur only after all regular ledger +entries have been parsed. + +@item i DATE TIME ACCOUNT [DESC] +Lowercase (and capital) i indicate an time-in event. This will +start accumulating hours in the account specified. Usually these +entries are created in a timelog file by the timeclock program, +which is distributed with ledger. There must be two spaces between +the account name, and the optional description, if one is used. + +@item o DATE TIME ACCOUNT [DESC] +Lowercase (and capital) o indicate an time-out event. This will +accumulate hours in the account specified. Usually these entries +are created in a timelog file by the timeclock program, which is +distributed with ledger. There must be two spaces between the +account name, and the optional description, if one is used. + +@item b, h +Entries beginning with lowercase b and h are ignored. These are +special entries used by timeclock, but ignored by ledger. + +@end table + +@node Command summary, Using command options, File format, Running Ledger +@section Command summary + +@menu +* balance:: +* register:: +* print:: +* equity:: +* price:: +* entry:: +@end menu + +@node balance, register, Command summary, Command summary +@subsection balance + +The ``balance'' command reports the current balance of any account. +This command accepts a list of optional regexps, which will confine +the balance report to only matching accounts. By default, the +balances for all accounts will be printed. If an account contains +multiple types of commodities, each commodity's total is separately +reported. + +@node register, print, balance, Command summary +@subsection register + +The ``register'' command displays all the transactions occurring in a +single account, line by line. The account regexp must be specified as +the only argument to this command. If any regexps occur after the +required account name, the register will contain only those +transactions that match. Very useful for hunting down a particular +transaction. + +The output from ``register'' is very close to what a typical checkbook, +or single account ledger, would look like. It also shows a running +balance. The final running balance of any register should always be +the same as the current balance of that account. + +@node print, equity, register, Command summary +@subsection print + +The ``print'' command prints out ledger entries just as they appear in +the original ledger. They will be properly formatted, and output in +the most economic form possible. The ``print'' command also takes a +list of optional regexps, which will cause only those transactions +which match in some way to be printed. + +The ``print'' command is a handy way to clean up a ledger file whose +formatting has gotten out of hand. + +@node equity, price, print, Command summary +@subsection equity + +Equity transactions are used to establish the starting value of an +account. You might think of equity as the ``ether'' from which initial +balances appear. + +@node price, entry, equity, Command summary +@subsection price + +This commands displays the last known current price for a given +commodity, using the specified end date for the cutoff (default is the +present moment). It takes a list of regexps, which can match the +commodities used in the ledger file. This command is helpful to +quickly seeing the last current price for a specific commodity, or all +commodities referenced by a ledger. + +@node entry, , price, Command summary +@subsection entry + +The three most laborious tasks of keeping a ledger are: adding new +entries, reconciling accounts, and generating reports. To address the +first of these, there is a sub-command to ledger called ``entry''. It +works on the principle that 80% of all transactions are variants of +earlier transactions. Here's how it works: + +Let's say you have an old transaction of the following form: + +@example +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end example + +Now it's 2004/4/9, and you've just eating at Viva Italiano again. The +exact amounts are different, but the overall form is the same. With +the ``entry'' command you can type: + +@example +ledger entry 2004/4/9 viva food 11.00 tips 2.50 +@end example + +This will produce the following output: + +@example +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end example + +This works by finding a transaction that matches the regexp ``viva'', +and then assuming that any accounts or amounts you specify will be the +same as that earlier transaction. If Ledger does not succeed in +generating a new entry for you, it will print an error and set the +exit code to 1. + +There is a shell script in the distribution called ``entry'', which +simplifies the task of adding a new entry to your ledger, and then +launches @samp{vi} to let you confirm that the entry looks appropriate. + +@node Using command options, , Command summary, Running Ledger +@section Using command options + +With all of the commands, various command-line options are allowed +that will modify the behavior of the command in some way. And while +the basic commands themselves are useful, you will often find +yourselves adding option flags to the command-line to modify those +commands. + +The command-line options always occur before the command word. This +is done to distinguish them from the matching expressions that always +occur after the command word. The basic form of any command is: + +@example +ledger [OPTIONS] COMMAND [MATCH] +@end example + +Both the OPTIONS and MATCH expressions are optional. You could, for +example, just use ``ledger balance'' without any modification. This +would print the summarized total of all account types. But to get +more specific reporting, or to change the way the output looks, you +must use the options. + +@menu +* Basic options:: +* Filtering options:: +* Output formatting options:: +* Commodity reporting options:: +@end menu + +@node Basic options, Filtering options, Using command options, Using command options +@subsection Basic options + +The @samp{--help} (@samp{-h}) option causes ledger to print 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. + +@samp{--version} (@samp{-v}) prints the current version of ledger and exits. +This is useful for sending bug reports (to @email{johnw@@newartisans.com}), to +let the author know which version of ledger you are using. + +@samp{--init FILE} (@samp{-i FILE}) causes FILE to be read by ledger before any +other ledger file. This file may not contain any transactions, but it +may contain option settings. To specify options in the init file, use +the same syntax as the command-line. Here's an example init file: + +@example +--price-db ~/finance/.pricedb +@end example + +Option settings on the command-line or in the environment always take +precedence over settings in the init file. + +@samp{--file FILE} (@samp{-f FILE}) reads FILE as a ledger file. This command +may be used multiple times. FILE may also be a list of file names +separated by colons. Typically, the environment variable +@samp{LEDGER_FILE} is set, rather than using this command-line option. + +@samp{--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 @samp{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 @samp{LEDGER_CACHE}, or by putting the option into +your init file. + +@samp{--output FILE} (@samp{-o FILE}) redirects output from any command to +@samp{FILE}. By default, all output goes to standard output. + +@node Filtering options, Output formatting options, Basic options, Using command options +@subsection Filtering options + +@table @strong +@item @strong{-b DATE} +Only consider entries occuring on or after the given date. + +@item @strong{-e DATE} +Only consider entries occuring before the given date. The date is +not inclusive, so any entries occurring on that date will not be +used. + +@item @strong{-c} +Only consider entries occurring on or before the current date. + +@item @strong{-d DATE} +Only consider entries fitting the given date mask. DATE in this +case may be the name of a month, or a year, or a year and month, +such as ``2004/05''. It's a shorthand for having to specify -b and -e +together. + +@item @strong{-C} +Only consider entries whose cleared flag has been set. The default +is to consider both. + +@item @strong{-U} +Show only uncleared transactions. The default is to consider both. + +@item @strong{-l AMT} +Limit balance reports to those which are greater than AMT. + +@item @strong{-N REGEXP} +If an account matches REGEXP, only display it in the balance report +if its total is negative. Useful to avoid seeing credit in accounts +where one cannot spend that credit, and it will soon become negative +anyway (such as credit cards). + +@item @strong{-R} +Ignore all virtual transactions, and report only the real balance +for each account. + +@end table + +@node Output formatting options, Commodity reporting options, Filtering options, Using command options +@subsection Output formatting options + +@table @strong +@item @strong{-n} +Do not show subtotals in the balance report, or split transactions +in the register report. + +@item @strong{-s} +If an account has children, show them in the balance report. + +@item @strong{-S} +Sort the ledger after reading it. This may affect ``register'' and +``print'' output. + +@item @strong{-E} +Also show empty accounts in the balance totals report. + +@item @strong{-F} +Print full account names in all cases, such as ``Assets:Checking'' +instead of just ``Checking''. Only used current by the ``balance'' +command. + +@item @strong{-M} +When used with the ``register'' command, causes only monthly subtotals +to appear. This can be useful for looking at spending patterns. +TODO: Accept an argument specifying the period to use. + +@item @strong{-A} +Report totals in terms of the arithmetic mean (sum of all items +divided by the count). This does not work when multiple commodities +are used in the same account, in which case this option is ignored. +This option works both for balance reports, and for register reports +(where it displays the running total average). Be aware that in the +balance report, parent account totals reflect the arithmetic mean of +all the transactions---not the mean average of the subaccount +totals. + +@item @strong{-T} +Report totals in terms of the average deviation from the average +value (i.e., the trend). The final total will indicate the amount +over or above the average value which it is expected you will next +spend/earn. When spending is regular, the trend will very slowly +move to zero. + +@item @strong{-X} +Report totals in terms of the expected value of the next +transaction. This is determined by adding the average deviation to +the average value. + +@item @strong{-W} +Report totals in terms of a time-weighted trend. Whereas @samp{-T} +reports the exact value trend irrespective of when the transactions +occurred, @samp{-W} takes into account the time between entries. If a +transaction occurs shortly after another, it will not affect the +running trend as much as if it occurs very much later. This style +of reports always adds a null transaction for the current date, so +that a current lack of spending is taken into account. + +@end table + +@node Commodity reporting options, , Output formatting options, Using command options +@subsection Commodity reporting options + +@table @strong +@item @strong{-P FILE} +With this option, or if the environment variable @samp{PRICE_HIST} is +set, pricing information obtained from the Internet will be kept +in this file. Also, this file will be read after all other ledger +files are read, so that full history information is available for +reports. + +@item @strong{-O} +Report commodity totals only, not their market value or basis cost. + +@item @strong{-V} +Report commodity values in terms of their last known market price. + +@item @strong{-B} +Report commodities in terms of their ``basis cost'', or what they cost +at time of purchase. Thus, totals in the register and balance +report reflect the total amount spent. + +@item @strong{-G} +Report commodities in terms of their net gain, which is: the market +value minus the cost basis. A balance report using this option +shows very quickly the performance of investments. + +@item @strong{-Q} +When needed (see the @samp{-L} option) pricing quotes are obtained by +calling the script @samp{getquote} (a sample Perl script is provided, but +the interface is kept simple so replacements may be made). + +@item @strong{-L MINS} +When using the @samp{-Q} flag, new quotes are obtained only if current +pricing data is older than MINS minutes. The default is one day, +or 1440 minutes. + +@item @strong{-p ARG} +If a string, such as ``COMM=$1.20'', the commodity COMM will be +reported only in terms of the conversion factor, which supersedes +all other pricing histories for that commodity. This can be used to +perform arbitrary value substitutions. For example, to report the +value of your dollars in terms of the ounces of gold they would buy, +use: -p ``$=0.00280112 AU'' (or whatever the current exchange rate +is). + +@end table + + +@c Page published by Emacs Muse ends here +@contents +@bye |