--- ledger-2.6.2.orig/ledger.el +++ ledger-2.6.2/ledger.el @@ -480,7 +480,7 @@ (account ledger-acct) (inhibit-read-only t) cleared) - (when (equal (car where) "") + (when (equal (car where) "/dev/stdin") (with-current-buffer ledger-buf (goto-char (cdr where)) (setq cleared (ledger-toggle-current 'pending))) @@ -553,7 +553,7 @@ (defun ledger-reconcile-delete () (interactive) (let ((where (get-text-property (point) 'where))) - (when (equal (car where) "") + (when (equal (car where) "/dev/stdin") (with-current-buffer ledger-buf (goto-char (cdr where)) (ledger-delete-current-entry)) @@ -565,7 +565,7 @@ (defun ledger-reconcile-visit () (interactive) (let ((where (get-text-property (point) 'where))) - (when (equal (car where) "") + (when (equal (car where) "/dev/stdin") (switch-to-buffer-other-window ledger-buf) (goto-char (cdr where))))) @@ -588,7 +588,7 @@ (let ((where (get-text-property (point) 'where)) (face (get-text-property (point) 'face))) (if (and (eq face 'bold) - (equal (car where) "")) + (equal (car where) "/dev/stdin")) (with-current-buffer ledger-buf (goto-char (cdr where)) (ledger-toggle-current 'cleared)))) --- ledger-2.6.2.orig/option.cc +++ ledger-2.6.2/option.cc @@ -892,7 +892,7 @@ namespace { void parse_price_setting(const char * optarg) { - char * equals = std::strchr(optarg, '='); + const char * equals = std::strchr(optarg, '='); if (! equals) return; --- ledger-2.6.2.orig/textual.cc +++ ledger-2.6.2/textual.cc @@ -298,8 +298,8 @@ DEBUG_PRINT("ledger.textual.parse", "line " << linenum << ": " << "Parsed a note '" << xact->note << "'"); - if (char * b = std::strchr(xact->note.c_str(), '[')) - if (char * e = std::strchr(xact->note.c_str(), ']')) { + if (const char * b = std::strchr(xact->note.c_str(), '[')) + if (const char * e = std::strchr(xact->note.c_str(), ']')) { char buf[256]; std::strncpy(buf, b + 1, e - b - 1); buf[e - b - 1] = '\0'; --- ledger-2.6.2.orig/ledger.texi +++ ledger-2.6.2/ledger.texi @@ -1554,8 +1554,7 @@ know which version of ledger you are using. @option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. -This command may be used multiple times. FILE may also be a list of -file names separated by colons. Typically, the environment variable +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 @@ -1565,11 +1564,12 @@ @option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by ledger before any other ledger file. This file may not contain any transactions, but it may contain option settings. To specify options -in the init file, use the same syntax as the command-line. Here's an -example init file: +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 +--pager /usr/bin/less ; ~/.ledgerrc ends here @end smallexample @@ -1578,7 +1578,7 @@ 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 +file. That is, if the ledger file to be read is 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 @@ -1888,6 +1888,7 @@ @example --cache /tmp/.mycache +--pager /usr/bin/less @end example @node Format strings, Value expressions, Options, Running Ledger --- ledger-2.6.2.orig/utf8 +++ ledger-2.6.2/utf8 @@ -0,0 +1,3644 @@ +This is ledger.info, produced by makeinfo version 4.13 from ledger.texi. + +INFO-DIR-SECTION User Applications + Copyright (c) 2003-2009, 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. + +START-INFO-DIR-ENTRY +* Ledger: (ledger). Command Line Accounting +END-INFO-DIR-ENTRY + + +File: ledger.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Overview +******** + +Copyright (c) 2003-2009, 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. + +* Menu: + +* Introduction:: +* Running Ledger:: +* Keeping a ledger:: +* Using XML:: + + +File: ledger.info, Node: Introduction, Next: Running Ledger, Prev: Top, Up: Top + +1 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. _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: + + 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 $23.00 + Checking $-23.00 + + The first line shows a payment to Pacific Bell for $23.00. Because +there is no "balance" in a general ledger--it's always zero--we write +in the total balance of all payments to "Pacific Bell", which now is +$223.00 (previously the balance was $200.00). This is done by looking +at the last entry for "Pacific Bell" in the ledger, adding $23.00 to +that amount, and writing the total in the balance column. And the +money came from "Checking"--a withdrawal of $23.00--which leaves the +ending balance in "Checking" at $77.00. This is a very manual +procedure; but that's where computers come in... + + The transaction must balance to $0: $23 went to Pacific Bell, $23 +came from Checking. There is nothing left over to be accounted for, +since the money has simply moved from one account to another. This is +the basis of double-entry accounting: that money never pops in or out of +existence; it is always a transaction from one account to another. + + Keeping a general ledger is the same as keeping two separate ledgers: +One for Pacific Bell and one for Checking. In that case, each time a +payment is written into one, you write a corresponding withdrawal into +the other. This makes it easier to write in a "running balance", since +you don't have to look back at the last time the account was +referenced--but it also means having a lot of ledger books, if you deal +with multiple accounts. + + Enter the beauty of computerized accounting. The purpose of the +Ledger program is to make general ledger accounting simple, by keeping +track of the balances for you. Your only job is to enter the +transactions. If a transaction does not balance, Ledger displays an +error and indicates the incorrect transaction.(1) + + 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: + + 2004/09/29 Pacific Bell + Payable:Pacific Bell $-200.00 + Equity:Opening Balances + + 2004/09/29 Checking + Accounts:Checking $100.00 + Equity:Opening Balances + + 2004/09/29 Pacific Bell + Payable:Pacific Bell $23.00 + Accounts:Checking + + The account balances and registers in this file, if saved as +`ledger.dat', could be reported using: + + $ ledger -f ledger.dat balance + $ ledger -f ledger.dat register checking + $ ledger -f ledger.dat register bell + +* Menu: + +* Building the program:: +* Getting help:: + + ---------- Footnotes ---------- + + (1) In some special cases, it automatically balances this entry for +you. + + +File: ledger.info, Node: Building the program, Next: Getting help, Prev: Introduction, Up: Introduction + +1.1 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: + + ./configure && make install + + +File: ledger.info, Node: Getting help, Prev: Building the program, Up: Introduction + +1.2 Getting help +================ + +If you need help on how to use Ledger, or run into problems, you can +just the Ledger mailing list at the following Web address: + + https://lists.sourceforge.net/lists/listinfo/ledger-discuss + + You can also find help at the `#ledger' channel on the IRC server +`irc.freenode.net'. + + +File: ledger.info, Node: Running Ledger, Next: Keeping a ledger, Prev: Introduction, Up: Top + +2 Running Ledger +**************** + +Ledger has a very simple command-line interface, named--enticing +enough--`ledger'. It supports a few reporting commands, and a large +number of options for refining the output from those commands. The +basic syntax of any ledger command is: + + ledger [OPTIONS...] COMMAND [ARGS...] + + Command options must always precede the command word. After the +command word there may appear any number of arguments. For most +commands, these arguments are regular expressions that cause the output +to relate only to transactions matching those regular expressions. For +the `entry' command, the arguments have a special meaning, described +below. + + The regular expressions arguments always match the account name that +a transaction refers to. To match on the payee of the entry instead, +precede the regular expression with `--'. For example, the following +balance command reports account totals for rent, food and movies, but +only those whose payee matches Freddie: + + ledger bal rent food movies -- freddie + + There are many, many command options available with the `ledger' +command, and it takes a while to master them. However, none of them +are required to use the basic reporting commands. + +* Menu: + +* Usage overview:: +* Commands:: +* Options:: +* Format strings:: +* Value expressions:: +* Period expressions:: +* File format:: +* Some typical queries:: +* Budgeting and forecasting:: + + +File: ledger.info, Node: Usage overview, Next: Commands, Prev: Running Ledger, Up: Running Ledger + +2.1 Usage overview +================== + +Before getting into the details of how to run Ledger, it will be easier +to introduce the features in the context of their typical usage. To +that end, this section presents a series of recipes, gradually +introducing all of the command-line features of Ledger. + + For the purpose of these examples, assume the environment variable +LEDGER is set to the file `sample.dat' (which is included in the +distribution), and that the contents of that file are: + + = /^Expenses:Books/ + (Liabilities:Taxes) -0.10 + + ~ Monthly + Assets:Bank:Checking $500.00 + Income:Salary + + 2004/05/01 * Checking balance + Assets:Bank:Checking $1,000.00 + Equity:Opening Balances + + 2004/05/01 * Investment balance + Assets:Brokerage 50 AAPL @ $30.00 + Equity:Opening Balances + + 2004/05/14 * Pay day + Assets:Bank:Checking $500.00 + Income:Salary + + 2004/05/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard + + 2004/05/27 (100) Credit card company + Liabilities:MasterCard $20.00 + Assets:Bank:Checking + + This sample file demonstrates a basic principle of accounting which +it is recommended you follow: Keep all of your accounts under five +parent Assets, Liabilities, Income, Expenses and Equity. It is +important to do so in order to make sense out of the following examples. + +2.1.1 Checking balances +----------------------- + +Ledger has seven basic commands, but by far the most often used are +`balance' and `register'. To see a summary balance of all accounts, +use: + + ledger bal + + `bal' is a short-hand for `balance'. This command prints out the +summary totals of the five parent accounts used in `sample.dat': + + $1,480.00 + 50 AAPL Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income + $-2.00 Liabilities + -------------------- + $-1,502.00 + 50 AAPL + + None of the child accounts are shown, just the parent account totals. +We can see that in `Assets' there is $1,480.00, and 50 shares of Apple +stock. There is also a negative grand total. Usually the grand total +is zero, which means that all accounts balance(1). In this case, since +the 50 shares of Apple stock cost $1,500.00 dollars, then these two +amounts balance each other in the grand total. The extra $2.00 comes +from a virtual transaction being added by the automatic entry at the +top of the file. The entry is virtual because the account name was +surrounded by parentheses in an automatic entry. Automatic entries +will be discussed later, but first let's remove the virtual transaction +from the balance report by using the `--real' option: + + ledger --real bal + + Now the report is: + + $1,480.00 + 50 AAPL Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income + -------------------- + $-1,500.00 + 50 AAPL + + Since the liability was a virtual transaction, it has dropped from +the report and we see that final total is balanced. + + But we only know that it balances because `sample.dat' is quite +simple, and we happen to know that the 50 shares of Apple stock cost +$1,500.00. We can verify that things really balance by reporting the +Apple shares in terms of their cost, instead of their quantity. To do +this requires the `--basis', or `-B', option: + + ledger --real -B bal + + This command reports: + + $2,980.00 Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income + + With the basis cost option, the grand total has disappeared, as it is +now zero. The confirms that the cost of everything balances to zero, +_which must always be true_. Reporting the real basis cost should +never yield a remainder(2). + +2.1.1.1 Sub-account balances +............................ + +The totals reported by the balance command are only the topmost parent +accounts. To see the totals of all child accounts as well, use the +`-s' option: + + ledger --real -B -s bal + + This reports: + + $2,980.00 Assets + $1,480.00 Bank:Checking + $1,500.00 Brokerage + $-2,500.00 Equity:Opening Balances + $20.00 Expenses:Books + $-500.00 Income:Salary + + This shows that the `Assets' total is made up from two child +account, but that the total for each of the other accounts comes from +one child account. + + Sometimes you may have a lot of children, nested very deeply, but +only want to report the first two levels. This can be done with a +display predicate, using a value expression. In the value expression, +`T' represents the reported total, and `l' is the display level for the +account: + + ledger --real -B -d "T&l<=2" bal + + This reports: + + $2,980.00 Assets + $1,480.00 Bank + $1,500.00 Brokerage + $-2,500.00 Equity:Opening Balances + $20.00 Expenses:Books + $-500.00 Income:Salary + + Instead of reporting `Bank:Checking' as a child of `Assets', it +report only `Bank', since that account is a nesting level of 2, while +`Checking' is at level 3. + + To review the display predicate used--`T&l<=2'--this rather terse +expression means: Display an account only if it has a non-zero total +(`T'), and its nesting level is less than or equal to 2 (`l<=2'). + +2.1.1.2 Specific account balances +................................. + +While reporting the totals for all accounts can be useful, most often +you will want to check the balance of a specific account or accounts. +To do this, put one or more account names after the balance command. +Since these names are really regular expressions, you can use partial +names if you wish: + + ledger bal checking + + Reports: + + $1,480.00 Assets:Bank:Checking + + Any number of names may be used: + + ledger bal checking broker liab + + Reports: + + $1,480.00 Assets:Bank:Checking + 50 AAPL Assets:Brokerage + $-2.00 Liabilities + + In this case no grand total is reported, because you are asking for +specific account balances. + + For those comfortable with regular expressions, any Perl regexp is +allowed: + + ledger bal ^assets.*checking ^liab + + Reports: + + $1,480.00 Assets:Bank:Checking + $-2.00 Liabilities:Taxes + +2.1.2 The register report +------------------------- + +While the `balance' command can be very handy for checking account +totals, by far the most powerful of Ledger's reporting tools is the +`register' command. In fact, internally both commands use the same +logic, but report the results differently: `balance' shows the summary +totals, while `register' reports each transaction and how it +contributes to that total. + + Paradoxically, the most basic form of `register' is almost never +used, since it displays every transaction: + + ledger reg + + `reg' is a short-hand for `register'. This command reports: + + 2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + Equity:Opening Balan.. $-1,000.00 0 + 2004/05/01 Investment balance Assets:Brokerage 50 AAPL 50 AAPL + Equity:Opening Balan.. $-1,500.00 $-1,500.00 + 50 AAPL + 2004/05/14 Pay day Assets:Bank:Checking $500.00 $-1,000.00 + 50 AAPL + Income:Salary $-500.00 $-1,500.00 + 50 AAPL + 2004/05/27 Book Store Expenses:Books $20.00 $-1,480.00 + 50 AAPL + Liabilities:MasterCard $-20.00 $-1,500.00 + 50 AAPL + (Liabilities:Taxes) $-2.00 $-1,502.00 + 50 AAPL + 2004/05/27 Credit card company Liabilities:MasterCard $20.00 $-1,482.00 + 50 AAPL + Assets:Bank:Checking $-20.00 $-1,502.00 + 50 AAPL + + This rather verbose output shows every account transaction in +`sample.dat', and how it affects the running total. The final total is +identical to what we saw with the plain `balance' command. To see how +things really balance, we can use `--real -B', just as we did with +`balance': + + ledger --real -B reg + + Reports: + + 2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + Equity:Opening Balan.. $-1,000.00 0 + 2004/05/01 Investment balance Assets:Brokerage $1,500.00 $1,500.00 + Equity:Opening Balan.. $-1,500.00 0 + 2004/05/14 Pay day Assets:Bank:Checking $500.00 $500.00 + Income:Salary $-500.00 0 + 2004/05/27 Book Store Expenses:Books $20.00 $20.00 + Liabilities:MasterCard $-20.00 0 + 2004/05/27 Credit card company Liabilities:MasterCard $20.00 $20.00 + Assets:Bank:Checking $-20.00 0 + + Here we see that everything balances to zero in the end, as it must. + +2.1.2.1 Specific register queries +................................. + +The most common use of the register command is to summarize +transactions based on the account(s) they affect. Using `sample.dat' +as as example, we could look at all book purchases using: + + ledger reg books + + Reports: + + 2004/05/29 Book Store Expenses:Books $20.00 $20.00 + + If a double-dash (`--') occurs in the list of regular expressions, +any following arguments are matched against payee names, instead of +account names: + + ledger reg ^liab -- credit + + Reports: + + 2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00 + + There are many reporting options for tailoring which transactions are +found, and also how to summarize the various amounts and totals that +result. These are plumbed in greater depth below. + +2.1.3 Selecting transactions +---------------------------- + +Although the easiest way to use the register is to report all the +transactions affecting a set of accounts, it can often result in more +information than you want. To cope with an ever-growing amount of +data, there are several options which can help you pinpoint your report +to exactly the transactions that interest you most. This is called the +"calculation" phase of Ledger. All of its related options are +documented under `--help-calc'. + +2.1.3.1 By date +............... + +`--current'(`-c') displays entries occurring on or before the current +date. Any entry recorded for a future date will be ignored, as if it +had not been seen. This is useful if you happen to pre-record entries, +but still wish to view your balances in terms of what is available +today. + + `--begin DATE' (`-b DATE') limits the report to only those entries +occurring on or after DATE. The running total in the register will +start at zero with the first transaction, even if there are earlier +entries. + + To limit the display only, but still add earlier transactions to the +running total, use the display expression `-d 'd>=[DATE]''): + + ledger --basis -b may -d 'd>=[5/14]' reg ^assets + + Reports: + + 2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 + 2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 + + In this example, the displayed transactions start from `5/14', but +the calculated total starts from the beginning of `may'. + + `--end DATE' (`-e DATE') states when reporting should end, both +calculation and display. The ending date is inclusive. + + The DATE argument to the `-b' and `-e' options can be rather +flexible. Assuming the current date to be November 15, 2004, then all +of the following are equivalent: + + ledger -b oct bal + ledger -b "this oct" bal + ledger -b 2004/10 bal + ledger -b 10 bal + ledger -b last bal + ledger -b "last month" bal + + To constrain the report to a specific time period, use `--period' +(`-p'). A time period may have both a beginning and an end, or +neither, as well as a specified interval. Here are a few examples: + + ledger -p 2004 bal + ledger -p august bal + ledger -p "from aug to oct" bal + ledger -p "daily from 8/1 to 8/15" bal + ledger -p "weekly since august" bal + ledger -p "monthly from feb to oct" bal + ledger -p "quarterly in 2004" bal + ledger -p yearly bal + + See *note Period expressions:: for more on syntax. Also, all of the +options `-b', `-e' and `-p' may be used together, but whatever +information occurs last takes priority. An example of such usage (in a +script, perhaps) would be: + + ledger -b 2004 -e 2005 -p monthly reg ^expenses + + This command is identical to: + + ledger -p "monthly in 2004" reg ^expenses + + The transactions within a period may be sorted using +`--period-sort', which takes a value expression. This is similar to +the `--sort' option, except that it sorts within each period entry, +rather than sorting all transactions in the report. See the +documentation on `--sort' below for more details. + +2.1.3.2 By status +................. + +By default, all regular transactions are included in each report. To +limit the report to certain kinds of transactions, use one or more of +the following options: + +`-C, --cleared' + Consider only cleared transactions. + +`-U, --uncleared' + Consider only uncleared and pending transactions. + +`-R, --real' + Consider only real (non-virtual) transactions. + +`-L, --actual' + Consider only actual (non-automated) transactions. + + Cleared transactions are indicated by an asterix placed just before +the payee name in a transaction. The meaning of this flag is up to the +user, but typically it means that an entry has been seen on a financial +statement. Pending transactions use an exclamation mark in the same +position, but are mainly used only by reconciling software. Uncleared +transactions are for things like uncashed checks, credit charges that +haven't appeared on a statement yet, etc. + + Real transactions are all non-virtual transactions, where the account +name is not surrounded by parentheses or square brackets. Virtual +transactions are useful for showing a transfer of money that never +really happened, like money set aside for savings without actually +transferring it from the parent account. + + Actual transactions are those not generated, either as part of an +automated entry, or a budget or forecast report. A useful of when you +might like to filter out generated transactions is with a budget: + + ledger --budget --actual reg ^expenses + + This command outputs all transactions affecting a budgeted account, +but without subtracting the budget amount (because the generated +transactions are suppressed with `--actual'). The report shows how +much you actually spent on budgeted items. + +2.1.3.3 By relationship +....................... + +Normally, a register report includes only the transactions that match +the regular expressions specified after the command word. For example, +to report all expenses: + + ledger reg ^expenses + + This reports: + + 2004/05/29 Book Store Expenses:Books $20.00 $20.00 + + Using `--related' (`-r') reports the transactions that did not match +your query, but only in entries that otherwise would have matched. +This has the effect of indicating where money came from, or when to: + + ledger -r reg ^expenses + + Reports: + + 2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00 + +2.1.3.4 By budget +................. + +There is more information about budgeting and forecasting in *note +Budgeting and forecasting::. Basically, if you have any period entries +in your ledger file, you can use these options. A period entry looks +like: + + ~ Monthly + Assets:Bank:Checking $500.00 + Income:Salary + + The difference from a regular entry is that the first line begins +with a tilde (~), and instead of a payee there's a period expression +(*note Period expressions::). Otherwise, a period entry is in every +other way the same as a regular entry. + + With such an entry in your ledger file, the `--budget' option will +report only transactions that match a budgeted account. Using +`sample.dat' from above: + + ledger --budget reg ^income + + Reports: + + 2004/05/01 Budget entry Income:Salary $500.00 $500.00 + 2004/05/14 Pay day Income:Salary $-500.00 0 + + The final total is zero, indicating that the budget matched exactly +for the reported period. Budgeting is most often helpful with period +reporting; for example, to show monthly budget results use `--budget -p +monthly'. + + The `--add-budget' option reports all matching transactions in +addition to budget transactions; while `--unbudgeted' shows only those +that don't match a budgeted account. To summarize: + +`--budget' + Show transactions matching budgeted accounts. + +`--unbudgeted' + Show transactions matching unbudgeted accounts. + +`--add-budget' + Show both budgeted and unbudgeted transactions together (i.e., add + the generated budget transactions to the regular report). + + A report with the `--forecast' option will add budgeted transactions +while the specified value expression is true. For example: + + ledger --forecast 'd<[2005] reg ^income + + Reports: + + 2004/05/14 Pay day Income:Salary $-500.00 $-500.00 + 2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00 + 2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00 + + The date this report was made was November 5, 2004; the reason the +first forecast entry is in december is that forecast entries are only +added for the future, and they only stop after the value expression has +matched at least once, which is why the January entry appears. A +forecast report can be very useful for determining when money will run +out in an account, or for projecting future cash flow: + + ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp + + This reports balances projected income against projected expenses, +showing the resulting total in yearly intervals until 2008. For the +case of `sample.dat', which has no budgeted expenses, the result of the +above command (in November 2004) is: + + 2004/01/01 - 2004/12/31 Income:Salary $-1,000.00 $-1,000.00 + Expenses:Books $20.00 $-980.00 + 2005/01/01 - 2005/12/31 Income:Salary $-6,000.00 $-6,980.00 + 2006/01/01 - 2006/12/31 Income:Salary $-6,000.00 $-12,980.00 + 2007/01/01 - 2007/12/31 Income:Salary $-6,000.00 $-18,980.00 + 2008/01/01 - 2008/01/01 Income:Salary $-500.00 $-19,480.00 + +2.1.3.5 By value expression +........................... + +Value expressions can be quite complex, and are treated more fully in +*note Value expressions::. They can be used for limiting a report with +`--limit' (`-l'). The following command report income since august, +but expenses since october: + + ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg + + The basic form of this value expression is `(A&B)|(A&B)'. The `A' +in each part matches against an account name with `/name/', while each +`B' part compares the date of the transaction (`d') with a specified +month. The resulting report will contain only transactions which match +the value expression. + + Another use of value expressions is to calculate the amount reported +for each line of a register report, or for computing the subtotal of +each account shown in a balance report. This example divides each +transaction amount by two: + + ledger -t 'a/2' reg ^exp + + The `-t' option doesn't affect the running total, only how the +transaction amount is displayed. To change the running total, use +`-T'. In that case, you will likely want to use the total (`O') +instead of the amount (`a'): + + ledger -T 'O/2' reg ^exp + +2.1.4 Massaging register output +------------------------------- + +Even after filtering down your data to just the transactions you're +interested in, the default reporting method of one transaction per line +is often still too much. To combat this complexity, it is possible to +ask Ledger to report the details to you in many different forms, +summarized in various ways. This is the "display" phase of Ledger, and +is documented under `--help-disp'. + +2.1.4.1 Summarizing +................... + +When multiple transactions relate to a single entry, they are reported +as part of that entry. For example, in the case of `sample.dat': + + ledger reg -- book + + Reports: + + 2004/05/29 Book Store Expenses:Books $20.00 $20.00 + Liabilities:MasterCard $-20.00 0 + (Liabilities:Taxes) $-2.00 $-2.00 + + All three transactions are part of one entry, and as such the entry +details are printed only once. To report every entry on a single line, +use `-n' to collapse entries with multiple transactions: + + ledger -n reg -- book + + Reports: + + 2004/05/29 Book Store $-2.00 $-2.00 + + In the balance report, `-n' causes the grand total not to be +displayed at the bottom of the report. + + If an account occurs more than once in a report, it is possible to +combine them all and report the total per-account, using `-s'. For +example, this command: + + ledger -B reg ^assets + + Reports: + + 2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + 2004/05/01 Investment balance Assets:Brokerage $1,500.00 $2,500.00 + 2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 + 2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 + + But if the `-s' option is added, the result becomes: + + 2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00 + Assets:Brokerage $1,500.00 $2,980.00 + + When account subtotaling is used, only one entry is printed, and the +date and name reflect the range of the combined transactions. + + With `-P', transactions relating to the same payee are combined. In +this case, the date of the combined entry is that of the latest +transaction. + + `-x' changes the payee name for each transaction to be the same as +the commodity it uses. This can be especially useful combined with +other options, like `-P'. For example: + + ledger -Px reg ^assets + + Reports: + + 2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 + 2004/05/01 AAPL Assets:Brokerage 50 AAPL $1,480.00 + 50 AAPL + + This reports shows the subtotal for each commodity held, and where it +is located. To see the basis cost, or initial investment, add `-B'. +Applied to the example above: + + 2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 + 2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00 + + The only other options which affect summarized totals is `-E', which +works only in the balance report. In this case, it shows matching +accounts with a zero a balance, which are ordinarily excluded. This +can be useful to see all the accounts involved in a report, even if +some have no total. + +2.1.4.2 Quick periods +..................... + +Although the `-p' option (also `--period') is much more versatile, +there are other options to make the most common period reports easier: + +`-W, --weekly' + Show weekly sub-totals. Same as `-p weekly'. + +`-M, --monthly' + Show monthly sub-totals. Same as `-p monthly'. + +`-Y, --yearly' + Show yearly sub-totals. Same as `-p yearly'. + + There is one kind of period report cannot be done with `-p'. This +is the `--dow', or "days of the week" report, which shows summarized +totals for each day of the week. The following examples shows a "day +of the week" report of income and expenses: + + ledger --dow reg ^inc ^exp + + Reports: + + 2004/05/27 Thursdays Expenses:Books $20.00 $20.00 + 2004/05/14 Fridays Income:Salary $-500.00 $-480.00 + +2.1.4.3 Ordering and width +.......................... + +The transactions displayed in a report are shown in the same order as +they appear in the ledger file. To change the order and sort a report, +use the `--sort' option. `--sort' takes a value expression to +determine the value to sort against, making it possible to sort +according to complex criteria. Here are some simple and useful +examples: + + ledger --sort d reg ^exp # sort by date + ledger --sort t reg ^exp # sort by amount total + ledger --sort -t reg ^exp # reverse sort by amount total + ledger --sort Ut reg ^exp # sort by abs amount total + + For the balance report, you will want to use `T' instead of `t': + + ledger --sort T reg ^exp # sort by amount total + ledger --sort -T reg ^exp # reverse sort by amount total + ledger --sort UT reg ^exp # sort by abs amount total + + The `--sort' options sorts all transactions in a report. If periods +are used (such as `--monthly'), this can get somewhat confusing. In +that case, you'll probably want to sort within periods using +`--period-sort' instead of `--sort'. + + And if the register seems too cramped, and you have a lot of screen +real estate, you can use `-w' to format the report within 132 acolumns, +instead of 80. You are more likely then to see full payee and account +names, as well as properly formatted totals when long-named commodities +are used. + + If you want only the first or last N entries to be printed--which can +be very useful for viewing the last 10 entries in your checking +account, while also showing the cumulative balance from all +entries--use the `--head' and/or `--tail' options. The two options may +be used simultaneously, for example: + + ledger --tail 20 reg checking + + If the output from your command is very long, Ledger can output the +data to a pager utility, such as `more' or `less': + + ledger --pager /usr/bin/less reg checking + +2.1.4.4 Averages and percentages +................................ + +To see the running total changed to a running average, use `-A'. The +final transaction's total will be the overall average of all displayed +transactions. The works in conjunction with period reporting, so that +you can see your monthly average expenses with: + + ledger -AM reg ^expenses:food + ledger -AMn reg ^expenses + + This works in the balance report too: + + ledger -AM bal ^expenses:food + ledger -AMs bal ^expenses + + The `-D' option changes the running average into a deviation from +the running average. This only makes sense in the register report, +however. + + ledger -DM reg ^expenses:food + + In the balance report only, `-%' changes the reported totals into a +percentage of the parent account. This kind of report is confusing if +negative amounts are involved, and doesn't work at all if multiple +commodities occur in an account's history. It has a somewhat limited +usefulness, therefore, but in certain cases it can be handy, such as +reviewing overall expenses: + + ledger -%s -S T bal ^expenses + +2.1.4.5 Reporting total data +............................ + +Normally in the `xml' report, only transaction amounts are printed. To +include the running total under a `' tag, use `--totals'. This +does not affect any other report. + + In the register report only, the output can be changed with `-j' to +show only the date and the amount--without commodities. This only +makes sense if a single commodity appears in the report, but can be +quite useful for scripting, or passing the data to Gnuplot. To show +only the date and running total, use `-J'. + +2.1.4.6 Display by value expression +................................... + +With `-d' you can decide which transactions (or accounts in the balance +report) are displayed, according to a value expression. The computed +total is not affected, only the display. This can be very useful for +shortening a report without changing the running total: + + ledger -d 'd>=[last month]' reg checking + + This command shows the checking account's register, beginning from +last month, but with the running total reflecting the entire history of +the account. + +2.1.4.7 Change report format +............................ + +When dates are printed in any report, the default format is `%Y/%m/%d', +which yields dates of the form `YYYY/mm/dd'. This can be changed with +`-y', whose argument is a `strftime' string--see your system's C +library documentation for the allowable codes. Mostly you will want to +use `%Y', `%m' and `%d', in whatever combination is convenient for your +locale. + + To change the format of the entire reported line, use `-F'. It +supports quite a large number of options, which are all documented in +*note Format strings::. In addition, each specific kind of report +(except for `xml') can be changed using one of the following options: + +`--balance-format' + `balance' report. Default: + %20T %2_%-a\n + +`--register-format' + `register' report. Default: + %D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n + +`--print-format' + `print' report. Default: + %D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n + +`--plot-amount-format' + `register' report when `-j' (plot amount) is used. Default: + %D %(St)\n + +`--plot-total-format' + `register' report when `-J' (plot total) is used. Default: + %D %(ST)\n + +`--equity-format' + `equity' report. Default: + \n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n + +`--prices-format' + `prices' report. Default: + \n%D %Y%C%P\n%/ %-34W %12t\n + +`--wide-register-format' + `register' report when `-w' (wide) is used. Default: + %D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n + +2.1.5 Standard queries +---------------------- + +If your ledger file uses the standard top-level accounts: Assets, +Liabilities, Income, Expenses, Equity: then the following queries will +enable you to generate some typical accounting reports from your data. + + Your _net worth_ can be determined by balancing assets against +liabilities: + + ledger bal ^assets ^liab + + By removing long-term investment and loan accounts, you can see your +current net liquidity (or liquid net worth): + + ledger bal ^assets ^liab -retirement -brokerage -loan + + Balancing expenses against income yields your _cash flow_, or net +profit/loss: + + ledger bal ^exp ^inc + + In this case, if the number is positive it means you spent more than +you earned during the report period. + + The most often used command is the "balance" command: + + export LEDGER=/home/johnw/doc/ledger.dat + ledger balance + + Here I've set my Ledger environment variable to point to where my +ledger file is hiding. Thereafter, I needn't specify it again. + +2.1.6 Reporting balance totals +------------------------------ + +The balance command prints out the summarized balances of all my +top-level accounts, excluding sub-accounts. In order to see the +balances for a specific account, just specify a regular expression +after the balance command: + + ledger balance expenses:food + + 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: + + ledger -p sep balance expenses:food + + Or maybe you want to see all of your assets, in which case the -s +(show sub-accounts) option comes in handy: + + ledger -s balance ^assets + + To exclude a particular account, use a regular expression with a +leading minus sign. The following will show all expenses, but without +food spending: + + ledger balance expenses -food + +2.1.7 Reporting percentages +--------------------------- + +There is no built-in way to report transaction amounts or account +balances in terms of percentages + + ---------- Footnotes ---------- + + (1) It is impossible for accounts not to balance in ledger; it +reports an error if a transaction does not balance + + (2) If it ever does, then generated transactions are involved, which +can be removed using `--actual' + + +File: ledger.info, Node: Commands, Next: Options, Prev: Usage overview, Up: Running Ledger + +2.2 Commands +============ + +2.2.1 balance +------------- + +The `balance' command reports the current balance of all accounts. It +accepts a list of optional regexps, which confine the balance report to +the matching accounts. If an account contains multiple types of +commodities, each commodity's total is reported separately. + +2.2.2 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. + + If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script `report', which is included +in the Ledger distribution. The only requirement is that you add +either `-j' or `-J' to your register command, in order to plot either +the amount or total column, respectively. + +2.2.3 print +----------- + +The `print' command prints out ledger entries in a textual format that +can be parsed by Ledger. They will be properly formatted, and output +in the most economic form possible. The "print" command also takes a +list of optional regexps, which will cause only those transactions +which match in some way to be printed. + + The `print' command can be a handy way to clean up a ledger file +whose formatting has gotten out of hand. + +2.2.4 output +------------ + +The `output' command is very similar to the `print' command, except +that it attempts to replicate the specified ledger file exactly. The +format of the command is: + + ledger -f FILENAME output FILENAME + + Where `FILENAME' is the name of the ledger file to output. The +reason for specifying this command is that only entries contained +within that file will be output, and not an included entries (as can +happen with the `print' command). + +2.2.5 xml +--------- + +The `xml' command outputs results similar to what `print' and +`register' display, but as an XML form. This data can then be read in +and processed. Use the `--totals' option to include the running total +with each transaction. + +2.2.6 emacs +----------- + +The `emacs' command outputs results in a form that can be read directly +by Emacs Lisp. The format of the sexp is: + + ((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of transactions + ...) ; list of entries + +2.2.7 equity +------------ + +The `equity' command prints out accounts balances as if they were +entries. This makes it easy to establish the starting balances for an +account, such as when *note Archiving previous years::. + +2.2.8 prices +------------ + +The `prices' command displays the price history for matching +commodities. The `-A' flag is useful with this report, to display the +running average price, or `-D' to show each price's deviation from that +average. + + There is also a `pricesdb' command which outputs the same +information as `prices', but does in a format that can be parsed by +Ledger. + +2.2.9 entry +----------- + +The `entry' commands simplifies the creation of new entries. It works +on the principle that 80% of all transactions are variants of earlier +transactions. Here's how it works: + + Say you currently have this transaction in your ledger file: + + 2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 + + Now it's `2004/4/9', and you've just eating at `Viva Italiano' +again. The exact amounts are different, but the overall form is the +same. With the `entry' command you can type: + + ledger entry 2004/4/9 viva food 11 tips 2.50 + + This produces the following output: + + 2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 + + It works by finding a past transaction matching the regular +expression `viva', and assuming that any accounts or amounts specified +will be similar to that earlier transaction. If Ledger does not +succeed in generating a new entry, an error is printed and the exit +code is set to `1'. + + There is a shell script in the distribution's `scripts' directory +called `entry', which simplifies the task of adding a new entry to your +ledger. It launches `vi' to confirm that the entry looks appropriate. + + Here are a few more examples of the `entry' command, assuming the +above journal entry: + + ledger entry 4/9 viva 11.50 + ledger entry 4/9 viva 11.50 checking # (from `checking') + ledger entry 4/9 viva food 11.50 tips 8 + ledger entry 4/9 viva food 11.50 tips 8 cash + ledger entry 4/9 viva food $11.50 tips $8 cash + ledger entry 4/9 viva dining "DM 11.50" + + +File: ledger.info, Node: Options, Next: Format strings, Prev: Commands, Up: Running Ledger + +2.3 Options +=========== + +With all of the reports, command-line options are useful to modify the +output generated. These command-line options always occur before the +command word. This is done to distinguish options from exclusive +regular expressions, which also begin with a dash. The basic form for +most commands is: + + ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] + + The OPTIONS and REGEXPS expressions are both optional. You could +just use `ledger balance', without any options--which prints a summary +of all accounts. But for more specific reporting, or to change the +appearance of the output, options are needed. + +* Menu: + +* Basic options:: +* Report filtering:: +* Output customization:: +* Commodity reporting:: +* Environment variables:: + + +File: ledger.info, Node: Basic options, Next: Report filtering, Prev: Options, Up: Options + +2.3.1 Basic options +------------------- + +These are the most basic command options. Most likely, the user will +want to set them using *note Environment variables::, instead of using +actual command-line options: + + `--help' (`-h') prints a summary of all the options, and what they +are used for. This can be a handy way to remember which options do +what. This help screen is also printed if ledger is run without a +command. + + `--version' (`-v') prints the current version of ledger and exits. +This is useful for sending bug reports, to let the author know which +version of ledger you are using. + + `--file FILE' (`-f FILE') reads FILE as a ledger file. This command +may be used multiple times. FILE may also be a list of file names +separated by colons. Typically, the environment variable `LEDGER_FILE' +is set, rather than using this command-line option. + + `--output FILE' (`-o FILE') redirects output from any command to +FILE. By default, all output goes to standard output. + + `--init-file FILE' (`-i FILE') causes FILE to be read by ledger +before any other ledger file. This file may not contain any +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: + + --price-db ~/finance/.pricedb + + ; ~/.ledgerrc ends here + + Option settings on the command-line or in the environment always take +precedence over settings in the init file. + + `--cache FILE' identifies FILE as the default binary cache file. +That is, if the ledger files to be read are specified using the +environment variable `LEDGER_FILE', then whenever a command is finished +a binary copy will be written to the specified cache, to speed up the +loading time of subsequent queries. This filename can also be given +using the environment variable `LEDGER_CACHE', or by putting the option +into your init file. The `--no-cache' option causes Ledger to always +ignore the binary cache. + + `--account NAME' (`-a NAME') specifies the default account which QIF +file transactions are assumed to relate to. + + +File: ledger.info, Node: Report filtering, Next: Output customization, Prev: Basic options, Up: Options + +2.3.2 Report filtering +---------------------- + +These options change which transactions affect the outcome of a report, +in ways other than just using regular expressions: + + `--current'(`-c') displays only entries occurring on or before the +current date. + + `--begin DATE' (`-b DATE') constrains the report to entries on or +after DATE. Only entries after that date will be calculated, which +means that the running total in the balance report will always start at +zero with the first matching entry. (Note: This is different from +using `--display' to constrain what is displayed). + + `--end DATE' (`-e DATE') constrains the report so that entries on or +after DATE are not considered. The ending date is inclusive. + + `--period STR' (`-p STR') sets the reporting period to STR. This +will subtotal all matching entries within each period separately, +making it easy to see weekly, monthly, quarterly, etc., transaction +totals. A period string can even specify the beginning and end of the +report range, using simple terms like "last june" or "next month". For +more using period expressions, see *note Period expressions::. + + `--period-sort EXPR' sorts the transactions within each reporting +period using the value expression EXPR. This is most often useful when +reporting monthly expenses, in order to view the highest expense +categories at the top of each month: + + ledger -M --period-sort -At reg ^Expenses + + `--cleared' (`-C') displays only transactions whose entry has been +marked "cleared" (by placing an asterix to the right of the date). + + `--uncleared' (`-U') displays only transactions whose entry has not +been marked "cleared" (i.e., if there is no asterix to the right of the +date). + + `--real' (`-R') displays only real transactions, not virtual. (A +virtual transaction is indicated by surrounding the account name with +parentheses or brackets; see the section on using virtual transactions +for more information). + + `--actual' (`-L') displays only actual transactions, and not those +created due to automated transactions. + + `--related' (`-r') displays transactions that are related to +whichever transactions would otherwise have matched the filtering +criteria. In the register report, this shows where money went to, or +the account it came from. In the balance report, it shows all the +accounts affected by entries having a related transaction. For +example, if a file had this entry: + + 2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 + + And the register command was: + + ledger -r register food + + The following would be output, showing the transactions related to +the transaction that matched: + + 2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 + + `--budget' is useful for displaying how close your transactions meet +your budget. `--add-budget' also shows unbudgeted transactions, while +`--unbudgeted' shows only those. `--forecast' is a related option that +projects your budget into the future, showing how it will affect future +balances. *Note Budgeting and forecasting::. + + `--limit EXPR' (`-l EXPR') limits which transactions take part in +the calculations of a report. + + `--amount EXPR' (`-t EXPR') changes the value expression used to +calculate the "value" column in the `register' report, the amount used +to calculate account totals in the `balance' report, and the values +printed in the `equity' report. *Note Value expressions::. + + `--total EXPR' (`-T EXPR') sets the value expression used for the +"totals" column in the `register' and `balance' reports. + + +File: ledger.info, Node: Output customization, Next: Commodity reporting, Prev: Report filtering, Up: Options + +2.3.3 Output customization +-------------------------- + +These options affect only the output, but not which transactions are +used to create it: + + `--collapse' (`-n') causes entries in a `register' report with +multiple transactions to be collapsed into a single, subtotaled entry. + + `--subtotal' (`-s') causes all entries in a `register' report to be +collapsed into a single, subtotaled entry. + + `--by-payee' (`-P') reports subtotals by payee. + + `--comm-as-payee' (`-x') changes the payee of every transaction to +be the commodity used in that transaction. This can be useful when +combined with other options, such as `-s'. + + `--empty' (`-E') includes even empty accounts in the `balance' +report. + + `--weekly' (`-W') reports transaction totals by the week. The week +begins on whichever day of the week begins the month containing that +transaction. To set a specific begin date, use a period string, such +as `weekly from DATE'. `--monthly' (`-M') reports transaction totals +by month; `--yearly' (`-Y') reports transaction totals by year. For +more complex period, using the `--period' option described above. + + `--dow' reports transactions totals for each day of the week. This +is an easy way to see if weekend spending is more than on weekdays. + + `--sort EXPR' (`-S EXPR') sorts a report by comparing the values +determined using the value expression EXPR. For example, using `-S +-UT' in the balance report will sort account balances from greatest to +least, using the absolute value of the total. For more on how to use +value expressions, see *note Value expressions::. + + `--wide' (`-w') causes the default `register' report to assume 132 +columns instead of 80. + + `--head' causes only the first N entries to be printed. This is +different from using the command-line utility `head', which would limit +to the first N transactions. `--tail' outputs only the last N entries. +Both options may be used simultaneously. If a negative amount is +given, it will invert the meaning of the flag (instead of the first +five entries being printed, for example, it would print all but the +first five). + + `--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 `LEDGER_PAGER' environment +variable. + + `--average' (`-A') reports the average transaction value. + + `--deviation' (`-D') reports each transaction's deviation from the +average. It is only meaningful in the `register' and `prices' reports. + + `--percentage' (`-%') shows account subtotals in the `balance' +report as percentages of the parent account. + + `--totals' include running total information in the `xml' report. + + `--amount-data' (`-j') changes the `register' report so that it +output nothing but the date and the value column, and the latter +without commodities. This is only meaningful if the report uses a +single commodity. This data can then be fed to other programs, which +could plot the date, analyze it, etc. + + `--total-data' (`-J') changes the `register' report so that it +output nothing but the date and totals column, without commodities. + + `--display EXPR' (`-d EXPR') limits which transactions or accounts +or actually displayed in a report. They might still be calculated, and +be part of the running total of a register report, for example, but +they will not be displayed. This is useful for seeing last month's +checking transactions, against a running balance which includes all +transaction values: + + ledger -d "d>=[last month]" reg checking + + The output from this command is very different from the following, +whose running total includes only transactions from the last month +onward: + + ledger -p "last month" reg checking + + Which is more useful depends on what you're looking to know: the +total amount for the reporting range (`-p'), or simply a display +restricted to the reporting range (using `-d'). + + `--date-format STR' (`-y STR') changes the basic date format used by +reports. The default uses a date like 2004/08/01, which represents the +default date format of `%Y/%m/%d'. To change the way dates are printed +in general, the easiest way is to put `--date-format FORMAT' in the +Ledger initialization file `~/.ledgerrc' (or the file referred to by +`LEDGER_INIT'). + + `--format STR' (`-F STR') sets the reporting format for whatever +report ledger is about to make. *Note Format strings::. There are +also specific format commands for each report type: + + * `--balance-format STR' + + * `--register-format STR' + + * `--print-format STR' + + * `--plot-amount-format STR' (-j `register') + + * `--plot-total-format STR' (-J `register') + + * `--equity-format STR' + + * `--prices-format STR' + + * `--wide-register-format STR' (-w `register') + + +File: ledger.info, Node: Commodity reporting, Next: Environment variables, Prev: Output customization, Up: Options + +2.3.4 Commodity reporting +------------------------- + +These options affect how commodity values are displayed: + + `--price-db FILE' sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this file +manually, to prevent downloading quotes for a specific, for example. +This is done by adding a line like the following: + + ; Don't download quotes for the dollar, or timelog values + N $ + N h + + `--price-exp MINS' (`-L MINS') sets the expected freshness of price +quotes, in minutes. That is, if the last known quote for any commodity +is older than this value--and if `--download' is being used--then the +Internet will be consulted again for a newer price. Otherwise, the old +price is still considered to be fresh enough. + + `--download' (`-Q') causes quotes to be automagically downloaded, as +needed, by running a script named `getquote' and expecting that script +to return a value understood by ledger. A sample implementation of a +`getquote' script, implemented in Perl, is provided in the +distribution. Downloaded quote price are then appended to the price +database, usually specified using the environment variable +`LEDGER_PRICE_DB'. + + There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the `-t' and `-T' options. However, there are also +several "default" reports, which will satisfy most users basic +reporting needs: + +`-O, --quantity' + Reports commodity totals (this is the default) + +`-B, --basis' + Reports the cost basis for all transactions. + +`-V, --market' + Reports the last known market value for all commodities. + +`-g, --performance' + Reports the net gain/loss for each transaction in a `register' + report. + +`-G --gain' + Reports the net gain/loss for all commodities in the report that + have a price history. + + +File: ledger.info, Node: Environment variables, Prev: Commodity reporting, Up: Options + +2.3.5 Environment variables +--------------------------- + +Every option to ledger may be set using an environment variable. If an +option has a long name such `--this-option', setting the environment +variable `LEDGER_THIS_OPTION' will have the same affect as specifying +that option on the command-line. Options on the command-line always +take precedence over environment variable settings, however. + + Note that you may also permanently specify option values by placing +option settings in the file `~/.ledgerrc', for example: + + --cache /tmp/.mycache + + +File: ledger.info, Node: Format strings, Next: Value expressions, Prev: Options, Up: Running Ledger + +2.4 Format strings +================== + +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the `--format' +(`-F') option. Within that string, constructs are allowed which make +it possible to display the various parts of an account or transaction +in custom ways. + + Within a format strings, a substitution is specified using a percent +character (`%'). The basic format of all substitutions is: + + %[-][MIN WIDTH][.MAX WIDTH]EXPR + + If the optional minus sign (`-') follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text will +be at least that wide, perhaps wider. If a period and a maximum width +is given, the substituted text will never be wider than this, and will +be truncated to fit. Here are some examples: + + %-P An entry's payee, left justified + %20P The same, right justified, at least 20 chars wide + %.20P The same, no more than 20 chars wide + %-.20P Left justified, maximum twenty chars wide + + The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: + +`%' + Inserts a percent sign. + +`t' + Inserts the results of the value expression specified by `-t'. If + `-t' was not specified, the current report style's value + expression is used. + +`T' + Inserts the results of the value expression specified by `-T'. If + `-T' was not specified, the current report style's value + expression is used. + +`|' + Inserts a single space. This is useful if a width is specified, + for inserting a certain number of spaces. + +`_' + Inserts a space for each level of an account's depth. That is, if + an account has two parents, this construct will insert two spaces. + If a minimum width is specified, that much space is inserted for + each level of depth. Thus `%5_', for an account with four + parents, will insert twenty spaces. + +`(EXPR)' + Inserts the amount resulting from the value expression given in + parentheses. To insert five times the total value of an account, + for example, one could say `%12(5*O)'. Note: It's important to put + the five first in that expression, so that the commodity doesn't + get stripped from the total. + +`[DATEFMT]' + Inserts the result of formatting a transaction's date with a date + format string, exactly like those supported by `strftime'. For + example: `%[%Y/%m/%d %H:%M:%S]'. + +`S' + Insert the pathname of the file from which the entry's data was + read. + +`B' + Inserts the beginning character position of that entry within the + file. + +`b' + Inserts the beginning line of that entry within the file. + +`E' + Inserts the ending character position of that entry within the + file. + +`e' + Inserts the ending line of that entry within the file. + +`D' + By default, this is the same as `%[%Y/%m%/d]'. The date format + used can be changed at any time with the `-y' flag, however. + Using `%D' gives the user more control over the way dates are + output. + +`d' + This is the same as the `%D' option, unless the entry has an + effective date, in which case it prints + `[ACTUAL_DATE=EFFECtIVE_DATE]'. + +`X' + If a transaction has been cleared, this inserts `*' followed by a + space; otherwise nothing is inserted. + +`Y' + This is the same as `%X', except that it only displays a state + character if all of the member transactions have the same state. + +`C' + Inserts the checking number for an entry, in parentheses, followed + by a space; if none was specified, nothing is inserted. + +`P' + Inserts the payee related to a transaction. + +`a' + Inserts the optimal short name for an account. This is normally + used in balance reports. It prints a parent account's name if + that name has not been printed yet, otherwise it just prints the + account's name. + +`A' + Inserts the full name of an account. + +`W' + This is the same as `%A', except that it first displays the + transaction's state _if the entry's transaction states are not all + the same_, followed by the full account name. This is offered as + a printing optimization, so that combined with `%Y', only the + minimum amount of state detail is printed. + +`o' + Inserts the "optimized" form of a transaction's amount. This is + used by the print report. In some cases, this inserts nothing; in + others, it inserts the transaction amount and its cost. It's use + is not recommend unless you are modifying the print report. + +`n' + Inserts the note associated with a transaction, preceded by two + spaces and a semi-colon, if it exists. Thus, no none becomes an + empty string, while the note `foo' is substituted as ` ; foo'. + +`N' + Inserts the note associated with a transaction, if one exists. + +`/' + The `%/' construct is special. It separates a format string + between what is printed for the first transaction of an entry, and + what is printed for all subsequent transactions. If not used, the + same format string is used for all transactions. + + +File: ledger.info, Node: Value expressions, Next: Period expressions, Prev: Format strings, Up: Running Ledger + +2.5 Value expressions +===================== + +Value expressions are an expression language used by Ledger to +calculate values used by the program for many different purposes: + + 1. The values displayed in reports + + 2. For predicates (where truth is anything non-zero), to determine + which transactions are calculated (`-l') or displayed (`-d'). + + 3. For sorting criteria, to yield the sort key. + + 4. In the matching criteria used by automated transactions. + + Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +argument is whatever follows it. The following is a display predicate +that I use with the `balance' command: + + ledger -d /^Liabilities/?T<0:UT>100 balance + + The effect is that account totals are displayed only if: 1) A +Liabilities account has a total less than zero; or 2) the absolute +value of the account's total exceeds 100 units of whatever commodity +contains. If it contains multiple commodities, only one of them must +exceed 100 units. + + Display predicates are also very handy with register reports, to +constrain which entries are printed. For example, the following +command shows only entries from the beginning of the current month, +while still calculating the running balance based on all entries: + + ledger -d "d>[this month]" register checking + + This advantage to this command's complexity is that it prints the +running total in terms of all entries in the register. The following, +simpler command is similar, but totals only the displayed transactions: + + ledger -b "this month" register checking + +2.5.1 Variables +--------------- + +Below are the one letter variables available in any value expression. +For the register and print commands, these variables relate to +individual transactions, and sometimes the account affected by a +transaction. For the balance command, these variables relate to +accounts--often with a subtle difference in meaning. The use of each +variable for both is specified. + +`t' + This maps to whatever the user specified with `-t'. In a register + report, `-t' changes the value column; in a balance report, it has + no meaning by default. If `-t' was not specified, the current + report style's value expression is used. + +`T' + This maps to whatever the user specified with `-T'. In a register + report, `-T' changes the totals column; in a balance report, this + is the value given for each account. If `-T' was not specified, + the current report style's value expression is used. + +`m' + This is always the present moment/date. + +2.5.1.1 Transaction/account details +................................... + +`d' + A transaction's date, as the number of seconds past the epoch. + This is always "today" for an account. + +`a' + The transaction's amount; the balance of an account, without + considering children. + +`b' + The cost of a transaction; the cost of an account, without its + children. + +`v' + The market value of a transaction, or an account without its + children. + +`g' + The net gain (market value minus cost basis), for a transaction or + an account without its children. It is the same as `v-b'. + +`l' + The depth ("level") of an account. If an account has one parent, + it's depth is one. + +`n' + The index of a transaction, or the count of transactions affecting + an account. + +`X' + 1 if a transaction's entry has been cleared, 0 otherwise. + +`R' + 1 if a transaction is not virtual, 0 otherwise. + +`Z' + 1 if a transaction is not automated, 0 otherwise. + +2.5.1.2 Calculated totals +......................... + +`O' + The total of all transactions seen so far, or the total of an + account and all its children. + +`N' + The total count of transactions affecting an account and all its + children. + +`B' + The total cost of all transactions seen so far; the total cost of + an account and all its children. + +`V' + The market value of all transactions seen so far, or of an account + and all its children. + +`G' + The total net gain (market value minus cost basis), for a series of + transactions, or an account and its children. It is the same as + `V-B'. + +2.5.2 Functions +--------------- + +The available one letter functions are: + +`-' + Negates the argument. + +`U' + The absolute (unsigned) value of the argument. + +`S' + Strips the commodity from the argument. + +`A' + The arithmetic mean of the argument; `Ax' is the same as `x/n'. + +`P' + The present market value of the argument. The syntax `P(x,d)' is + supported, which yields the market value at time `d'. If no date + is given, then the current moment is used. + +2.5.3 Operators +--------------- + +The binary and ternary operators, in order of precedence, are: + + 1. `* /' + + 2. `+ -' + + 3. `! < > =' + + 4. `& | ?:' + +2.5.4 Complex expressions +------------------------- + +More complicated expressions are possible using: + +`NUM' + A plain integer represents a commodity-less amount. + +`{AMOUNT}' + An amount in braces can be any kind of amount supported by ledger, + with or without a commodity. Use this for decimal values. + +`/REGEXP/' + +`W/REGEXP/' + A regular expression that matches against an account's full name. + If a transaction, this will match against the account affected by + the transaction. + +`//REGEXP/' + +`p/REGEXP/' + A regular expression that matches against an entry's payee name. + +`///REGEXP/' + +`w/REGEXP/' + A regular expression that matches against an account's base name. + If a transaction, this will match against the account affected by + the transaction. + +`c/REGEXP/' + A regular expression that matches against the entry code (the text + that occurs between parentheses before the payee name). + +`e/REGEXP/' + A regular expression that matches against a transaction's note, or + comment field. + +`(EXPR)' + A sub-expression is nested in parenthesis. This can be useful + passing more complicated arguments to functions, or for overriding + the natural precedence order of operators. + +`[DATE]' + Useful specifying a date in plain terms. For example, you could + say `[2004/06/01]'. + + +File: ledger.info, Node: Period expressions, Next: File format, Prev: Value expressions, Up: Running Ledger + +2.6 Period expressions +====================== + +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: + + [INTERVAL] [BEGIN] [END] + + The optional INTERVAL part may be any one of: + + every day + every week + every monthly + every quarter + every year + every N days # N is any integer + every N weeks + every N months + every N quarters + every N years + daily + weekly + biweekly + monthly + bimonthly + quarterly + yearly + + After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: + + from + since + + The end time can be either of: + + to + until + + Where SPEC can be any of: + + 2004 + 2004/10 + 2004/10/1 + 10/1 + october + oct + this week # or day, month, quarter, year + next week + last week + + The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use SPEC by itself. In that case, +the period `oct', for example, will cover all the days in october. The +possible forms are: + + + in + + Here are a few examples of period expressions: + + monthly + monthly in 2004 + weekly from oct + weekly from last month + from sep to oct + from 10/1 to 10/5 + monthly until 2005 + from apr + until nov + last oct + weekly last august + + +File: ledger.info, Node: File format, Next: Some typical queries, Prev: Period expressions, Up: Running Ledger + +2.7 File format +=============== + +The ledger file format is quite simple, but also very flexible. It +supports many options, though typically the user can ignore most of +them. They are summarized below. + + The initial character of each line determines what the line means, +and how it should be interpreted. Allowable initial characters are: + +`NUMBER' + A line beginning with a number denotes an entry. It may be + followed by any number of lines, each beginning with whitespace, + to denote the entry's account transactions. The format of the + first line is: + + DATE[=EDATE] [*|!] [(CODE)] DESC + + If `*' appears after the date (with optional effective date), it + indicates the entry is "cleared", which can mean whatever the user + wants it t omean. If `!' appears after the date, it indicates d + the entry is "pending"; i.e., tentatively cleared from the user's + point of view, but not yet actually cleared. If a `CODE' appears + in parentheses, it may be used to indicate a check number, or the + type of the transaction. Following these is the payee, or a + description of the transaction. + + The format of each following transaction is: + + ACCOUNT AMOUNT [; NOTE] + + The `ACCOUNT' may be surrounded by parentheses if it is a virtual + transactions, or square brackets if it is a virtual transactions + that must balance. The `AMOUNT' can be followed by a per-unit + transaction cost, by specifying `@ AMOUNT', or a complete + transaction cost with `@@ AMOUNT'. Lastly, the `NOTE' may specify + an actual and/or effective date for the transaction by using the + syntax `[ACTUAL_DATE]' or `[=EFFECTIVE_DATE]' or + `[ACTUAL_DATE=EFFECtIVE_DATE]'. + +`=' + An automated entry. A value expression must appear after the equal + sign. + + After this initial line there should be a set of one or more + transactions, just as if it were normal entry. If the amounts of + the transactions have no commodity, they will be applied as + modifiers to whichever real transaction is matched by the value + expression. + +`~' + A period entry. A period expression must appear after the tilde. + + After this initial line there should be a set of one or more + transactions, just as if it were normal entry. + +`!' + A line beginning with an exclamation mark denotes a command + directive. It must be immediately followed by the command word. + The supported commands are: + + `!include' + Include the stated ledger file. + + `!account' + The account name is given is taken to be the parent of all + transactions that follow, until `!end' is seen. + + `!end' + Ends an account block. + +`;' + A line beginning with a colon indicates a comment, and is ignored. + +`Y' + If a line begins with a capital Y, it denotes the year used for all + subsequent entries that give a date without a year. The year + should appear immediately after the Y, for example: `Y2004'. This + is useful at the beginning of a file, to specify the year for that + file. If all entries specify a year, however, this command has no + effect. + +`P' + Specifies a historical price for a commodity. These are usually + found in a pricing history file (see the `-Q' option). The syntax + is: + P DATE SYMBOL PRICE + +`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 `~/.pricedb'. The syntax for this command is: + N SYMBOL + +`D AMOUNT' + Specifies the default commodity to use, by specifying an amount in + the expected format. The `entry' command will use this commodity + as the default when none other can be determined. This command + may be used multiple times, to set the default flags for different + commodities; whichever is seen last is used as the default + commodity. For example, to set US dollars as the default + commodity, while also setting the thousands flag and decimal flag + for that commodity, use: + D $1,000.00 + +`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: + C 1.00 Kb = 1024 bytes + +`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. + + +File: ledger.info, Node: Some typical queries, Next: Budgeting and forecasting, Prev: File format, Up: Running Ledger + +2.8 Some typical queries +======================== + +A query such as the following shows all expenses since last October, +sorted by total: + + ledger -b "last oct" -s -S T bal ^expenses + + From left to right the options mean: Show entries since October, +2003; show all sub-accounts; sort by the absolute value of the total; +and report the balance for all expenses. + +2.8.1 Reporting monthly expenses +-------------------------------- + +The following query makes it easy to see monthly expenses, with each +month's expenses sorted by the amount: + + ledger -M --period-sort t reg ^expenses + + Now, you might wonder where the money came from to pay for these +things. To see that report, add `-r', which shows the "related +account" transactions: + + ledger -M --period-sort t -r reg ^expenses + + But maybe this prints too much information. You might just want to +see how much you're spending with your MasterCard. That kind of query +requires the use of a display predicate, since the transactions +calculated must match `^expenses', while the transactions displayed +must match `mastercard'. The command would be: + + ledger -M -r -d /mastercard/ reg ^expenses + + This query says: Report monthly subtotals; report the "related +account" transactions; display only related transactions whose account +matches `mastercard', and base the calculation on transactions matching +`^expenses'. + + This works just as well for report the overall total, too: + + ledger -s -r -d /mastercard/ reg ^expenses + + The `-s' option subtotals all transactions, just as `-M' subtotaled +by the month. The running total in both cases is off, however, since a +display expression is being used. + +2.8.2 Visualizing with Gnuplot +------------------------------ + +If you have `Gnuplot' installed, you can graph any of the above +register reports. The script to do this is included in the ledger +distribution, and is named `scripts/report'. Install `report' anywhere +along your `PATH', and then use `report' instead of `ledger' when doing +a register report. The only thing to keep in mind is that you must +specify `-j' or `-J' to indicate whether Gnuplot should plot the +amount, or the running total. For example, this command plots total +monthly expenses made on your MasterCard. + + report -j -M -r -d /mastercard/ reg ^expenses + + The `report' script is a very simple Bourne shell script, that +passes a set of scripted commands to Gnuplot. Feel free to modify the +script to your liking, since you may prefer histograms to line plots, +for example. + +2.8.2.1 Typical plots +..................... + +Here are some useful plots: + + report -j -M reg ^expenses # monthly expenses + report -J reg checking # checking account balance + report -J reg ^income ^expenses # cash flow report + + # net worth report, ignoring non-$ transactions + + report -J -l "Ua>={\$0.01}" reg ^assets ^liab + + # net worth report starting last February. the use of a display + # predicate (-d) is needed, otherwise the balance will start at + # zero, and thus the y-axis will not reflect the true balance + + report -J -l "Ua>={\$0.01}" -d "d>=[last feb]" reg ^assets ^liab + + The last report uses both a calculation predicate (`-l') and a +display predicate (`-d'). The calculation predicates limits the report +to transactions whose amount is greater than $1 (which can only happen +if the transaction amount is in dollars). The display predicate limits +the entries _displayed_ to just those since last February, even those +entries from before then will be computed as part of the balance. + + +File: ledger.info, Node: Budgeting and forecasting, Prev: Some typical queries, Up: Running Ledger + +2.9 Budgeting and forecasting +============================= + +2.9.1 Budgeting +--------------- + +Keeping a budget allows you to pay closer attention to your income and +expenses, by reporting how far your actual financial activity is from +your expectations. + + To start keeping a budget, put some period entries at the top of your +ledger file. A period entry is almost identical to a regular entry, +except that it begins with a tilde and has a period expression in place +of a payee. For example: + + ~ Monthly + Expenses:Rent $500.00 + Expenses:Food $450.00 + Expenses:Auto:Gas $120.00 + Expenses:Insurance $150.00 + Expenses:Phone $125.00 + Expenses:Utilities $100.00 + Expenses:Movies $50.00 + Expenses $200.00 ; all other expenses + Assets + + ~ Yearly + Expenses:Auto:Repair $500.00 + Assets + + These two period entries give the usual monthly expenses, as well as +one typical yearly expense. For help on finding out what your average +monthly expense is for any category, use a command like: + + ledger -p "this year" -MAs bal ^expenses + + The reported totals are the current year's average for each account. + + Once these period entries are defined, creating a budget report is as +easy as adding `--budget' to the command-line. For example, a typical +monthly expense report would be: + + ledger -M reg ^exp + + To see the same report balanced against your budget, use: + + ledger --budget -M reg ^exp + + A budget report includes only those accounts that appear in the +budget. To see all expenses balanced against the budget, use +`--add-budget'. You can even see only the unbudgeted expenses using +`--unbudgeted': + + ledger --unbudgeted -M reg ^exp + + You can also use these flags with the `balance' command. + +2.9.2 Forecasting +----------------- + +Sometimes it's useful to know what your finances will look like in the +future, such as determining when an account will reach zero. Ledger +makes this easy to do, using the same period entries as are used for +budgeting. An example forecast report can be generated with: + + ledger --forecast "T>{\$-500.00}" register ^assets ^liabilities + + This report continues outputting transactions until the running total +is greater than $-500.00. A final transaction is always output, to +show you what the total afterwards would be. + + Forecasting can also be used with the balance report, but by date +only, and not against the running total: + + ledger --forecast "d<[2010]" bal ^assets ^liabilities + + +File: ledger.info, Node: Keeping a ledger, Next: Using XML, Prev: Running Ledger, Up: Top + +3 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: + + 9/29 (100) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking $-23.00 + + 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: + + 9/29 (100) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking + + 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:: +* Working with multiple funds and accounts:: +* Archiving previous years:: +* Virtual transactions:: +* Automated transactions:: +* Using Emacs to Keep Your Ledger:: +* Using GnuCash to Keep Your Ledger:: +* Using timeclock to record billable time:: + + +File: ledger.info, Node: Stating where money goes, Next: Assets and Liabilities, Prev: Keeping a ledger, Up: Keeping a ledger + +3.1 Stating where money goes +============================ + +Accountants will talk of "credits" and "debits", but the meaning is +often different from the layman's understanding. To avoid confusion, +Ledger uses only subtractions and additions, although the underlying +intent is the same as standard accounting principles. + + Recall that every transaction will involve two or more accounts. +Money is transferred from one or more accounts to one or more other +accounts. To record the transaction, an amount is _subtracted_ from +the source accounts, and _added_ to the target accounts. + + In order to write a Ledger entry correctly, you must determine where +the money comes from and where it goes to. For example, when you are +paid a salary, you must add money to your bank account and also +subtract it from an income account: + + 9/29 My Employer + Assets:Checking $500.00 + Income:Salary $-500.00 + + Why is the Income a negative figure? When you look at the balance +totals for your ledger, you may be surprised to see that Expenses are a +positive figure, and Income is a negative figure. It may take some +getting used to, but to properly use a general ledger you must think in +terms of how money moves. Rather than Ledger "fixing" the minus signs, +let's understand why they are there. + + When you earn money, the money has to come from somewhere. Let's +call that somewhere "society". In order for society to give you an +income, you must take money away (withdraw) from society in order to +put it into (make a payment to) your bank. When you then spend that +money, it leaves your bank account (a withdrawal) and goes back to +society (a payment). This is why Income will appear negative--it +reflects the money you have drawn from society--and why Expenses will +be positive--it is the amount you've given back. These additions and +subtractions will always cancel each other out in the end, because you +don't have the ability to create new money: it must always come from +somewhere, and in the end must always leave. This is the beginning of +economy, after which the explanation gets terribly difficult. + + Based on that explanation, here's another way to look at your balance +report: every negative figure means that that account or person or +place has less money now than when you started your ledger; and every +positive figure means that that account or person or place has more +money now that when you started your ledger. Make sense? + + +File: ledger.info, Node: Assets and Liabilities, Next: Commodities and Currencies, Prev: Stating where money goes, Up: Keeping a ledger + +3.2 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: + + 2004/09/29 My Employer + Assets:Checking $500.00 + Income:Salary + + Money, here, comes from an Income account belonging to "My +Employer", and is transferred to your checking account. The money is +now yours, which makes it an Asset. + + Liabilities track money owed to others. This can happen when you +borrow money to buy something, or if you owe someone money. Here is an +example of increasing a MasterCard liability by spending money with it: + + 2004/09/30 Restaurant + Expenses:Dining $25.00 + Liabilities:MasterCard + + The Dining account balance now shows $25 spent on Dining, and a +corresponding $25 owed on the MasterCard--and therefore shown as +$-25.00. The MasterCard liability shows up as negative because it +offsets the value of your assets. + + The combined total of your Assets and Liabilities is your net worth. +So to see your current net worth, use this command: + + ledger balance ^assets ^liabilities + + Relatedly, your Income accounts show up negative, because they +transfer money _from_ an account in order to increase your assets. +Your Expenses show up positive because that is where the money went to. +The combined total of Income and Expenses is your cash flow. A +positive cash flow means you are spending more than you make, since +income is always a negative figure. To see your current cash flow, use +this command: + + ledger balance ^income ^expenses + + Another common question to ask of your expenses is: How much do I +spend each month on X? Ledger provides a simple way of displaying +monthly totals for any account. Here is an example that summarizes +your monthly automobile expenses: + + ledger -M register expenses:auto + + This assumes, of course, that you use account names like +`Expenses:Auto:Gas' and `Expenses:Auto:Repair'. + +3.2.1 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 _to_ your Assets:Reimbursements, using a different account for each +person or business that you spend money for. For example: + + 2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard + + This shows $100.00 spent on a MasterCard at Circuit City, with the +expense was made on behalf of Company XYZ. Later, when Company XYZ +pays the amount back, the money will transfer from that reimbursement +account back to a regular asset account: + + 2004/09/29 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ + + This deposits the money owed from Company XYZ into a checking +account, presumably because they paid the amount back with a check. + + But what to do if you run your own business, and you want to keep +track of expenses made on your own behalf, while still tracking +everything in a single ledger file? This is more complex, because you +need to track two separate things: 1) The fact that the money should be +reimbursed to you, and 2) What the expense account was, so that you can +later determine where your company is spending its money. + + This kind of transaction is best handled with mirrored transactions +in two different files, one for your personal accounts, and one for your +company accounts. But keeping them in one file involves the same kinds +of transactions, so those are what is shown here. First, the personal +entry, which shows the need for reimbursement: + + 2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard + + 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: + + 2004/09/29 Circuit City + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name + + 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: + + 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 + + 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: + + 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 + + And now the reimbursements account is paid off, accounts payable is +paid off, and $100.00 has been effectively transferred from the +company's checking account to your personal checking account. The +money simply "waited"--in both `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: + + 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 + + And two in your company ledger file: + + !account Company XYZ + + 2004/09/29 Circuit City + Expenses:Computer:Software $100.00 + Accounts Payable:Your Name $-100.00 + + 2004/10/15 Company XYZ + Accounts Payable:Your Name $100.00 + Assets:Checking $-100.00 + + !end + + (Note: The `!account' above means that all accounts mentioned in the +file are children of that account. In this case it means that all +activity in the file relates to Company XYZ). + + After creating these entries, you will always know that $100.00 was +spent using your MasterCard on behalf of Company XYZ, and that Company +XYZ spent the money on computer software and paid it back about two +weeks later. + + +File: ledger.info, Node: Commodities and Currencies, Next: Accounts and Inventories, Prev: Assets and Liabilities, Up: Keeping a ledger + +3.3 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: + + $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 + 50 EUR ; currency: 50 Euros (or use appropriate symbol) + + 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: + + $200.00 + 100.00 AU + AAPL 40 + BORL 100 + FEQTX 50 Assets:Brokerage + + This balance report shows how much of each commodity is in your +brokerage account. + + Sometimes, you will want to know the current street value of your +balance, and not the commodity totals. For this to happen, you must +specify what the current price is for each commodity. The price can be +any commodity, in which case the balance will be computed in terms of +that commodity. The usual way to specify prices is with a price +history file, which might look like this: + + P 2004/06/21 02:18:01 FEQTX $22.49 + P 2004/06/21 02:18:01 BORL $6.20 + P 2004/06/21 02:18:02 AAPL $32.91 + P 2004/06/21 02:18:02 AU $400.00 + + Specify the price history to use with the `--price-db' option, with +the `-V' option to report in terms of current market value: + + ledger --price-db prices.db -V balance brokerage + + The balance for your brokerage account will be reported in US +dollars, since the prices database uses that currency. + + $40880.00 Assets:Brokerage + + You can convert from any commodity to any other commodity. Let's say +you had $5000 in your checking account, and for whatever reason you +wanted to know many ounces of gold that would buy, in terms of the +current price of gold: + + ledger -T "{1 AU}*(O/P{1 AU})" balance checking + + Although the total expression appears complex, it is simply saying +that the reported total should be in multiples of AU units, where the +quantity is the account total divided by the price of one AU. Without +the initial multiplication, the reported total would still use the +dollars commodity, since multiplying or dividing amounts always keeps +the left value's commodity. The result of this command might be: + + 14.01 AU Assets:Checking + +3.3.1 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: + + 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 + + By default, ledger will not consider commodity prices when generating +its various reports. It will always report balances in terms of the +commodity total, rather than the current value of those commodities. +To enable pricing reports, use one of the commodity reporting options. + +3.3.2 Commodity equivalencies +----------------------------- + +Sometimes a commodity has several forms which are all equivalent. An +example of this is time. Whether tracked in terms of minutes, hours or +days, it should be possible to convert between the various forms. +Doing this requires the use of commodity equivalencies. + + For example, you might have the following two transactions, one which +transfers an hour of time into a `Billable' account, and another which +decreases the same account by ten minutes. The resulting report will +indicate that fifty minutes remain: + + 2005/10/01 Work done for company + Billable:Client 1h + Project:XYZ + + 2005/10/02 Return ten minutes to the project + Project:XYZ 10m + Billable:Client + + Reporting the balance for this ledger file produces: + + 50.0m Billable:Client + -50.0m Project:XYZ + + This example works because ledger already knows how to handle +seconds, minutes and hours, as part of its time tracking support. +Defining other equivalencies is simple. The following is an example +that creates data equivalencies, helpful for tracking bytes, kilobytes, +megabytes, and more: + + C 1.00 Kb = 1024 b + C 1.00 Mb = 1024 Kb + C 1.00 Gb = 1024 Mb + C 1.00 Tb = 1024 Gb + + Each of these definitions correlates a commodity (such as `Kb') and +a default precision, with a certain quantity of another commodity. In +the above example, kilobytes are reporetd with two decimal places of +precision and each kilobyte is equal to 1024 bytes. + + Equivalency chains can be as long as desired. Whenever a commodity +would report as a decimal amount (less than `1.00'), the next smallest +commodity is used. If a commodity could be reported in terms of a +higher commodity without resulting to a partial fraction, then the +larger commodity is used. + + +File: ledger.info, Node: Accounts and Inventories, Next: Understanding Equity, Prev: Commodities and Currencies, Up: Keeping a ledger + +3.4 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: + + 9/29 Get some stuff at the Inn + Places:Black's Tavern -3 Apples + Places:Black's Tavern -5 Steaks + EverQuest:Inventory + + Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The +amounts are negative, because you are taking _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: + + 10/2 Sturm Brightblade + EverQuest:Inventory -2 Steaks + EverQuest:Inventory 15 Gold + + Now you've turned 2 steaks into 15 gold, courtesy of your customer, +Sturm Brightblade. + + +File: ledger.info, Node: Understanding Equity, Next: Dealing with Petty Cash, Prev: Accounts and Inventories, Up: Keeping a ledger + +3.5 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. + + 10/2 Opening Balance + Assets:Checking $100.00 + Equity:Opening Balances + + But what is equity? You may have heard of equity when people talked +about house mortgages, as "the part of the house that you own". +Basically, equity is like the value of something. If you own a car +worth $5000, then you have $5000 in equity in that car. In order to +turn that car (a commodity) into a cash flow, or a credit to your bank +account, you will have to debit the equity by selling it. + + When you start a ledger, you are probably already worth something. +Your net worth is your current equity. By transferring the money in +the ledger from your equity to your bank accounts, you are crediting +the ledger account based on your prior equity. That is why, when you +look at the balance report, you will see a large negative number for +Equity that never changes: Because that is what you were worth (what +you debited from yourself in order to start the ledger) before the +money started moving around. If the total positive value of your +assets is greater than the absolute value of your starting equity, it +means you are making money. + + Clear as mud? Keep thinking about it. Until you figure it out, put +`-Equity' at the end of your balance command, to remove the confusing +figure from the total. + + +File: ledger.info, Node: Dealing with Petty Cash, Next: Working with multiple funds and accounts, Prev: Understanding Equity, Up: Keeping a ledger + +3.6 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: + + 2004/03/15 ATM + Expenses:Cash $100.00 + Assets:Checking + + 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: + + 2004/03/20 Somebody + Expenses:Food $65.00 + Expenses:Cash + + This way, you can still track large cash expenses, while ignoring all +of the smaller ones. + + +File: ledger.info, Node: Working with multiple funds and accounts, Next: Archiving previous years, Prev: Dealing with Petty Cash, Up: Keeping a ledger + +3.7 Working with multiple funds and accounts +============================================ + +There are situations when the accounts you're tracking are different +between your clients and the financial institutions where money is +kept. An example of this is working as the treasurer for a religious +institution. From the secular point of view, you might be working with +three different accounts: + + * Checking + + * Savings + + * Credit Card + + From a religious point of view, the community expects to divide its +resources into multiple "funds", from which it makes purchases or +reserves resources for later: + + * School fund + + * Building fund + + * Community fund + + The problem with this kind of setup is that when you spend money, it +comes from two or more places at once: the account and the fund. And +yet, the correlation of amounts between funds and accounts is rarely +one-to-one. What if the school fund has `$500.00', but `$400.00' of +that comes from Checking, and `$100.00' from Savings? + + Traditional finance packages require that the money reside in only +one place. But there are really two "views" of the data: from the +account point of view and from the fund point of view - yet both sets +should reflect the same overall expenses and cash flow. It's simply +where the money resides that differs. + + This situation can be handled one of two ways. The first is using +virtual transactions to represent the fact that money is moving to and +from two kind of accounts at the same time: + + 2004/03/20 Contributions + Assets:Checking $500.00 + Income:Donations + + 2004/03/25 Distribution of donations + [Funds:School] $300.00 + [Funds:Building] $200.00 + [Assets:Checking] $-500.00 + + The use of square brackets in the second entry ensures that the +virtual transactions balance to zero. Now money can be spent directly +from a fund at the same time as money is drawn from a physical account: + + 2004/03/25 Payment for books (paid from Checking) + Expenses:Books $100.00 + Assets:Checking $-100.00 + (Funds:School) $-100.00 + + When reports are generated, by default they'll appear in terms of the +funds. In this case, you will likely want to mask out your `Assets' +account, because otherwise the balance won't make much sense: + + ledger bal -^Assets + + If the `--real' option is used, the report will be in terms of the +real accounts: + + ledger --real bal + + If more asset accounts are needed as the source of a transaction, +just list them as you would normally, for example: + + 2004/03/25 Payment for books (paid from Checking) + Expenses:Books $100.00 + Assets:Checking $-50.00 + Liabilities:Credit Card $-50.00 + (Funds:School) $-100.00 + + The second way of tracking funds is to use entry codes. In this +respect the codes become like virtual accounts that embrace the entire +set of transactions. Basically, we are associating an entry with a +fund by setting its code. Here are two entries that desposit money +into, and spend money from, the `Funds:School' fund: + + 2004/03/25 (Funds:School) Donations + Assets:Checking $100.00 + Income:Donations + + 2004/04/25 (Funds:School) Payment for books + Expenses:Books $50.00 + Assets:Checking + + Note how the accounts now relate only to the real accounts, and any +balance or registers reports will reflect this. That the entries +relate to a particular fund is kept only in the code. + + How does this become a fund report? By using the `--code-as-payee' +option, you can generate a register report where the payee for each +transaction shows the code. Alone, this is not terribly interesting; +but when combined with the `--by-payee' option, you will now see +account subtotals for any transactions related to a specific fund. So, +to see the current monetary balances of all funds, the command would be: + + ledger --code-as-payee -P reg ^Assets + + Or to see a particular funds expenses, the `School' fund in this +case: + + ledger --code-as-payee -P reg ^Expenses -- School + + Both approaches yield different kinds of flexibility, depending on +how you prefer to think of your funds: as virtual accounts, or as tags +associated with particular entries. Your own tastes will decide which +is best for your situation. + + +File: ledger.info, Node: Archiving previous years, Next: Virtual transactions, Prev: Working with multiple funds and accounts, Up: Keeping a ledger + +3.8 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 `ledger-old.dat': + + ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat + + To delete older data from the current ledger file, use `print' +again, this time specifying year 2002 as the starting date: + + ledger -f ledger.dat -b 2002 print > x + mv x ledger.dat + + However, now the current file contains _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: + + ledger -f ledger-old.dat equity > equity.dat + cat equity.dat ledger.dat > x + mv x ledger.dat + rm equity.dat + + Now the balances reported from `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. + + +File: ledger.info, Node: Virtual transactions, Next: Automated transactions, Prev: Archiving previous years, Up: Keeping a ledger + +3.9 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: + + 10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + (Debt:Alimony) $200.00 + + In this example, after receiving a paycheck an alimony debt is +increased--even though no money has moved around yet. + + 10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + [Savings:Trip] $200.00 + [Assets:Checking] $-200.00 + + 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". + + +File: ledger.info, Node: Automated transactions, Next: Using Emacs to Keep Your Ledger, Prev: Virtual transactions, Up: Keeping a ledger + +3.10 Automated 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 transaction at the top of your ledger file: + + ; This automated entry will compute Huqúqu'lláh based on this + ; journal's transactions. Any that match will affect the + ; Liabilities:Huququ'llah account by 19% of the value of that + ; transaction. + + = /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ + (Liabilities:Huququ'llah) 0.19 + + This automated transaction works by looking at each transaction in +the ledger file. If any match the given value expression, 19% of the +transaction's value is applied to the `Liabilities:Huququ'llah' +account. So, if $1000 is earned from `Income:Salary', $190 is added to +`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 +`Liabilities:Huququ'llah'. That entry would look like: + + 2003/01/01 (101) Baha'i Huqúqu'lláh Trust + Liabilities:Huququ'llah $1,000.00 + Assets:Checking + + That's it. To see how much Huqúq is currently owed based on your +ledger entries, use: + + ledger balance Liabilities:Huquq + + 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: + + ledger -Q -t "/Liab.*Huquq/?(a/P{2.22 AU}<={-1.0}&a):a" -s bal liab + + 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: + + ledger -Q -T "/Liab.*Huquq/?(O/P{2.22 AU}<={-1.0}&O):O" -s bal liab + + In some cases, you may wish to refer to the account of whichever +transaction matched your automated entry's value expression. To do +this, use the special account name `$account': + + = /^Some:Long:Account:Name/ + [$account] -0.10 + [Savings] 0.10 + + This example causes 10% of the matching account's total to be +deferred to the `Savings' account--as a balanced virtual transaction, +which may be excluded from reports by using `--real'. + + +File: ledger.info, Node: Using Emacs to Keep Your Ledger, Next: Using GnuCash to Keep Your Ledger, Prev: Automated transactions, Up: Keeping a ledger + +3.11 Using Emacs to Keep Your Ledger +==================================== + +In the Ledger tarball is an Emacs module, `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: + + ; -*-ledger-*- + + And this in your `.emacs' file, after copying `ledger.el' to your +`site-lisp' directory: + + (load "ledger") + + Now when you edit your ledger file, it will be in `ledger-mode'. +`ledger-mode' adds these commands: + +*C-c C-a* + For quickly adding new entries based on the form of older ones (see + previous section). + +*C-c C-c* + Toggles the "cleared" flag of the transaction under point. + +*C-c C-d* + Delete the entry under point. + +*C-c C-r* + Reconciles an account by displaying the transactions in another + buffer, where simply hitting the spacebar will toggle the pending + flag of the transaction in the ledger. Once all the appropriate + transactions have been marked, press C-c C-c in the reconcile + buffer to "commit" the reconciliation, which will mark all of the + entries as cleared, and display the new cleared balance in the + minibuffer. + +*C-c C-m* + Set the default month for new entries added with C-c C-a. This is + handy if you have a large number of transactions to enter from a + previous month. + +*C-c C-y* + Set the default year for new entries added with C-c C-a. This is + handy if you have a large number of transactions to enter from a + previous year. + + Once you enter the reconcile buffer, there are several key commands +available: + +*RET* + Visit the ledger file entry corresponding to the reconcile entry. + +*C-c C-c* + Commit the reconcialation. This marks all of the marked + transactions as "cleared", saves the ledger file, and then + displays the new cleared balance. + +*C-l* + Refresh the reconcile buffer by re-reading transactions from the + ledger data file. + +*SPC* + Toggle the transaction under point as cleared. + +*a* + Add a new entry to the ledger data file, and refresh the reconcile + buffer to include its transactions (if the entry is added to the + same account as the one being reconciled). + +*d* + Delete the entry related to the transaction under point. Note: + This may result in multiple transactions being deleted. + +*n* + Move to the next line. + +*p* + Move to the previous line. + +*C-c C-r* + +*r* + Attempt to auto-reconcile the transactions to the entered balance. + If it can do so, it will mark all those transactions as pending + that would yield the specified balance. + +*C-x C-s* + +*s* + Save the ledger data file, and show the current cleared balance for + the account being reconciled. + +*q* + Quit the reconcile buffer. + + There is also an `emacs' command which can be used to output reports +in a format directly `read'-able from Emacs Lisp. + + +File: ledger.info, Node: Using GnuCash to Keep Your Ledger, Next: Using timeclock to record billable time, Prev: Using Emacs to Keep Your Ledger, Up: Keeping a ledger + +3.12 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. There is, at least, an Emacs mode that +makes editing Ledger's data files much easier. + + You are also 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, multi-megabyte +behemoth to edit their data, and only a one megabyte binary to query it? + + +File: ledger.info, Node: Using timeclock to record billable time, Prev: Using GnuCash to Keep Your Ledger, Up: Keeping a ledger + +3.13 Using timeclock to record billable time +============================================ + +The timeclock tool makes it easy to track time events, like clocking +into and out of a particular job. These events accumulate in a timelog +file. + + Each in/out event may have an optional description. If the "in" +description is a ledger account name, these in/out pairs may be viewed +as virtual transactions, adding time commodities (hours) to that +account. + + For example, the command-line version of the timeclock tool could be +used to begin a timelog file like: + + export TIMELOG=$HOME/.timelog + ti ClientOne category + sleep 10 + to waited for ten seconds + + The `.timelog' file now contains: + + i 2004/10/06 15:21:00 ClientOne category + o 2004/10/06 15:21:10 waited for ten seconds + + Ledger parses this directly, as if it had seen the following entry: + + 2004/10/06 category + (ClientOne) 10s + + 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: + + 2004/11/01 (INV#1) ClientOne, Inc. + Receivable:ClientOne $0.10 + ClientOne -0.00277h @ $35.00 + + 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: + + 2004/12/01 ClientOne, Inc. + Assets:Checking $0.10 + Receivable:ClientOne + + 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 `!include' my timelog at the top of my company's +accounting ledger, with the attached prefix `Billable': + + ; -*-ledger-*- + + ; This is the ledger file for my company. But first, include the + ; timelog data, entering all of the time events within the umbrella + ; account "Billable". + + !account Billable + !include /home/johnw/.timelog + !end + + ; Here follows this fiscal year's transactions for the company. + + 2004/11/01 (INV#1) ClientOne, Inc. + Receivable:ClientOne $0.10 + Billable:ClientOne -0.00277h @ $35.00 + + 2004/12/01 ClientOne, Inc. + Assets:Checking $0.10 + Receivable:ClientOne + + +File: ledger.info, Node: Using XML, Prev: Keeping a ledger, Up: Top + +4 Using XML +*********** + +By default, Ledger uses a human-readable data format, and displays its +reports in a manner meant to be read on screen. For the purpose of +writing tools which use Ledger, however, it is possible to read and +display data using XML. This chapter documents that format. + + The general format used for Ledger data is: + + + + ... + ... + ...... + + + The data stream is enclosed in a `ledger' tag, which contains a +series of one or more entries. Each `entry' describes the entry and +contains a series of one or more transactions: + + + 2004/03/01 + + 100 + John Wiegley + + ... + ... + ...... + + + + The date format for `en:date' is always `YYYY/MM/DD'. The +`en:cleared' tag is optional, and indicates whether the transaction has +been cleared or not. There is also an `en:pending' tag, for marking +pending transactions. The `en:code' and `en:payee' tags both contain +whatever text the user wishes. + + After the initial entry data, there must follow a set of transactions +marked with `en:transactions'. Typically these transactions will all +balance each other, but if not they will be automatically balanced into +an account named `'. + + Within the `en:transactions' tag is a series of one or more +`transaction''s, which have the following form: + + + Expenses:Computer:Hardware + + + + $ + 90.00 + + + + + + This is a basic transaction. It may also be begin with `tr:virtual' +and/or `tr:generated' tags, to indicate virtual and auto-generated +transactions. Then follows the `tr:account' tag, which contains the +full name of the account the transaction is related to. Colons +separate parent from child in an account name. + + Lastly follows the amount of the transaction, indicated by +`tr:amount'. Within this tag is a `value' tag, of which there are four +different kinds, each with its own format: + + 1. boolean + + 2. integer + + 3. amount + + 4. balance + + The format of a boolean value is `true' or `false' surrounded by a +`boolean' tag, for example: + + true + + The format of an integer value is the numerical value surrounded by +an `integer' tag, for example: + + 12036 + + The format of an amount contains two members, the commodity and the +quantity. The commodity can have a set of flags that indicate how to +display it. The meaning of the flags (all of which are optional) are: + +*P* + The commodity is prefixed to the value. + +*S* + The commodity is separated from the value by a space. + +*T* + Thousands markers are used to display the amount. + +*E* + The format of the amount is European, with period used as a + thousands marker, and comma used as the decimal point. + + The actual quantity for an amount is an integer of arbitrary size. +Ledger uses the GNU multi-precision math library to handle such values. +The XML format assumes the reader to be equally capable. Here is an +example amount: + + + + $ + 90.00 + + + + Lastly, a balance value contains a series of amounts, each with a +different commodity. Unlike the name, such a value does need to +balance. It is called a balance because it sums several amounts. For +example: + + + + + $ + 90.00 + + + DM + 200.00 + + + + + That is the extent of the XML data format used by Ledger. It will +output such data if the `xml' command is used, and can read the same +data as long as the `expat' library was available when Ledger was built. + + + +Tag Table: +Node: Top1705 +Node: Introduction3383 +Ref: Introduction-Footnote-19312 +Node: Building the program9389 +Node: Getting help9936 +Node: Running Ledger10346 +Node: Usage overview11866 +Ref: Usage overview-Footnote-145337 +Ref: Usage overview-Footnote-245455 +Node: Commands45560 +Node: Options50789 +Node: Basic options51650 +Node: Report filtering53835 +Node: Output customization57715 +Node: Commodity reporting62620 +Node: Environment variables64718 +Node: Format strings65366 +Node: Value expressions70738 +Node: Period expressions77069 +Node: File format78657 +Node: Some typical queries83527 +Node: Budgeting and forecasting87249 +Node: Keeping a ledger89989 +Node: Stating where money goes92698 +Node: Assets and Liabilities95351 +Node: Commodities and Currencies103496 +Node: Accounts and Inventories109656 +Node: Understanding Equity111251 +Node: Dealing with Petty Cash113158 +Node: Working with multiple funds and accounts114255 +Node: Archiving previous years118971 +Node: Virtual transactions121495 +Node: Automated transactions123171 +Node: Using Emacs to Keep Your Ledger126169 +Node: Using GnuCash to Keep Your Ledger129240 +Node: Using timeclock to record billable time130140 +Node: Using XML132900 + +End Tag Table + + +Local Variables: +coding: iso-8859-1 +End: --- ledger-2.6.2.orig/gnucash.cc +++ ledger-2.6.2/gnucash.cc @@ -201,7 +201,7 @@ { const char * num = number.c_str(); - if (char * p = std::strchr(num, '/')) { + if (const char * p = std::strchr(num, '/')) { std::string numer_str(num, p - num); std::string denom_str(p + 1); --- ledger-2.6.2.orig/debian/dirs +++ ledger-2.6.2/debian/dirs @@ -0,0 +1,2 @@ +usr/bin +usr/share/emacs/site-lisp --- ledger-2.6.2.orig/debian/info +++ ledger-2.6.2/debian/info @@ -0,0 +1 @@ +ledger.info --- ledger-2.6.2.orig/debian/compat +++ ledger-2.6.2/debian/compat @@ -0,0 +1 @@ +6 --- ledger-2.6.2.orig/debian/copyright +++ ledger-2.6.2/debian/copyright @@ -0,0 +1,45 @@ +This package was debianized by Matt Palmer on Tue, 10 +Jun 2008 18:44:40 +1000. + +It was downloaded from + + +Upstream Author: + + John Wiegley + +Copyright: + + Copyright (c) 2003-2006, John Wiegley. + +License: + + 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. + +The Debian packaging is (C) 2008 Matt Palmer and +is licensed under the GPL, see `/usr/share/common-licenses/GPL'. --- ledger-2.6.2.orig/debian/emacsen-startup +++ ledger-2.6.2/debian/emacsen-startup @@ -0,0 +1,7 @@ +;;; 50ledger.el -- debian emacs setups for ledger. -*- mode: emacs-lisp -*- + +(if (not (file-exists-p "/usr/share/emacs/site-lisp/ledger.el")) + (message "ledger removed but not purged, skipping setup") + + ;; per autoload cookie in ledger.el + (autoload 'ledger-mode "ledger" "A mode for editing ledger data files." t)) --- ledger-2.6.2.orig/debian/docs +++ ledger-2.6.2/debian/docs @@ -0,0 +1,2 @@ +NEWS +README --- ledger-2.6.2.orig/debian/control +++ ledger-2.6.2/debian/control @@ -0,0 +1,17 @@ +Source: ledger +Section: utils +Priority: optional +Maintainer: Matt Palmer +Build-Depends: debhelper (>= 6), autotools-dev, libgmp-dev, libpcre3-dev, + libexpat1-dev, libofx-dev, texinfo, texlive +Standards-Version: 3.9.1 +Homepage: http://newartisans.com/software/ledger.html + +Package: ledger +Architecture: any +Depends: ${shlibs:Depends}, ${misc:Depends} +Description: command-line double-entry accounting program + Ledger is a powerful and flexible double-entry accounting system run + entirely from the command line. Your accounts ledger is stored in one or + more plain-text files with a very simple and readable format, and ledger + does the hard work of balancing your books and reporting. --- ledger-2.6.2.orig/debian/examples +++ ledger-2.6.2/debian/examples @@ -0,0 +1,2 @@ +sample.dat +scripts --- ledger-2.6.2.orig/debian/ledger.1 +++ ledger-2.6.2/debian/ledger.1 @@ -0,0 +1,613 @@ +.\" Copyright (c) 2003-2009, 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. +.TH LEDGER 1 2009-08-06 "Ledger 2.6.2" +.SH NAME +ledger \- command-line accounting +.SH SYNOPSIS +.B ledger +.RI [ options ] " command " [ acct-regex "]... [\-\- " payee-regex ...] +.SH DESCRIPTION +Ledger is a command-line 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. +.SH NOTE +This man page is a summary of the command-line usage of +.B ledger +along with a short example of a Ledger data file. +For more complete documentation see the Ledger Reference Manual, (via +the +.B info ledger +command or otherwise). +.SH COMMANDS +All commands require a Ledger data file which can be specified with +.BI -f "\ filename" +or via the +.B LEDGER_FILE +environment variable. + +The +.BR balance " and " register +commands provide the primary functionality of Ledger and are used most +frequently: +.RS 4 +.TP 4 +.BR bal ", " balance " [REGEXP]..." +Reports the current balance of all matching accounts. +If an account contains multiple types of commodities, each +commodity's total is reported separately. +.TP +.BR reg ", " register " [REGEXP]..." +Displays all the transactions occurring in the matching accounts, line +by line. +The output from +.B 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. +.RE + +Several commands are effectively variants of +.BR register . +These commands accept the same options and display the same +transactions as +.B register +and differ only in the format of the output: +.RS 4 +.TP 4 +.BR print " [REGEXP]..." +Displays transactions in a format that can be parsed by Ledger. +They will be properly formatted and output in the most economic form +possible. +The +.B print +command can be a handy way to clean up a Ledger file whose formatting +has gotten out of hand. +.TP +.BR xml " [REGEXP]..." +Displays transactions in an XML format that can then be read and +processed by external tools. +Use the +.B \-\-totals +option to include the running total with each transaction. +.TP +.BR emacs " [REGEXP]..." +Displays transactions in a format that can be read directly by Emacs +Lisp. +.RE + +The remaining commands are each useful in particular circumstances: +.RS 4 +.TP 4 +.BR equity " [REGEXP]..." +Prints out account balances as if they were entries. +This makes it easy to establish the starting balances for accounts, +(such as when beginning a new Ledger file to then archive previous +years). +.TP +.BR prices " [REGEXP]..." +Displays the price history for matching commodities. +The +.B \-A +option is useful with this report to display the average running +price, or +.B \-D +to show each price's deviation from that average. +.TP +.BR pricedb " [REGEXP]..." +Produces the same information as +.B prices +but in a format that can be parsed by Ledger. +.TP +.BI entry " DATE PAYEE AMOUNT" +Output a derived entry, based on the arguments and an account matching +.I PAYEE +in the transacation history. If Ledger does not succeed in generating +a new entry, an error is printed and the exit code is set to 1. +.RE +.SH OPTIONS +\ +.SS Basic options +.TP +.B \-h, \-\-help +Print a summary of the basic options and commands. +This help screen is also printed if +.B ledger +is run without a command. +.TP +.B \-H, \-\-full-help +Print a help message including all command-line options. +.TP +.B \-v, \-\-version +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. +.TP +.BI \-f,\ \-\-file \ FILE +Reads +.I FILE +as a Ledger file. +Typically, the environment variable +.B LEDGER_FILE +is set rather than using this command-line option. +.TP +.BI \-o,\ \-\-output \ FILE +Redirects output from any command to +.IR FILE \. +By default, all output goes to standard output. +.TP +.BI \-i,\ \-\-init\-file\ FILE +Causes +.I FILE +to be read by +.B 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, but put each option on it's own line. +Option settings on the command-line or in the environment always take +precedence over settings in the init file. +The default init file is +.BR ~/.ledgerrc \. +.TP +.BI \-\-cache\ FILE +Identifies +.I FILE +as the default binary cache file. +That is, whenever a command is finished a binary copy of the input +files 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 +.B LEDGER_CACHE +or by putting the option into your init file. +.TP +.B \-\-no\-cache +Causes Ledger to always ignore the binary cache. +.TP +.BI \-a,\ \-\-account\ NAME +Specifies the default account which QIF file transactions are assumed +to relate to. +.SS Report filtering options +These options change which transactions affect the outcome of a +report, in ways other than just using regular expressions: +.TP +.B \-c,\ \-\-current +Displays only entries occurring on or before the current date. +.TP +.BI \-b,\ \-\-begin\ DATE +Constrains the report to entries on or after +.IR DATE \. +Only entries after that date will be calculated, which means that the +running total in the balance report will always start at zero with the +first matching entry. +Note: This is different from using +.B \-\-display +to constrain what is displayed. +.TP +.BI \-e,\ \-\-end\ DATE +Constrains the report so that entries on or after +.I DATE +are not considered. +The ending date is inclusive. +.TP +.BI \-p,\ \-\-period\ STR +Sets the reporting period to +.IR STR \. +This will subtotal all matching entries within each period separately, +making it easy to see +.BR weekly ,\ monthly ,\ quarterly , +etc. transaction totals. +A period string can even specify the beginning and end of the report +range, using simple terms like +.B last june +or +.BR "next month" \. +For more using period expressions, see the Period Expressions section +of the Ledger Reference Manual. +.TP +.BI \-\-period\-sort\ EXPR +Sorts the transactions within each reporting period using the value +expression +.IR EXPR \. +This is most often useful when reporting monthly expenses. +For example, to view the highest expense categories at the top of each +month use: + +.B "ledger -M --period-sort -At reg ^Expenses" +.TP +.B \-C, \-\-cleared +Displays only transactions whose entry has been marked cleared (by +placing an asterix to the right of the date). +.TP +.B \-U, \-\-uncleared +Displays only transactions whose entry has not been marked cleared +(i.e., if there is no asterix to the right of the date). +.TP +.B \-R, \-\-real +Displays only real transactions, not virtual. +A virtual transaction is indicated by surrounding the account name +with parentheses or brackets, (see the Ledger Reference Manual for +more on using virtual transactions). +.TP +.B \-L, \-\-actual +Displays only actual transactions, and not those created due to +automated transactions. +.TP +.B \-r, \-\-related +Displays transactions that are related to whichever transactions would +otherwise have matched the filtering criteria. +In the register report, this shows where money went to, or the account +it came from. +In the balance report, it shows all the accounts affected by entries +having a related transaction. +.TP +.B \-\-budget +Display budgeted transactions only. +.TP +.B \-\-add\-budget +Shows both budgeted and unbudgeted transactions. +This option is useful for displaying how close your actual +transactions meet your budget. +.TP +.B \-\-unbudgeted +Show only unbudgeted transactions. +.TP +.BI \-\-forecast\ EXPR +Projects your budget into the future, (while +.I EXPR +is true), showing how it will affect future balances. +.TP +.BI \-l,\ \-\-limit\ EXPR +Calculate only transactions matching +.IR EXPR \. +(See the Value Expressions section of Ledger Reference Manual for more +details on possible values of +.I EXPR +for this and other options.) +.TP +.BI \-t,\ \-\-amount\ EXPR +Sets the value expression used to calculate the value column in the +.B register +report, the account totals in the +.B balance +report, and the values printed in the +.B equity +report. +.TP +.BI \-T,\ \-\-total\ EXPR +Sets the value expression used for the +.B totals +column in the +.BR register " and " balance +reports. +.I EXPR +to calculate the displayed total. +.SS Output customization options +.TP +.B \-n,\ \-\-collapse +Causes entries in a +.B register +report with multiple transactions to be collapsed into a single, +subtotaled entry. +.TP +.B \-s,\ \-\-subtotal +Causes all entries in a +.B register +report to be collapsed into a single, subtotaled entry. +.TP +.B \-P,\ \-\-by\-payee +Reports subtotals by payee. +.TP +.B \-x,\ \-\-comm\-as\-payee +Changes the payee of every transaction to be the commodity used in +that transaction. +This can be useful when combined with other options, such as +.BR \-s,\ \-\-sort \. +.TP +.B \-E,\ \-\-empty +Includes even empty accounts in the +.B balance +report. +.TP +.B \-W,\ \-\-weekly +reports transaction totals by the week. +The week begins on whichever day of the week begins the month +containing that transaction. To set a specific begin date, use a +period string, such as +.B \-\-period weekly from +.IR DATE \. +.TP +.B \-M,\ \-\-monthly +Reports transaction totals by month. +.TP +.B \-Y,\ \-\-yearly +Reports transaction totals by year. +.TP +.B \-\-dow +Reports transactions totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. +.TP +.B \-S,\ \-\-sort EXPR +Sorts a report by comparing the values determined using the value +expression +.IR EXPR \. +For example, using +.B \-\-sort date +will sort by date, (useful if included files cover different date +ranges), and +.B \-\-sort \-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 the Value Expressions +section of the Ledger Reference Manual. +.TP +.B \-w,\ \-\-wide +Causes the default +.B register +report to assume 132 columns instead of 80. +.TP +.BI \-\-head\ COUNT +Show only the first +.I COUNT +entries. +If a negative amount is given, it will invert the meaning of the flag +(instead of the first five entries being printed, for example, it +would print all but the first five). +.TP +.BI \-\-tail\ COUNT +Show only the last +.I COUNT +entries. +If a negative amount is given, it will invert the meaning of the flag +(instead of the last five entries being printed, for example, it +would print all but the last five). +.TP +.B \-\-pager PAGER +Tells +.B 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 +.B LEDGER_PAGER +environment variable. +.TP +.B \-A,\ \-\-average +Reports the average transaction value. +.TP +.B \-D,\ \-\-deviation +Reports each transaction's deviation from the average. +It is only meaningful in the +.BR register " and " prices +reports. +.TP +.B \-%,\ \-\-percentage +Shows account subtotals in the +.B balance +report as percentages of the parent account. +.TP +.B \-\-totals +Include running total information in the +.B xml +report. +.TP +.B \-j,\ \-\-amount\-data +Changes the +.B 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. +.TP +.B \-J,\ \-\-total\-data +Changes the +.B register +report so that it outputs nothing but the date and totals column, +without commodities. +.TP +.BI \-d,\ \-\-display\ EXPR +Limits which transactions or accounts or actually displayed in a +report. +They might still be calculated, and be part of the running total of a +register report, for example, but they will not be displayed. +.TP +.BI \-y,\ \-\-date\-format\ 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 +.BR %Y/%m/%d \. +To change the way dates are printed in general, the easiest way is to +put +.BI \-\-date\-format\ FORMAT +in the Ledger initialization file +.B ~/.ledgerrc +(or the file referred to by +.BR LEDGER_INIT ). +.TP +.BI \-F,\ \-\-format\ STR +Sets the reporting format for whatever report ledger is about to make. +See the Format Strings section of the Ledger Reference Manual for details. +.SS Commodity price options +These options affect how commodity values are displayed: +.TP +.BI \-\-price\-db\ FILE +Sets the file that is used for recording downloaded commodity prices. +It is always read on startup, to determine historical prices. +The default file is +.BR ~/.pricedb \. +.TP +.BI \-L,\ \-\-price\-exp\ 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 +.B \-\-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. +(Default value is 1440 minutes.) +.TP +.B \-Q,\ \-\-download +Causes quotes to be automatically downloaded, as needed, by running a +script named +.B getquote +and expecting that script to return a value understood by ledger. +A sample implementation of a +.B 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 +.BR LEDGER_PRICE_DB \. +.SS Commodity reporting options +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 +.BR \-t " and " \-T +options. +However, there are also several standard reports, which will satisfy +most users' basic reporting needs: +.TP +.B \-O,\ \-\-quantity +Reports commodity totals (this is the default). +.TP +.B \-B,\ \-\-basis +Reports the cost basis for all transactions. +.TP +.B \-V,\ \-\-market +Reports the last known market value for all commodities. +.TP +.B \-g,\ \-\-performance +Reports the net gain/loss for each transaction in a +.B register +report. +.TP +.B \-G,\ \-\-gain +Reports the net gain/loss for all commodities in the report that have +a price history. +.SH ENVIRONMENT +Every option to ledger may be set using an environment variable. If +an option has a long name such as +.B \-\-this\-option +then setting the +environment variable +.B LEDGER_THIS_OPTION +will have the same effect 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 +.B ~/.ledgerrc +by default, (or the file specified by the +.B LEDGER_INIT_FILE +environment variable). + +Of special note is the +.B LEDGER_FILE +environment variable which almost all users of Ledger will find convenient: +.TP +.B LEDGER_FILE +Set to a file, to be read by the +.B ledger +command. +This avoids the requirement to pass +.BI \-\-file\ FILE +to every invocation of +.BR ledger \. +.SH EXAMPLE +Here is sample data file +.RB ( ledger.dat +from the distribution) demonstrating most of the features of the +ledger data-file format. +These include comments +.RB ( ; ), +automated transactions +.RB ( = ), +virtual transactions ( +.BI ( "account-name" ) +), periodic (budget) transactions +.RB ( ~ ), +cleared transactions +.RB ( * ), +commodity transactions +.RI ( SYMBOL +.BR @ ), +and check numbers ( +.BI ( NUMBER ) +). +.in +4n +.nf + +; Sample file ledger.dat + +; An automated transaction to a virtual account += /^Expenses:Books/ + (Liabilities:Taxes) -0.10 + +; A periodic (budget) transaction +~ Monthly + Assets:Bank:Checking $500.00 + Income:Salary + +; A cleared transaction +2004/05/01 * Checking balance + Assets:Bank:Checking $1,000.00 + Equity:Opening Balances + +; A transaction involving multiple commodities +2004/05/01 * Investment balance + Assets:Brokerage 50 AAPL @ $30.00 + Equity:Opening Balances + +2004/05/14 * Pay day + Assets:Bank:Checking $500.00 + Income:Salary + +2004/05/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard + +; A transaction with a check number +2004/05/27 (100) Credit card company + Liabilities:MasterCard $20.00 + Assets:Bank:Checking + +.fi +.in +.SH SEE ALSO +The Ledger Reference Manual available via +.B info ledger +if +.BR ledger " and " info +are properly installed. + +The ledger homepage: +.B http://wiki.github.com/jwiegley/ledger --- ledger-2.6.2.orig/debian/changelog +++ ledger-2.6.2/debian/changelog @@ -0,0 +1,73 @@ +ledger (2.6.2-3.1) unstable; urgency=low + + * NMU. Change dependency libgmp3-dev --> libgmp-dev. + + -- Steve M. Robbins Thu, 17 Mar 2011 21:56:30 -0500 + +ledger (2.6.2-3) unstable; urgency=low + + * Ack NMU from Margarita Manterola, fixing #576660. + * Apply patch to ledger.el from David Maus to fix some sort of reconciling + buffer problem. Closes: #605429. + * Update docs to clarify that options in ~/.ledgerrc must be placed on + separate lines. Closes: #605810. + * Update docs to remove unwarranted optimism about the --file option + (It doesn't take a colon-separated list of files, and you can't specify + it more than once). Closes: #605807. + * Bump standards version; no changes required. + + -- Matt Palmer Fri, 10 Dec 2010 12:41:20 +1100 + +ledger (2.6.2-2.1) unstable; urgency=low + + * Non-maintainer upload to fix generation of unneeded dir.gz info file. + * Changed debian/rules to remove /usr/share/info/dir before building the + package. Closes: #576660. + + -- Margarita Manterola Sat, 24 Apr 2010 19:06:01 +0000 + +ledger (2.6.2-2) unstable; urgency=low + + * CONSTipate gnucash.cc, textual.cc, and option.cc, so it builds with GCC + 4.4. Thanks to Stefan Ebner for the patch. Closes: #547303. + * Install a man page (this will become redundant once 3.0 comes out, but + until then...). Thanks to Carl Worth for the manpage. Closes: #540409. + * Install emacs mode for ledger (ledger.el); untested, as I have no emacs + fu, but here's hoping... Thanks to Kevin Ryde for the patch. + Closes: #554040. + * Bumped standards version; no changes required. + + -- Matt Palmer Sat, 26 Dec 2009 10:38:50 +1100 + +ledger (2.6.2-1) unstable; urgency=low + + * New upstream release. + + -- Matt Palmer Tue, 30 Jun 2009 18:47:07 +1000 + +ledger (2.6.1-3) unstable; urgency=low + + * Put sample.dat and the scripts directory in examples. Closes: #524976. + * Build and install the HTML docs as well. Just Because. + + -- Matt Palmer Tue, 28 Apr 2009 19:52:52 +1000 + +ledger (2.6.1-2) unstable; urgency=low + + * Update README to point to new mailing list. Closes: #513414 + * Build and install the PDF documentation. Closes: #513416 + + -- Matt Palmer Sat, 31 Jan 2009 15:04:13 +1100 + +ledger (2.6.1-1) unstable; urgency=low + + * New upstream release. + + -- Matt Palmer Thu, 18 Sep 2008 10:11:27 +1000 + +ledger (2.6.0.90-1) unstable; urgency=low + + * Initial release (Closes: #405011) + + -- Matt Palmer Tue, 10 Jun 2008 18:44:40 +1000 + --- ledger-2.6.2.orig/debian/rules +++ ledger-2.6.2/debian/rules @@ -0,0 +1,105 @@ +#!/usr/bin/make -f +# -*- makefile -*- +# Sample debian/rules that uses debhelper. +# This file was originally written by Joey Hess and Craig Small. +# As a special exception, when this file is copied by dh-make into a +# dh-make output file, you may use that output file without restriction. +# This special exception was added by Craig Small in version 0.37 of dh-make. + +# Uncomment this to turn on verbose mode. +#export DH_VERBOSE=1 + +# These are used for cross-compiling and for saving the configure script +# from having to guess our platform (since we know it already) +DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE) +DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE) +ifneq ($(DEB_HOST_GNU_TYPE),$(DEB_BUILD_GNU_TYPE)) +CROSS= --build $(DEB_BUILD_GNU_TYPE) --host $(DEB_HOST_GNU_TYPE) +else +CROSS= --build $(DEB_BUILD_GNU_TYPE) +endif + +config.status: configure + dh_testdir + # Add here commands to configure the package. +ifneq "$(wildcard /usr/share/misc/config.sub)" "" + cp -f /usr/share/misc/config.sub config.sub +endif +ifneq "$(wildcard /usr/share/misc/config.guess)" "" + cp -f /usr/share/misc/config.guess config.guess +endif + ./configure $(CROSS) --prefix=/usr --mandir=\$${prefix}/share/man \ + --infodir=\$${prefix}/share/info \ + CFLAGS="$(CFLAGS)" # LDFLAGS="-Wl,-z,defs" + + +build: build-stamp + +build-stamp: config.status + dh_testdir + + # Add here commands to compile the package. + $(MAKE) + $(MAKE) ledger.pdf + $(MAKE) ledger.html + + touch $@ + +clean: + dh_testdir + dh_testroot + rm -f build-stamp + + # Add here commands to clean up after the build process. + [ ! -f Makefile ] || $(MAKE) distclean + rm -f config.sub config.guess + + dh_clean + +install: build + dh_testdir + dh_testroot + dh_clean -k + dh_installdirs + + # Add here commands to install the package into debian/ledger. + $(MAKE) DESTDIR=$(CURDIR)/debian/ledger install + $(MAKE) DESTDIR=$(CURDIR)/debian/ledger install-pdf + $(MAKE) DESTDIR=$(CURDIR)/debian/ledger install-html + + # Clean out some stuff that make install puts in that we don't want + rm -rf $(CURDIR)/debian/ledger/usr/include + rm -rf $(CURDIR)/debian/ledger/usr/lib + rm -rf $(CURDIR)/debian/ledger/usr/share/info/dir + + # Install emacs mode for ledger. Not byte compiled. We don't + # install timeclock.el since it comes with emacs already and in + # particular the one with emacs 23.1 might be newer than with ledger + # 2.6.2 + cp -a ledger.el $(CURDIR)/debian/ledger/usr/share/emacs/site-lisp + +# Build architecture-independent files here. +binary-indep: build install +# We have nothing to do by default. + +# Build architecture-dependent files here. +binary-arch: build install + dh_testdir + dh_testroot + dh_installchangelogs + dh_installdocs + dh_installemacsen + dh_installexamples + dh_installinfo + dh_installman debian/ledger.1 + dh_strip + dh_compress + dh_fixperms + dh_installdeb + dh_shlibdeps + dh_gencontrol + dh_md5sums + dh_builddeb + +binary: binary-indep binary-arch +.PHONY: build clean binary-indep binary-arch binary install