From 465a37622f76b3855090245e4653141e869775cc Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 23 Nov 2008 01:55:19 -0800 Subject: reorganise the manual roughly into intro, reference, and detailed examples --- doc/ledger.texi | 3674 +++++++++++++++++++++++++++---------------------------- 1 file changed, 1837 insertions(+), 1837 deletions(-) diff --git a/doc/ledger.texi b/doc/ledger.texi index 9dc1ba4b..8e886477 100644 --- a/doc/ledger.texi +++ b/doc/ledger.texi @@ -61,12 +61,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @menu * Introduction:: -* Running Ledger:: -* Keeping a ledger:: -* Using XML:: +* Using Ledger:: +* Ledger in Practice:: @end menu -@node Introduction, Running Ledger, Top, Top +@node Introduction, Using Ledger, Top, Top @chapter Introduction Ledger is an accounting tool with the moxie to exist. It provides no @@ -223,8 +222,8 @@ https://lists.sourceforge.net/lists/listinfo/ledger-discuss You can also find help at the @samp{#ledger} channel on the IRC server @samp{irc.freenode.net}. -@node Running Ledger, Keeping a ledger, Introduction, Top -@chapter Running Ledger +@node Using Ledger, Ledger in Practice, Introduction, Top +@chapter Using Ledger Ledger has a very simple command-line interface, named---enticing enough---@command{ledger}. It supports a few reporting commands, and @@ -258,7 +257,6 @@ However, none of them are required to use the basic reporting commands. @menu -* Usage overview:: * Commands:: * Options:: * Format strings:: @@ -269,2479 +267,2481 @@ commands. * Budgeting and forecasting:: @end menu -@node Usage overview, Commands, Running Ledger, Running Ledger -@section Usage overview - -Before getting into the details of how to run Ledger, it will be -easier to introduce the features in the context of their typical -usage. To that end, this section presents a series of recipes, -gradually introducing all of the command-line features of Ledger. +@node Commands, Options, Using Ledger, Using Ledger +@section Commands -For the purpose of these examples, assume the environment variable -@var{LEDGER} is set to the file @file{sample.dat} (which is included -in the distribution), and that the contents of that file are: +@subsection balance -@smallexample -= /^Expenses:Books/ - (Liabilities:Taxes) -0.10 +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. -~ Monthly - Assets:Bank:Checking $500.00 - Income:Salary +@subsection register -2004/05/01 * Checking balance - Assets:Bank:Checking $1,000.00 - Equity:Opening Balances +The @command{register} command displays all the transactions occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +transactions that match. Very useful for hunting down a particular +transaction. -2004/05/01 * Investment balance - Assets:Brokerage 50 AAPL @@ $30.00 - Equity:Opening Balances +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +always be the same as the current balance of that account. -2004/05/14 * Pay day - Assets:Bank:Checking $500.00 - Income:Salary +If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script @file{report}, which is +included in the Ledger distribution. The only requirement is that you +add either @option{-j} or @option{-J} to your register command, in +order to plot either the amount or total column, respectively. -2004/05/27 Book Store - Expenses:Books $20.00 - Liabilities:MasterCard +@subsection print -2004/05/27 (100) Credit card company - Liabilities:MasterCard $20.00 - Assets:Bank:Checking -@end smallexample +The @command{print} command prints out ledger entries in a textual +format that can be parsed by Ledger. They will be properly formatted, +and output in the most economic form possible. The ``print'' command +also takes a list of optional regexps, which will cause only those +transactions which match in some way to be printed. -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. +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. -@subsection Checking balances +@subsection output -Ledger has seven basic commands, but by far the most often used are -@command{balance} and @command{register}. To see a summary balance of -all accounts, use: +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: @example -ledger bal +ledger -f FILENAME output FILENAME @end example -@command{bal} is a short-hand for @command{balance}. This command -prints out the summary totals of the five parent accounts used in -@file{sample.dat}: - -@smallexample - $1,480.00 - 50 AAPL Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - $-2.00 Liabilities --------------------- - $-1,502.00 - 50 AAPL -@end smallexample - -None of the child accounts are shown, just the parent account totals. -We can see that in @samp{Assets} there is $1,480.00, and 50 shares of -Apple stock. There is also a negative grand total. Usually the grand -total is zero, which means that all accounts balance@footnote{It is -impossible for accounts not to balance in ledger; it reports an error -if a transaction does not balance}. In this case, since the 50 shares -of Apple stock cost $1,500.00 dollars, then these two amounts balance -each other in the grand total. The extra $2.00 comes from a virtual -transaction being added by the automatic entry at the top of the file. -The entry is virtual because the account name was surrounded by -parentheses in an automatic entry. Automatic entries will be -discussed later, but first let's remove the virtual transaction from -the balance report by using the @option{--real} option: - -@example -ledger --real bal -@end example +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only entries contained +within that file will be output, and not an included entries (as can +happen with the @command{print} command). -Now the report is: +@subsection xml -@smallexample - $1,480.00 - 50 AAPL Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income --------------------- - $-1,500.00 - 50 AAPL -@end smallexample +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +transaction. -Since the liability was a virtual transaction, it has dropped from the -report and we see that final total is balanced. +@subsection emacs -But we only know that it balances because @file{sample.dat} is quite -simple, and we happen to know that the 50 shares of Apple stock cost -$1,500.00. We can verify that things really balance by reporting the -Apple shares in terms of their cost, instead of their quantity. To do -this requires the @option{--basis}, or @option{-B}, option: +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: @example -ledger --real -B bal +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of transactions + ...) ; list of entries @end example -This command reports: +@subsection equity -@smallexample - $2,980.00 Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income -@end smallexample +The @command{equity} command prints out accounts balances as if they +were entries. This makes it easy to establish the starting balances +for an account, such as when @ref{Archiving previous years}. -With the basis cost option, the grand total has disappeared, as it is -now zero. The confirms that the cost of everything balances to zero, -@emph{which must always be true}. Reporting the real basis cost -should never yield a remainder@footnote{If it ever does, then -generated transactions are involved, which can be removed using -@option{--actual}}. +@subsection prices -@subsubsection Sub-account balances +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +deviation from that average. -The totals reported by the balance command are only the topmost parent -accounts. To see the totals of all child accounts as well, use the -@option{-s} option: +There is also a @command{pricesdb} command which outputs the same +information as @command{prices}, but does in a format that can be +parsed by Ledger. -@example -ledger --real -B -s bal -@end example +@subsection entry -This reports: +The @command{entry} commands simplifies the creation of new entries. +It works on the principle that 80% of all transactions are variants of +earlier transactions. Here's how it works: + +Say you currently have this transaction in your ledger file: @smallexample - $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 +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 @end smallexample -This shows that the @samp{Assets} total is made up from two child -account, but that the total for each of the other accounts comes from -one child account. - -Sometimes you may have a lot of children, nested very deeply, but only -want to report the first two levels. This can be done with a display -predicate, using a value expression. In the value expression, -@code{T} represents the reported total, and @code{l} is the display -level for the account: +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{entry} command you can type: @example -ledger --real -B -d "T&l<=2" bal +ledger entry 2004/4/9 viva food 11 tips 2.50 @end example -This reports: +This produces the following output: @smallexample - $2,980.00 Assets - $1,480.00 Bank - $1,500.00 Brokerage - $-2,500.00 Equity:Opening Balances - $20.00 Expenses:Books - $-500.00 Income:Salary +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 @end smallexample -Instead of reporting @samp{Bank:Checking} as a child of @samp{Assets}, -it report only @samp{Bank}, since that account is a nesting level of -2, while @samp{Checking} is at level 3. - -To review the display predicate used---@code{T&l<=2}---this rather -terse expression means: Display an account only if it has a non-zero -total (@code{T}), and its nesting level is less than or equal to 2 -(@code{l<=2}). +It works by finding a past transaction matching the regular expression +@samp{viva}, and assuming that any accounts or amounts specified will +be similar to that earlier transaction. If Ledger does not succeed in +generating a new entry, an error is printed and the exit code is set +to @samp{1}. -@subsubsection Specific account balances +There is a shell script in the distribution's @file{scripts} directory +called @file{entry}, which simplifies the task of adding a new entry +to your ledger. It launches @command{vi} to confirm that the entry +looks appropriate. -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: +Here are a few more examples of the @command{entry} command, assuming +the above journal entry: @example -ledger bal checking +ledger entry 4/9 viva 11.50 +ledger entry 4/9 viva 11.50 checking # (from `checking') +ledger entry 4/9 viva food 11.50 tips 8 +ledger entry 4/9 viva food 11.50 tips 8 cash +ledger entry 4/9 viva food $11.50 tips $8 cash +ledger entry 4/9 viva dining "DM 11.50" @end example -Reports: +@node Options, Format strings, Commands, Using Ledger +@section Options -@smallexample - $1,480.00 Assets:Bank:Checking -@end smallexample - -Any number of names may be used: +With all of the reports, command-line options are useful to modify the +output generated. These command-line options always occur before the +command word. This is done to distinguish options from exclusive +regular expressions, which also begin with a dash. The basic form for +most commands is: @example -ledger bal checking broker liab +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] @end example -Reports: +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. -@smallexample - $1,480.00 Assets:Bank:Checking - 50 AAPL Assets:Brokerage - $-2.00 Liabilities -@end smallexample +@menu +* Basic options:: +* Report filtering:: +* Output customization:: +* Commodity reporting:: +* Environment variables:: +@end menu -In this case no grand total is reported, because you are asking for -specific account balances. +@node Basic options, Report filtering, Options, Options +@subsection Basic options -For those comfortable with regular expressions, any Perl regexp is -allowed: +These are the most basic command options. Most likely, the user will +want to set them using @ref{Environment variables}, instead of using +actual command-line options: -@example -ledger bal ^assets.*checking ^liab -@end example +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. -Reports: +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. -@smallexample - $1,480.00 Assets:Bank:Checking - $-2.00 Liabilities:Taxes -@end smallexample +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. FILE may also be a list of +file names separated by colons. Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. -@subsection The register report +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. -While the @command{balance} command can be very handy for checking -account totals, by far the most powerful of Ledger's reporting tools -is the @command{register} command. In fact, internally both commands -use the same logic, but report the results differently: -@command{balance} shows the summary totals, while @command{register} -reports each transaction and how it contributes to that total. +@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: -Paradoxically, the most basic form of @command{register} is almost -never used, since it displays every transaction: +@smallexample +--price-db ~/finance/.pricedb -@example -ledger reg -@end example +; ~/.ledgerrc ends here +@end smallexample -@command{reg} is a short-hand for @command{register}. This command -reports: +Option settings on the command-line or in the environment always take +precedence over settings in the init file. -@smallexample -2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 - Equity:Opening Balan.. $-1,000.00 0 -2004/05/01 Investment balance Assets:Brokerage 50 AAPL 50 AAPL - Equity:Opening Balan.. $-1,500.00 $-1,500.00 - 50 AAPL -2004/05/14 Pay day Assets:Bank:Checking $500.00 $-1,000.00 - 50 AAPL - Income:Salary $-500.00 $-1,500.00 - 50 AAPL -2004/05/27 Book Store Expenses:Books $20.00 $-1,480.00 - 50 AAPL - Liabilities:MasterCard $-20.00 $-1,500.00 - 50 AAPL - (Liabilities:Taxes) $-2.00 $-1,502.00 - 50 AAPL -2004/05/27 Credit card company Liabilities:MasterCard $20.00 $-1,482.00 - 50 AAPL - Assets:Bank:Checking $-20.00 $-1,502.00 - 50 AAPL -@end smallexample +@option{--cache FILE} identifies FILE as the default binary cache +file. That is, if the ledger files to be read are specified using the +environment variable @env{LEDGER_FILE}, then whenever a command is +finished a binary copy will be written to the specified cache, to +speed up the loading time of subsequent queries. This filename can +also be given using the environment variable @env{LEDGER_CACHE}, or by +putting the option into your init file. The @option{--no-cache} +option causes Ledger to always ignore the binary cache. -This rather verbose output shows every account transaction in -@file{sample.dat}, and how it affects the running total. The final -total is identical to what we saw with the plain @command{balance} -command. To see how things really balance, we can use @samp{--real --B}, just as we did with @command{balance}: +@option{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file transactions are assumed to relate to. -@example -ledger --real -B reg -@end example +@node Report filtering, Output customization, Basic options, Options +@subsection Report filtering -Reports: +These options change which transactions affect the outcome of a +report, in ways other than just using regular expressions: -@smallexample -2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 - Equity:Opening Balan.. $-1,000.00 0 -2004/05/01 Investment balance Assets:Brokerage $1,500.00 $1,500.00 - Equity:Opening Balan.. $-1,500.00 0 -2004/05/14 Pay day Assets:Bank:Checking $500.00 $500.00 - Income:Salary $-500.00 0 -2004/05/27 Book Store Expenses:Books $20.00 $20.00 - Liabilities:MasterCard $-20.00 0 -2004/05/27 Credit card company Liabilities:MasterCard $20.00 $20.00 - Assets:Bank:Checking $-20.00 0 -@end smallexample +@option{--current}(@option{-c}) displays only entries occurring on or +before the current date. -Here we see that everything balances to zero in the end, as it must. +@option{--begin DATE} (@option{-b DATE}) constrains the report to +entries on or after @var{DATE}. Only entries after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching entry. (Note: This +is different from using @option{--display} to constrain what is +displayed). -@subsubsection Specific register queries +@option{--end DATE} (@option{-e DATE}) constrains the report so that +entries on or after @var{DATE} are not considered. The ending date +is inclusive. -The most common use of the register command is to summarize -transactions based on the account(s) they affect. Using -@file{sample.dat} as as example, we could look at all book purchases -using: +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching entries within each +period separately, making it easy to see weekly, monthly, quarterly, +etc., transaction totals. A period string can even specify the +beginning and end of the report range, using simple terms like ``last +june'' or ``next month''. For more using period expressions, see +@ref{Period expressions}. + +@option{--period-sort EXPR} sorts the transactions within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: @example -ledger reg books +ledger -M --period-sort -At reg ^Expenses @end example -Reports: +@option{--cleared} (@option{-C}) displays only transactions whose entry +has been marked ``cleared'' (by placing an asterix to the right of the +date). + +@option{--uncleared} (@option{-U}) displays only transactions whose +entry has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). + +@option{--real} (@option{-R}) displays only real transactions, not +virtual. (A virtual transaction is indicated by surrounding the +account name with parentheses or brackets; see the section on using +virtual transactions for more information). + +@option{--actual} (@option{-L}) displays only actual transactions, and +not those created due to automated transactions. + +@option{--related} (@option{-r}) displays transactions that are +related to whichever transactions would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by entries having a related transaction. +For example, if a file had this entry: @smallexample -2004/05/29 Book Store Expenses:Books $20.00 $20.00 +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 @end smallexample -If a double-dash (@samp{--}) occurs in the list of regular -expressions, any following arguments are matched against payee names, -instead of account names: +And the register command was: @example -ledger reg ^liab -- credit +ledger -r register food @end example -Reports: +The following would be output, showing the transactions related to the +transaction that matched: @smallexample -2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00 +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 @end smallexample -There are many reporting options for tailoring which transactions are -found, and also how to summarize the various amounts and totals that -result. These are plumbed in greater depth below. +@option{--budget} is useful for displaying how close your transactions +meet your budget. @option{--add-budget} also shows unbudgeted +transactions, while @option{--unbudgeted} shows only those. +@option{--forecast} is a related option that projects your budget into +the future, showing how it will affect future balances. +@xref{Budgeting and forecasting}. -@subsection Selecting transactions +@option{--limit EXPR} (@option{-l EXPR}) limits which transactions +take part in the calculations of a report. -Although the easiest way to use the register is to report all the -transactions affecting a set of accounts, it can often result in more -information than you want. To cope with an ever-growing amount of -data, there are several options which can help you pinpoint your -report to exactly the transactions that interest you most. This is -called the ``calculation'' phase of Ledger. All of its related -options are documented under @option{--help-calc}. +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +used to calculate the ``value'' column in the @command{register} +report, the amount used to calculate account totals in the +@command{balance} report, and the values printed in the +@command{equity} report. @xref{Value expressions}. -@subsubsection By date +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. -@c -c, --current show only current and past entries (not future) +@node Output customization, Commodity reporting, Report filtering, Options +@subsection Output customization -@option{--current}(@option{-c}) displays entries occurring on or -before the current date. Any entry recorded for a future date will be -ignored, as if it had not been seen. This is useful if you happen to -pre-record entries, but still wish to view your balances in terms of -what is available today. +These options affect only the output, but not which transactions are +used to create it: -@c -b, --begin DATE set report begin date -@c -e, --end DATE set report end date +@option{--collapse} (@option{-n}) causes entries in a +@command{register} report with multiple transactions to be collapsed +into a single, subtotaled entry. -@option{--begin DATE} (@option{-b DATE}) limits the report to only -those entries occurring on or after @var{DATE}. The running total in -the register will start at zero with the first transaction, even if -there are earlier entries. +@option{--subtotal} (@option{-s}) causes all entries in a +@command{register} report to be collapsed into a single, subtotaled +entry. -To limit the display only, but still add earlier transactions to the -running total, use the display expression @samp{-d 'd>=[DATE]'}): +@option{--by-payee} (@option{-P}) reports subtotals by payee. -@example -ledger --basis -b may -d 'd>=[5/14]' reg ^assets -@end example +@option{--comm-as-payee} (@option{-x}) changes the payee of every +transaction to be the commodity used in that transaction. This can be +useful when combined with other options, such as @option{-s}. -Reports: +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. -@smallexample -2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 -2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 -@end smallexample +@option{--weekly} (@option{-W}) reports transaction totals by the +week. The week begins on whichever day of the week begins the month +containing that transaction. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports transaction totals by month; @option{--yearly} +(@option{-Y}) reports transaction totals by year. For more complex +period, using the @option{--period} option described above. -In this example, the displayed transactions start from @samp{5/14}, -but the calculated total starts from the beginning of @samp{may}. +@option{--dow} reports transactions totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. -@option{--end DATE} (@option{-e DATE}) states when reporting should -end, both calculation and display. The ending date is inclusive. +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +the values determined using the value expression @var{EXPR}. For +example, using @option{-S -UT} in the balance report will sort account +balances from greatest to least, using the absolute value of the +total. For more on how to use value expressions, see @ref{Value +expressions}. -The @var{DATE} argument to the @option{-b} and @option{-e} options can -be rather flexible. Assuming the current date to be November 15, -2004, then all of the following are equivalent: +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. -@example -ledger -b oct bal -ledger -b "this oct" bal -ledger -b 2004/10 bal -ledger -b 10 bal -ledger -b last bal -ledger -b "last month" bal -@end example +@option{--head} causes only the first N entries to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N transactions. @option{--tail} outputs only +the last N entries. Both options may be used simultaneously. If a +negative amount is given, it will invert the meaning of the flag +(instead of the first five entries being printed, for example, it +would print all but the first five). -@c -p, --period STR report using the given period -@c --period-sort EXPR sort each report period's entries by EXPR +@option{--pager} tells Ledger to pass its output to the given pager +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. -To constrain the report to a specific time period, use -@option{--period} (@option{-p}). A time period may have both a -beginning and an end, or neither, as well as a specified interval. -Here are a few examples: +@option{--average} (@option{-A}) reports the average transaction +value. -@example -ledger -p 2004 bal -ledger -p august bal -ledger -p "from aug to oct" bal -ledger -p "daily from 8/1 to 8/15" bal -ledger -p "weekly since august" bal -ledger -p "monthly from feb to oct" bal -ledger -p "quarterly in 2004" bal -ledger -p yearly bal -@end example +@option{--deviation} (@option{-D}) reports each transaction's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. -See @ref{Period expressions} for more on syntax. Also, all of the -options @option{-b}, @option{-e} and @option{-p} may be used together, -but whatever information occurs last takes priority. An example of -such usage (in a script, perhaps) would be: +@option{--percentage} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. + +@option{--totals} include running total information in the +@command{xml} report. + +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it output nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. + +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it output nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which transactions +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking transactions, against a running balance which +includes all transaction values: @example -ledger -b 2004 -e 2005 -p monthly reg ^expenses +ledger -d "d>=[last month]" reg checking @end example -This command is identical to: +The output from this command is very different from the following, +whose running total includes only transactions from the last month +onward: @example -ledger -p "monthly in 2004" reg ^expenses +ledger -p "last month" reg checking @end example -The transactions within a period may be sorted using -@option{--period-sort}, which takes a value expression. This is -similar to the @option{--sort} option, except that it sorts within -each period entry, rather than sorting all transactions in the report. -See the documentation on @option{--sort} below for more details. +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). -@subsubsection By status +@option{--date-format STR} (@option{-y STR}) changes the basic date +format used by reports. The default uses a date like 2004/08/01, +which represents the default date format of @samp{%Y/%m/%d}. To +change the way dates are printed in general, the easiest way is to put +@option{--date-format FORMAT} in the Ledger initialization file +@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). -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: +@option{--format STR} (@option{-F STR}) sets the reporting format for +whatever report ledger is about to make. @xref{Format strings}. +There are also specific format commands for each report type: -@table @option -@item -C, --cleared -Consider only cleared transactions. -@item -U, --uncleared -Consider only uncleared and pending transactions. -@item -R, --real -Consider only real (non-virtual) transactions. -@item -L, --actual -Consider only actual (non-automated) transactions. -@end table +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize -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. +@node Commodity reporting, Environment variables, Output customization, Options +@subsection Commodity reporting -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. +These options affect how commodity values are displayed: -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: +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: @example -ledger --budget --actual reg ^expenses +; Don't download quotes for the dollar, or timelog values +N $ +N h @end example -This command outputs all transactions affecting a budgeted account, -but without subtracting the budget amount (because the generated -transactions are suppressed with @option{--actual}). The report shows -how much you actually spent on budgeted items. +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. -@subsubsection By relationship +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. -@c -r, --related calculate report using related transactions +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: -Normally, a register report includes only the transactions that match -the regular expressions specified after the command word. For -example, to report all expenses: +@table @code +@item -O, --quantity +Reports commodity totals (this is the default) -@example -ledger reg ^expenses -@end example +@item -B, --basis +Reports the cost basis for all transactions. -This reports: +@item -V, --market +Reports the last known market value for all commodities. -@smallexample -2004/05/29 Book Store Expenses:Books $20.00 $20.00 -@end smallexample +@item -g, --performance +Reports the net gain/loss for each transaction in a @command{register} +report. -Using @option{--related} (@option{-r}) reports the transactions that -did not match your query, but only in entries that otherwise would -have matched. This has the effect of indicating where money came -from, or when to: +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. +@end table + +@node Environment variables, , Commodity reporting, Options +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. + +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: @example -ledger -r reg ^expenses +--cache /tmp/.mycache @end example -Reports: +@node Format strings, Value expressions, Options, Using Ledger +@section Format strings -@smallexample -2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00 -@end smallexample +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the +@option{--format} (@option{-F}) option. Within that string, +constructs are allowed which make it possible to display the various +parts of an account or transaction in custom ways. -@subsubsection By budget +Within a format strings, a substitution is specified using a percent +character (@samp{%}). The basic format of all substitutions is: -@c --budget generate budget entries based on FILE +@example +%[-][MIN WIDTH][.MAX WIDTH]EXPR +@end example -There is more information about budgeting and forecasting in -@ref{Budgeting and forecasting}. Basically, if you have any period -entries in your ledger file, you can use these options. A period -entry looks like: +If the optional minus sign (@samp{-}) follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text +will be at least that wide, perhaps wider. If a period and a maximum +width is given, the substituted text will never be wider than this, +and will be truncated to fit. Here are some examples: @example -~ Monthly - Assets:Bank:Checking $500.00 - Income:Salary +%-P An entry's payee, left justified +%20P The same, right justified, at least 20 chars wide +%.20P The same, no more than 20 chars wide +%-.20P Left justified, maximum twenty chars wide @end example -The difference from a regular entry is that the first line begins with -a tilde (~), and instead of a payee there's a period expression -(@ref{Period expressions}). Otherwise, a period entry is in every -other way the same as a regular entry. +The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: -With such an entry in your ledger file, the @option{--budget} option -will report only transactions that match a budgeted account. Using -@file{sample.dat} from above: +@table @code +@item % +Inserts a percent sign. -@example -ledger --budget reg ^income -@end example +@item t +Inserts the results of the value expression specified by @option{-t}. +If @option{-t} was not specified, the current report style's value +expression is used. -Reports: +@item T +Inserts the results of the value expression specified by @option{-T}. +If @option{-T} was not specified, the current report style's value +expression is used. -@smallexample -2004/05/01 Budget entry Income:Salary $500.00 $500.00 -2004/05/14 Pay day Income:Salary $-500.00 0 -@end smallexample +@item | +Inserts a single space. This is useful if a width is specified, for +inserting a certain number of spaces. -The final total is zero, indicating that the budget matched exactly -for the reported period. Budgeting is most often helpful with period -reporting; for example, to show monthly budget results use -@option{--budget -p monthly}. +@item _ +Inserts a space for each level of an account's depth. That is, if an +account has two parents, this construct will insert two spaces. If a +minimum width is specified, that much space is inserted for each level +of depth. Thus @samp{%5_}, for an account with four parents, will +insert twenty spaces. -@c --add-budget show all transactions plus the budget -@c --unbudgeted show only unbudgeted transactions +@item (EXPR) +Inserts the amount resulting from the value expression given in +parentheses. To insert five times the total value of an account, for +example, one could say @samp{%12(5*O)}. Note: It's important to put +the five first in that expression, so that the commodity doesn't get +stripped from the total. -The @option{--add-budget} option reports all matching transactions in -addition to budget transactions; while @option{--unbudgeted} shows -only those that don't match a budgeted account. To summarize: +@item [DATEFMT] +Inserts the result of formatting a transaction's date with a date +format string, exactly like those supported by @code{strftime}. For +example: @samp{%[%Y/%m/%d %H:%M:%S]}. -@table @option -@item --budget -Show transactions matching budgeted accounts. -@item --unbudgeted -Show transactions matching unbudgeted accounts. -@item --add-budget -Show both budgeted and unbudgeted transactions together (i.e., add the -generated budget transactions to the regular report). -@end table +@item S +Insert the pathname of the file from which the entry's data was read. -@c --forecast EXPR generate forecast entries while EXPR is true +@item B +Inserts the beginning character position of that entry within the file. -A report with the @option{--forecast} option will add budgeted -transactions while the specified value expression is true. For -example: +@item b +Inserts the beginning line of that entry within the file. -@example -ledger --forecast 'd<[2005] reg ^income -@end example +@item E +Inserts the ending character position of that entry within the file. -Reports: +@item e +Inserts the ending line of that entry within the file. -@smallexample -2004/05/14 Pay day Income:Salary $-500.00 $-500.00 -2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00 -2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00 -@end smallexample +@item D +By default, this is the same as @samp{%[%Y/%m%/d]}. The date format +used can be changed at any time with the @option{-y} flag, however. +Using @samp{%D} gives the user more control over the way dates are +output. -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: +@item d +This is the same as the @samp{%D} option, unless the entry has an +effective date, in which case it prints +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. -@example -ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp -@end example +@item X +If a transaction has been cleared, this inserts @samp{*} followed by a +space; otherwise nothing is inserted. -This reports balances projected income against projected expenses, -showing the resulting total in yearly intervals until 2008. For the -case of @file{sample.dat}, which has no budgeted expenses, the result -of the above command (in November 2004) is: +@item Y +This is the same as @samp{%X}, except that it only displays a state +character if all of the member transactions have the same state. -@smallexample -2004/01/01 - 2004/12/31 Income:Salary $-1,000.00 $-1,000.00 - Expenses:Books $20.00 $-980.00 -2005/01/01 - 2005/12/31 Income:Salary $-6,000.00 $-6,980.00 -2006/01/01 - 2006/12/31 Income:Salary $-6,000.00 $-12,980.00 -2007/01/01 - 2007/12/31 Income:Salary $-6,000.00 $-18,980.00 -2008/01/01 - 2008/01/01 Income:Salary $-500.00 $-19,480.00 -@end smallexample +@item C +Inserts the checking number for an entry, in parentheses, followed by +a space; if none was specified, nothing is inserted. -@subsubsection By value expression +@item P +Inserts the payee related to a transaction. -@c -l, --limit EXPR calculate only transactions matching EXPR +@item a +Inserts the optimal short name for an account. This is normally used +in balance reports. It prints a parent account's name if that name +has not been printed yet, otherwise it just prints the account's name. -Value expressions can be quite complex, and are treated more fully in -@ref{Value expressions}. They can be used for limiting a report with -@option{--limit} (@option{-l}). The following command report income -since august, but expenses since october: +@item A +Inserts the full name of an account. -@example -ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg -@end example +@item W +This is the same as @samp{%A}, except that it first displays the +transaction's state @emph{if the entry's transaction states are not +all the same}, followed by the full account name. This is offered as +a printing optimization, so that combined with @samp{%Y}, only the +minimum amount of state detail is printed. -The basic form of this value expression is @samp{(A&B)|(A&B)}. The -@samp{A} in each part matches against an account name with -@samp{/name/}, while each @samp{B} part compares the date of the -transaction (@samp{d}) with a specified month. The resulting report -will contain only transactions which match the value expression. +@item o +Inserts the ``optimized'' form of a transaction's amount. This is +used by the print report. In some cases, this inserts nothing; in +others, it inserts the transaction amount and its cost. It's use is +not recommend unless you are modifying the print report. -@c -t, --amount EXPR use EXPR to calculate the displayed amount -@c -T, --total EXPR use EXPR to calculate the displayed total +@item n +Inserts the note associated with a transaction, preceded by two spaces +and a semi-colon, if it exists. Thus, no none becomes an empty +string, while the note @samp{foo} is substituted as @samp{ ; foo}. -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: +@item N +Inserts the note associated with a transaction, if one exists. -@example -ledger -t 'a/2' reg ^exp -@end example +@item / +The @samp{%/} construct is special. It separates a format string +between what is printed for the first transaction of an entry, and +what is printed for all subsequent transactions. If not used, the +same format string is used for all transactions. +@end table -The @option{-t} option doesn't affect the running total, only how the -transaction amount is displayed. To change the running total, use -@option{-T}. In that case, you will likely want to use the total -(@samp{O}) instead of the amount (@samp{a}): +@node Value expressions, Period expressions, Format strings, Using Ledger +@section Value expressions + +Value expressions are an expression language used by Ledger to +calculate values used by the program for many different purposes: + +@enumerate +@item +The values displayed in reports +@item +For predicates (where truth is anything non-zero), to determine which +transactions are calculated (@option{-l}) or displayed (@option{-d}). +@item +For sorting criteria, to yield the sort key. +@item +In the matching criteria used by automated transactions. +@end enumerate + +Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +argument is whatever follows it. The following is a display predicate +that I use with the @command{balance} command: @example -ledger -T 'O/2' reg ^exp +ledger -d /^Liabilities/?T<0:UT>100 balance @end example -@subsection Massaging register output - -Even after filtering down your data to just the transactions you're -interested in, the default reporting method of one transaction per -line is often still too much. To combat this complexity, it is -possible to ask Ledger to report the details to you in many different -forms, summarized in various ways. This is the ``display'' phase of -Ledger, and is documented under @option{--help-disp}. +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. -@subsubsection Summarizing +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: -@c -n, --collapse register: collapse entries with multiple transactions +@example +ledger -d "d>[this month]" register checking +@end example -When multiple transactions relate to a single entry, they are reported -as part of that entry. For example, in the case of @file{sample.dat}: +This advantage to this command's complexity is that it prints the +running total in terms of all entries in the register. The following, +simpler command is similar, but totals only the displayed +transactions: @example -ledger reg -- book +ledger -b "this month" register checking @end example -Reports: +@subsection Variables -@smallexample -2004/05/29 Book Store Expenses:Books $20.00 $20.00 - Liabilities:MasterCard $-20.00 0 - (Liabilities:Taxes) $-2.00 $-2.00 -@end smallexample +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. -All three transactions are part of one entry, and as such the entry -details are printed only once. To report every entry on a single -line, use @option{-n} to collapse entries with multiple transactions: +@table @code +@item t +This maps to whatever the user specified with @option{-t}. In a +register report, @option{-t} changes the value column; in a balance +report, it has no meaning by default. If @option{-t} was not +specified, the current report style's value expression is used. -@example -ledger -n reg -- book -@end example +@item T +This maps to whatever the user specified with @option{-T}. In a +register report, @option{-T} changes the totals column; in a balance +report, this is the value given for each account. If @option{-T} was +not specified, the current report style's value expression is used. -Reports: +@item m +This is always the present moment/date. +@end table -@smallexample -2004/05/29 Book Store $-2.00 $-2.00 -@end smallexample +@subsubsection Transaction/account details -In the balance report, @option{-n} causes the grand total not to be -displayed at the bottom of the report. +@table @code +@item d +A transaction's date, as the number of seconds past the epoch. This +is always ``today'' for an account. -@c -s, --subtotal balance: show sub-accounts; other: show subtotals +@item a +The transaction's amount; the balance of an account, without +considering children. -If an account occurs more than once in a report, it is possible to -combine them all and report the total per-account, using @option{-s}. -For example, this command: +@item b +The cost of a transaction; the cost of an account, without its +children. -@example -ledger -B reg ^assets -@end example +@item v +The market value of a transaction, or an account without its children. -Reports: +@item g +The net gain (market value minus cost basis), for a transaction or an +account without its children. It is the same as @samp{v-b}. -@smallexample -2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 -2004/05/01 Investment balance Assets:Brokerage $1,500.00 $2,500.00 -2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 -2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 -@end smallexample +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. -But if the @option{-s} option is added, the result becomes: +@item n +The index of a transaction, or the count of transactions affecting an +account. -@smallexample -2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00 - Assets:Brokerage $1,500.00 $2,980.00 -@end smallexample +@item X +1 if a transaction's entry has been cleared, 0 otherwise. -When account subtotaling is used, only one entry is printed, and the -date and name reflect the range of the combined transactions. +@item R +1 if a transaction is not virtual, 0 otherwise. -@c -P, --by-payee show summarized totals by payee +@item Z +1 if a transaction is not automated, 0 otherwise. +@end table -With @option{-P}, transactions relating to the same payee are -combined. In this case, the date of the combined entry is that of the -latest transaction. +@subsubsection Calculated totals -@c -x, --comm-as-payee set commodity name as the payee, for reporting +@table @code +@item O +The total of all transactions seen so far, or the total of an account +and all its children. -@option{-x} changes the payee name for each transaction to be the same -as the commodity it uses. This can be especially useful combined with -other options, like @option{-P}. For example: +@item N +The total count of transactions affecting an account and all its +children. -@example -ledger -Px reg ^assets -@end example +@item B +The total cost of all transactions seen so far; the total cost of an +account and all its children. -Reports: +@item V +The market value of all transactions seen so far, or of an account and +all its children. -@smallexample -2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 -2004/05/01 AAPL Assets:Brokerage 50 AAPL $1,480.00 - 50 AAPL -@end smallexample +@item G +The total net gain (market value minus cost basis), for a series of +transactions, or an account and its children. It is the same as +@samp{V-B}. +@end table -This reports shows the subtotal for each commodity held, and where it -is located. To see the basis cost, or initial investment, add -@option{-B}. Applied to the example above: +@subsection Functions -@smallexample -2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 -2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00 -@end smallexample +The available one letter functions are: -@c -E, --empty balance: show accounts with zero balance +@table @code +@item - +Negates the argument. -The only other options which affect summarized totals is @option{-E}, -which works only in the balance report. In this case, it shows -matching accounts with a zero a balance, which are ordinarily -excluded. This can be useful to see all the accounts involved in a -report, even if some have no total. +@item U +The absolute (unsigned) value of the argument. -@subsubsection Quick periods +@item S +Strips the commodity from the argument. -Although the @option{-p} option (also @option{--period}) is much more -versatile, there are other options to make the most common period -reports easier: +@item A +The arithmetic mean of the argument; @samp{Ax} is the same as +@samp{x/n}. -@table @option -@item -W, --weekly -Show weekly sub-totals. Same as @samp{-p weekly}. -@item -M, --monthly -Show monthly sub-totals. Same as @samp{-p monthly}. -@item -Y, --yearly -Show yearly sub-totals. Same as @samp{-p yearly}. +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. If no date +is given, then the current moment is used. @end table -@c --dow show a days-of-the-week report - -There is one kind of period report cannot be done with @option{-p}. -This is the @option{--dow}, or ``days of the week'' report, which -shows summarized totals for each day of the week. The following -examples shows a ``day of the week'' report of income and expenses: +@subsection Operators -@example -ledger --dow reg ^inc ^exp -@end example +The binary and ternary operators, in order of precedence, are: -Reports: +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate -@smallexample -2004/05/27 Thursdays Expenses:Books $20.00 $20.00 -2004/05/14 Fridays Income:Salary $-500.00 $-480.00 -@end smallexample +@subsection Complex expressions -@subsubsection Ordering and width +More complicated expressions are possible using: -@c -S, --sort EXPR sort report according to the value expression EXPR +@table @code +@item NUM +A plain integer represents a commodity-less amount. -The transactions displayed in a report are shown in the same order as -they appear in the ledger file. To change the order and sort a -report, use the @option{--sort} option. @option{--sort} takes a value -expression to determine the value to sort against, making it possible -to sort according to complex criteria. Here are some simple and -useful examples: +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. -@example -ledger --sort d reg ^exp # sort by date -ledger --sort t reg ^exp # sort by amount total -ledger --sort -t reg ^exp # reverse sort by amount total -ledger --sort Ut reg ^exp # sort by abs amount total -@end example +@item /REGEXP/ +@item W/REGEXP/ +A regular expression that matches against an account's full name. If +a transaction, this will match against the account affected by the +transaction. -For the balance report, you will want to use @samp{T} instead of -@samp{t}: +@item //REGEXP/ +@item p/REGEXP/ +A regular expression that matches against an entry's payee name. -@example -ledger --sort T reg ^exp # sort by amount total -ledger --sort -T reg ^exp # reverse sort by amount total -ledger --sort UT reg ^exp # sort by abs amount total -@end example +@item ///REGEXP/ +@item w/REGEXP/ +A regular expression that matches against an account's base name. If +a transaction, this will match against the account affected by the +transaction. -The @option{--sort} options sorts all transactions in a report. If -periods are used (such as @option{--monthly}), this can get somewhat -confusing. In that case, you'll probably want to sort within periods -using @option{--period-sort} instead of @option{--sort}. +@item c/REGEXP/ +A regular expression that matches against the entry code (the text +that occurs between parentheses before the payee name). -@c -w, --wide for the default register report, use 132 columns +@item e/REGEXP/ +A regular expression that matches against a transaction's note, or +comment field. -And if the register seems too cramped, and you have a lot of screen -real estate, you can use @option{-w} to format the report within 132 -acolumns, instead of 80. You are more likely then to see full payee -and account names, as well as properly formatted totals when -long-named commodities are used. +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. -If you want only the first or last N entries to be printed---which can -be very useful for viewing the last 10 entries in your checking -account, while also showing the cumulative balance from all -entries---use the @option{--head} and/or @option{--tail} options. The -two options may be used simultaneously, for example: +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table -@example -ledger --tail 20 reg checking -@end example +@node Period expressions, File format, Value expressions, Using Ledger +@section Period expressions -If the output from your command is very long, Ledger can output the -data to a pager utility, such as @command{more} or @command{less}: +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: @example -ledger --pager /usr/bin/less reg checking +[INTERVAL] [BEGIN] [END] @end example -@subsubsection Averages and percentages - -@c -A, --average report average transaction amount - -To see the running total changed to a running average, use -@option{-A}. The final transaction's total will be the overall -average of all displayed transactions. The works in conjunction with -period reporting, so that you can see your monthly average expenses -with: +The optional @var{INTERVAL} part may be any one of: @example -ledger -AM reg ^expenses:food -ledger -AMn reg ^expenses +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly @end example -This works in the balance report too: +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: @example -ledger -AM bal ^expenses:food -ledger -AMs bal ^expenses +from +since @end example -@c -D, --deviation report deviation from the average - -The @option{-D} option changes the running average into a deviation -from the running average. This only makes sense in the register -report, however. +The end time can be either of: @example -ledger -DM reg ^expenses:food +to +until @end example -@c -%, --percentage report balance totals as a percentile of the parent - -In the balance report only, @option{-%} changes the reported totals -into a percentage of the parent account. This kind of report is -confusing if negative amounts are involved, and doesn't work at all if -multiple commodities occur in an account's history. It has a somewhat -limited usefulness, therefore, but in certain cases it can be handy, -such as reviewing overall expenses: +Where @var{SPEC} can be any of: @example -ledger -%s -S T bal ^expenses +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week @end example -@subsubsection Reporting total data +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: -@c --totals in the "xml" report, include running total +@example + +in +@end example -Normally in the @command{xml} report, only transaction amounts are -printed. To include the running total under a @samp{} tag, use -@option{--totals}. This does not affect any other report. +Here are a few examples of period expressions: -@c -j, --amount-data print only raw amount data (useful for scripting) -@c -J, --total-data print only raw total data +@example +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +last oct +weekly last august +@end example -In the register report only, the output can be changed with -@option{-j} to show only the date and the amount---without -commodities. This only makes sense if a single commodity appears in -the report, but can be quite useful for scripting, or passing the data -to Gnuplot. To show only the date and running total, use @option{-J}. +@node File format, Some typical queries, Period expressions, Using Ledger +@section File format -@subsubsection Display by value expression +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. -@c -d, --display EXPR display only transactions matching EXPR +The initial character of each line determines what the line means, and +how it should be interpreted. Allowable initial characters are: -With @option{-d} you can decide which transactions (or accounts in the -balance report) are displayed, according to a value expression. The -computed total is not affected, only the display. This can be very -useful for shortening a report without changing the running total: +@table @code +@item NUMBER +A line beginning with a number denotes an entry. It may be followed +by any number of lines, each beginning with whitespace, to denote the +entry's account transactions. The format of the first line is: @example -ledger -d 'd>=[last month]' reg checking +DATE[=EDATE] [*|!] [(CODE)] DESC @end example -This command shows the checking account's register, beginning from -last month, but with the running total reflecting the entire history -of the account. - -@subsubsection Change report format - -@c -y, --date-format STR use STR as the date format (default: %Y/%m/%d) +If @samp{*} appears after the date (with optional effective date), it +indicates the entry is ``cleared'', which can mean whatever the user +wants it t omean. If @samp{!} appears after the date, it indicates d +the entry is ``pending''; i.e., tentatively cleared from the user's +point of view, but not yet actually cleared. If a @samp{CODE} appears +in parentheses, it may be used to indicate a check number, or the type +of the transaction. Following these is the payee, or a description of +the transaction. -When dates are printed in any report, the default format is -@samp{%Y/%m/%d}, which yields dates of the form @samp{YYYY/mm/dd}. -This can be changed with @option{-y}, whose argument is a -@code{strftime} string---see your system's C library documentation for -the allowable codes. Mostly you will want to use @samp{%Y}, @samp{%m} -and @samp{%d}, in whatever combination is convenient for your locale. +The format of each following transaction is: -@c -F, --format STR use STR as the format; for each report type, use: -@c --balance-format --register-format --print-format -@c --plot-amount-format --plot-total-format --equity-format -@c --prices-format --wide-register-format +@example + ACCOUNT AMOUNT [; NOTE] +@end example -To change the format of the entire reported line, use @option{-F}. It -supports quite a large number of options, which are all documented in -@ref{Format strings}. In addition, each specific kind of report -(except for @command{xml}) can be changed using one of the following -options: +The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual +transactions, or square brackets if it is a virtual transactions that +must balance. The @samp{AMOUNT} can be followed by a per-unit +transaction cost, by specifying @samp{@@ AMOUNT}, or a complete +transaction cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may +specify an actual and/or effective date for the transaction by using +the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. -@table @option -@item --balance-format -@command{balance} report. Default: -@smallexample -%20T %2_%-a\n -@end smallexample +@item = +An automated entry. A value expression must appear after the equal +sign. -@item --register-format -@command{register} report. Default: -@smallexample -%D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n -@end smallexample +After this initial line there should be a set of one or more +transactions, just as if it were normal entry. If the amounts of the +transactions have no commodity, they will be applied as modifiers to +whichever real transaction is matched by the value expression. -@item --print-format -@command{print} report. Default: -@smallexample -%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n -@end smallexample +@item ~ +A period entry. A period expression must appear after the tilde. -@item --plot-amount-format -@command{register} report when @option{-j} (plot amount) is used. Default: -@smallexample -%D %(St)\n -@end smallexample +After this initial line there should be a set of one or more +transactions, just as if it were normal entry. -@item --plot-total-format -@command{register} report when @option{-J} (plot total) is used. Default: -@smallexample -%D %(ST)\n -@end smallexample +@item ! +A line beginning with an exclamation mark denotes a command directive. +It must be immediately followed by the command word. The supported +commands are: -@item --equity-format -@command{equity} report. Default: -@smallexample -\n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n -@end smallexample +@table @samp +@item !include +Include the stated ledger file. -@item --prices-format -@command{prices} report. Default: -@smallexample -\n%D %Y%C%P\n%/ %-34W %12t\n -@end smallexample +@item !account +The account name is given is taken to be the parent of all +transactions that follow, until @samp{!end} is seen. -@item --wide-register-format -@command{register} report when @option{-w} (wide) is used. Default: -@smallexample -%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n -@end smallexample +@item !end +Ends an account block. @end table -@subsection Standard queries - -If your ledger file uses the standard top-level accounts: Assets, -Liabilities, Income, Expenses, Equity: then the following queries will -enable you to generate some typical accounting reports from your data. +@item ; +A line beginning with a colon indicates a comment, and is ignored. -Your @emph{net worth} can be determined by balancing assets against -liabilities: +@item Y +If a line begins with a capital Y, it denotes the year used for all +subsequent entries that give a date without a year. The year should +appear immediately after the Y, for example: @samp{Y2004}. This is +useful at the beginning of a file, to specify the year for that file. +If all entries specify a year, however, this command has no effect. +@item P +Specifies a historical price for a commodity. These are usually found +in a pricing history file (see the @option{-Q} option). The syntax +is: @example -ledger bal ^assets ^liab +P DATE SYMBOL PRICE @end example -By removing long-term investment and loan accounts, you can see your -current net liquidity (or liquid net worth): +@item N SYMBOL +Indicates that pricing information is to be ignored for a given +symbol, nor will quotes ever be downloaded for that symbol. Useful +with a home currency, such as the dollar ($). It is recommended that +these pricing options be set in the price database file, which +defaults to @file{~/.pricedb}. The syntax for this command is: +@example +N SYMBOL +@end example +@item D AMOUNT +Specifies the default commodity to use, by specifying an amount in the +expected format. The @command{entry} command will use this commodity +as the default when none other can be determined. This command may be +used multiple times, to set the default flags for different +commodities; whichever is seen last is used as the default commodity. +For example, to set US dollars as the default commodity, while also +setting the thousands flag and decimal flag for that commodity, use: @example -ledger bal ^assets ^liab -retirement -brokerage -loan +D $1,000.00 @end example -Balancing expenses against income yields your @emph{cash flow}, or net -profit/loss: - +@item C AMOUNT1 = AMOUNT2 +Specifies a commodity conversion, where the first amount is given to +be equivalent to the second amount. The first amount should use the +decimal precision desired during reporting: @example -ledger bal ^exp ^inc +C 1.00 Kb = 1024 bytes @end example -In this case, if the number is positive it means you spent more than -you earned during the report period. +@item i, o, b, h +These four relate to timeclock support, which permits ledger to read +timelog files. See the timeclock's documentation for more info on the +syntax of its timelog files. +@end table -@c ---------------------------------------------------------------------- +@node Some typical queries, Budgeting and forecasting, File format, Using Ledger +@section Some typical queries -The most often used command is the ``balance'' command: +A query such as the following shows all expenses since last +October, sorted by total: @example -export LEDGER=/home/johnw/doc/ledger.dat -ledger balance +ledger -b "last oct" -s -S T bal ^expenses @end example -Here I've set my Ledger environment variable to point to where my -ledger file is hiding. Thereafter, I needn't specify it again. +From left to right the options mean: Show entries since October, 2003; +show all sub-accounts; sort by the absolute value of the total; and +report the balance for all expenses. -@subsection Reporting balance totals +@subsection Reporting monthly expenses -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: +The following query makes it easy to see monthly expenses, with each +month's expenses sorted by the amount: @example -ledger balance expenses:food +ledger -M --period-sort t reg ^expenses @end example -This will show all the money that's been spent on food, since the -beginning of the ledger. For food spending just this month -(September), use: +Now, you might wonder where the money came from to pay for these +things. To see that report, add @option{-r}, which shows the +``related account'' transactions: @example -ledger -p sep balance expenses:food +ledger -M --period-sort t -r reg ^expenses @end example -Or maybe you want to see all of your assets, in which case the -s -(show sub-accounts) option comes in handy: +But maybe this prints too much information. You might just want to +see how much you're spending with your MasterCard. That kind of query +requires the use of a display predicate, since the transactions +calculated must match @samp{^expenses}, while the transactions +displayed must match @samp{mastercard}. The command would be: @example -ledger -s balance ^assets +ledger -M -r -d /mastercard/ reg ^expenses @end example -To exclude a particular account, use a regular expression with a -leading minus sign. The following will show all expenses, but without -food spending: +This query says: Report monthly subtotals; report the ``related +account'' transactions; display only related transactions whose +account matches @samp{mastercard}, and base the calculation on +transactions matching @samp{^expenses}. + +This works just as well for report the overall total, too: @example -ledger balance expenses -food +ledger -s -r -d /mastercard/ reg ^expenses @end example -@subsection Reporting percentages - -There is no built-in way to report transaction amounts or account -balances in terms of percentages - -@node Commands, Options, Usage overview, Running Ledger -@section Commands - -@subsection balance - -The @command{balance} command reports the current balance of all -accounts. It accepts a list of optional regexps, which confine the -balance report to the matching accounts. If an account contains -multiple types of commodities, each commodity's total is reported -separately. - -@subsection register - -The @command{register} command displays all the transactions occurring -in a single account, line by line. The account regexp must be -specified as the only argument to this command. If any regexps occur -after the required account name, the register will contain only those -transactions that match. Very useful for hunting down a particular -transaction. - -The output from @command{register} is very close to what a typical -checkbook, or single-account ledger, would look like. It also shows a -running balance. The final running balance of any register should -always be the same as the current balance of that account. - -If you have Gnuplot installed, you may plot the amount or running -total of any register by using the script @file{report}, which is -included in the Ledger distribution. The only requirement is that you -add either @option{-j} or @option{-J} to your register command, in -order to plot either the amount or total column, respectively. - -@subsection print - -The @command{print} command prints out ledger entries in a textual -format that can be parsed by Ledger. They will be properly formatted, -and output in the most economic form possible. The ``print'' command -also takes a list of optional regexps, which will cause only those -transactions which match in some way to be printed. - -The @command{print} command can be a handy way to clean up a ledger -file whose formatting has gotten out of hand. +The @option{-s} option subtotals all transactions, just as @option{-M} +subtotaled by the month. The running total in both cases is off, +however, since a display expression is being used. -@subsection output +@subsection Visualizing with Gnuplot -The @command{output} command is very similar to the @command{print} -command, except that it attempts to replicate the specified ledger -file exactly. The format of the command is: +If you have @command{Gnuplot} installed, you can graph any of the +above register reports. The script to do this is included in the +ledger distribution, and is named @file{scripts/report}. Install +@file{report} anywhere along your @env{PATH}, and then use +@command{report} instead of @command{ledger} when doing a register +report. The only thing to keep in mind is that you must specify +@option{-j} or @option{-J} to indicate whether Gnuplot should plot the +amount, or the running total. For example, this command plots total +monthly expenses made on your MasterCard. @example -ledger -f FILENAME output FILENAME +report -j -M -r -d /mastercard/ reg ^expenses @end example -Where @file{FILENAME} is the name of the ledger file to output. The -reason for specifying this command is that only entries contained -within that file will be output, and not an included entries (as can -happen with the @command{print} command). - -@subsection xml +The @command{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. -The @command{xml} command outputs results similar to what -@command{print} and @command{register} display, but as an XML form. -This data can then be read in and processed. Use the -@option{--totals} option to include the running total with each -transaction. +@subsubsection Typical plots -@subsection emacs +Here are some useful plots: -The @command{emacs} command outputs results in a form that can be read -directly by Emacs Lisp. The format of the sexp is: +@smallexample +report -j -M reg ^expenses # monthly expenses +report -J reg checking # checking account balance +report -J reg ^income ^expenses # cash flow report -@example -((BEG-POS CLEARED DATE CODE PAYEE - (ACCOUNT AMOUNT)...) ; list of transactions - ...) ; list of entries -@end example +# net worth report, ignoring non-$ transactions -@subsection equity +report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab -The @command{equity} command prints out accounts balances as if they -were entries. This makes it easy to establish the starting balances -for an account, such as when @ref{Archiving previous years}. +# 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 -@subsection prices +report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab +@end smallexample -The @command{prices} command displays the price history for matching -commodities. The @option{-A} flag is useful with this report, to -display the running average price, or @option{-D} to show each price's -deviation from that average. +The last report uses both a calculation predicate (@option{-l}) and a +display predicate (@option{-d}). The calculation predicates limits +the report to transactions whose amount is greater than $1 (which can +only happen if the transaction amount is in dollars). The display +predicate limits the entries @emph{displayed} to just those since last +February, even those entries from before then will be computed as part +of the balance. -There is also a @command{pricesdb} command which outputs the same -information as @command{prices}, but does in a format that can be -parsed by Ledger. +@node Budgeting and forecasting, , Some typical queries, Using Ledger +@section Budgeting and forecasting -@subsection entry +@subsection Budgeting -The @command{entry} commands simplifies the creation of new entries. -It works on the principle that 80% of all transactions are variants of -earlier transactions. Here's how it works: +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. -Say you currently have this transaction in your ledger file: +To start keeping a budget, put some period entries at the top of your +ledger file. A period entry is almost identical to a regular entry, +except that it begins with a tilde and has a period expression in +place of a payee. For example: @smallexample -2004/03/15 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 +~ Monthly + Expenses:Rent $500.00 + Expenses:Food $450.00 + Expenses:Auto:Gas $120.00 + Expenses:Insurance $150.00 + Expenses:Phone $125.00 + Expenses:Utilities $100.00 + Expenses:Movies $50.00 + Expenses $200.00 ; all other expenses + Assets + +~ Yearly + Expenses:Auto:Repair $500.00 + Assets @end smallexample -Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva -Italiano} again. The exact amounts are different, but the overall -form is the same. With the @command{entry} command you can type: +These two period entries give the usual monthly expenses, as well as +one typical yearly expense. For help on finding out what your average +monthly expense is for any category, use a command like: @example -ledger entry 2004/4/9 viva food 11 tips 2.50 +ledger -p "this year" -MAs bal ^expenses @end example -This produces the following output: +The reported totals are the current year's average for each account. -@smallexample -2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 -@end smallexample +Once these period entries are defined, creating a budget report is as +easy as adding @option{--budget} to the command-line. For example, a +typical monthly expense report would be: -It works by finding a past transaction matching the regular expression -@samp{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier transaction. If Ledger does not succeed in -generating a new entry, an error is printed and the exit code is set -to @samp{1}. +@example +ledger -M reg ^exp +@end example -There is a shell script in the distribution's @file{scripts} directory -called @file{entry}, which simplifies the task of adding a new entry -to your ledger. It launches @command{vi} to confirm that the entry -looks appropriate. +To see the same report balanced against your budget, use: -Here are a few more examples of the @command{entry} command, assuming -the above journal entry: +@example +ledger --budget -M reg ^exp +@end example + +A budget report includes only those accounts that appear in the +budget. To see all expenses balanced against the budget, use +@option{--add-budget}. You can even see only the unbudgeted expenses +using @option{--unbudgeted}: @example -ledger 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" +ledger --unbudgeted -M reg ^exp @end example -@node Options, Format strings, Commands, Running Ledger -@section Options +You can also use these flags with the @command{balance} command. -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: +@subsection Forecasting + +Sometimes it's useful to know what your finances will look like in the +future, such as determining when an account will reach zero. Ledger +makes this easy to do, using the same period entries as are used for +budgeting. An example forecast report can be generated with: @example -ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities @end example -The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. -You could just use @samp{ledger balance}, without any options---which -prints a summary of all accounts. But for more specific reporting, or -to change the appearance of the output, options are needed. +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. -@menu -* Basic options:: -* Report filtering:: -* Output customization:: -* Commodity reporting:: -* Environment variables:: -@end menu +Forecasting can also be used with the balance report, but by date +only, and not against the running total: -@node Basic options, Report filtering, Options, Options -@subsection Basic options +@example +ledger --forecast "d<[2010]" bal ^assets ^liabilities +@end example -These are the most basic command options. Most likely, the user will -want to set them using @ref{Environment variables}, instead of using -actual command-line options: +@node Ledger in Practice, , Using Ledger, Top +@chapter Ledger in Practice -@option{--help} (@option{-h}) prints a summary of all the options, and -what they are used for. This can be a handy way to remember which -options do what. This help screen is also printed if ledger is run -without a command. +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. -@option{--version} (@option{-v}) prints the current version of ledger -and exits. This is useful for sending bug reports, to let the author -know which version of ledger you are using. +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. -@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. -This command may be used multiple times. FILE may also be a list of -file names separated by colons. Typically, the environment variable -@env{LEDGER_FILE} is set, rather than using this command-line option. +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. -@option{--output FILE} (@option{-o FILE}) redirects output from any -command to @var{FILE}. By default, all output goes to standard -output. +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. -@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: +Here is the Pacific Bell example from above, given as a Ledger +transaction: @smallexample ---price-db ~/finance/.pricedb +9/29 (100) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking $-23.00 +@end smallexample -; ~/.ledgerrc ends here +As you can see, it is very similar to what would be written on paper, +minus the computed balance totals, and adding in account names that +work better with Ledger's scheme of things. In fact, since Ledger is +smart about many things, you don't need to specify the balanced +amount, if it is the same as the first line: + +@smallexample +9/29 (100) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking @end smallexample -Option settings on the command-line or in the environment always take -precedence over settings in the init file. +For this entry, Ledger will figure out that $-23.00 must come from +@samp{Assets:Checking} in order to balance the entry. -@option{--cache FILE} identifies FILE as the default binary cache -file. That is, if the ledger files to be read are specified using the -environment variable @env{LEDGER_FILE}, then whenever a command is -finished a binary copy will be written to the specified cache, to -speed up the loading time of subsequent queries. This filename can -also be given using the environment variable @env{LEDGER_CACHE}, or by -putting the option into your init file. The @option{--no-cache} -option causes Ledger to always ignore the binary cache. +@menu +* Usage overview:: +* 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:: +* Using XML:: +@end menu -@option{--account NAME} (@option{-a NAME}) specifies the default -account which QIF file transactions are assumed to relate to. +@node Usage overview, Stating where money goes, Ledger in Practice, Ledger in Practice +@section Usage overview -@node Report filtering, Output customization, Basic options, Options -@subsection Report filtering +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. -These options change which transactions affect the outcome of a -report, in ways other than just using regular expressions: +For the purpose of these examples, assume the environment variable +@var{LEDGER} is set to the file @file{sample.dat} (which is included +in the distribution), and that the contents of that file are: -@option{--current}(@option{-c}) displays only entries occurring on or -before the current date. +@smallexample += /^Expenses:Books/ + (Liabilities:Taxes) -0.10 -@option{--begin DATE} (@option{-b DATE}) constrains the report to -entries on or after @var{DATE}. Only entries after that date will be -calculated, which means that the running total in the balance report -will always start at zero with the first matching entry. (Note: This -is different from using @option{--display} to constrain what is -displayed). +~ Monthly + Assets:Bank:Checking $500.00 + Income:Salary -@option{--end DATE} (@option{-e DATE}) constrains the report so that -entries on or after @var{DATE} are not considered. The ending date -is inclusive. +2004/05/01 * Checking balance + Assets:Bank:Checking $1,000.00 + Equity:Opening Balances -@option{--period STR} (@option{-p STR}) sets the reporting period -to @var{STR}. This will subtotal all matching entries within each -period separately, making it easy to see weekly, monthly, quarterly, -etc., transaction totals. A period string can even specify the -beginning and end of the report range, using simple terms like ``last -june'' or ``next month''. For more using period expressions, see -@ref{Period expressions}. +2004/05/01 * Investment balance + Assets:Brokerage 50 AAPL @@ $30.00 + Equity:Opening Balances -@option{--period-sort EXPR} sorts the transactions within each -reporting period using the value expression @var{EXPR}. This is most -often useful when reporting monthly expenses, in order to view the -highest expense categories at the top of each month: +2004/05/14 * Pay day + Assets:Bank:Checking $500.00 + Income:Salary -@example -ledger -M --period-sort -At reg ^Expenses -@end example +2004/05/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard -@option{--cleared} (@option{-C}) displays only transactions whose entry -has been marked ``cleared'' (by placing an asterix to the right of the -date). +2004/05/27 (100) Credit card company + Liabilities:MasterCard $20.00 + Assets:Bank:Checking +@end smallexample -@option{--uncleared} (@option{-U}) displays only transactions whose -entry has not been marked ``cleared'' (i.e., if there is no asterix to -the right of the date). +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. -@option{--real} (@option{-R}) displays only real transactions, not -virtual. (A virtual transaction is indicated by surrounding the -account name with parentheses or brackets; see the section on using -virtual transactions for more information). +@subsection Checking balances -@option{--actual} (@option{-L}) displays only actual transactions, and -not those created due to automated transactions. +Ledger has seven basic commands, but by far the most often used are +@command{balance} and @command{register}. To see a summary balance of +all accounts, use: -@option{--related} (@option{-r}) displays transactions that are -related to whichever transactions would otherwise have matched the -filtering criteria. In the register report, this shows where money -went to, or the account it came from. In the balance report, it shows -all the accounts affected by entries having a related transaction. -For example, if a file had this entry: +@example +ledger bal +@end example + +@command{bal} is a short-hand for @command{balance}. This command +prints out the summary totals of the five parent accounts used in +@file{sample.dat}: @smallexample -2004/03/20 Safeway - Expenses:Food $65.00 - Expenses:Cash $20.00 - Assets:Checking $-85.00 + $1,480.00 + 50 AAPL Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income + $-2.00 Liabilities +-------------------- + $-1,502.00 + 50 AAPL @end smallexample -And the register command was: +None of the child accounts are shown, just the parent account totals. +We can see that in @samp{Assets} there is $1,480.00, and 50 shares of +Apple stock. There is also a negative grand total. Usually the grand +total is zero, which means that all accounts balance@footnote{It is +impossible for accounts not to balance in ledger; it reports an error +if a transaction does not balance}. In this case, since the 50 shares +of Apple stock cost $1,500.00 dollars, then these two amounts balance +each other in the grand total. The extra $2.00 comes from a virtual +transaction being added by the automatic entry at the top of the file. +The entry is virtual because the account name was surrounded by +parentheses in an automatic entry. Automatic entries will be +discussed later, but first let's remove the virtual transaction from +the balance report by using the @option{--real} option: @example -ledger -r register food +ledger --real bal @end example -The following would be output, showing the transactions related to the -transaction that matched: +Now the report is: @smallexample -2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 + $1,480.00 + 50 AAPL Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income +-------------------- + $-1,500.00 + 50 AAPL @end smallexample -@option{--budget} is useful for displaying how close your transactions -meet your budget. @option{--add-budget} also shows unbudgeted -transactions, while @option{--unbudgeted} shows only those. -@option{--forecast} is a related option that projects your budget into -the future, showing how it will affect future balances. -@xref{Budgeting and forecasting}. +Since the liability was a virtual transaction, it has dropped from the +report and we see that final total is balanced. -@option{--limit EXPR} (@option{-l EXPR}) limits which transactions -take part in the calculations of a report. +But we only know that it balances because @file{sample.dat} is quite +simple, and we happen to know that the 50 shares of Apple stock cost +$1,500.00. We can verify that things really balance by reporting the +Apple shares in terms of their cost, instead of their quantity. To do +this requires the @option{--basis}, or @option{-B}, option: -@option{--amount EXPR} (@option{-t EXPR}) changes the value expression -used to calculate the ``value'' column in the @command{register} -report, the amount used to calculate account totals in the -@command{balance} report, and the values printed in the -@command{equity} report. @xref{Value expressions}. +@example +ledger --real -B bal +@end example -@option{--total EXPR} (@option{-T EXPR}) sets the value expression -used for the ``totals'' column in the @command{register} and -@command{balance} reports. +This command reports: -@node Output customization, Commodity reporting, Report filtering, Options -@subsection Output customization +@smallexample + $2,980.00 Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income +@end smallexample -These options affect only the output, but not which transactions are -used to create it: +With the basis cost option, the grand total has disappeared, as it is +now zero. The confirms that the cost of everything balances to zero, +@emph{which must always be true}. Reporting the real basis cost +should never yield a remainder@footnote{If it ever does, then +generated transactions are involved, which can be removed using +@option{--actual}}. -@option{--collapse} (@option{-n}) causes entries in a -@command{register} report with multiple transactions to be collapsed -into a single, subtotaled entry. +@subsubsection Sub-account balances -@option{--subtotal} (@option{-s}) causes all entries in a -@command{register} report to be collapsed into a single, subtotaled -entry. +The totals reported by the balance command are only the topmost parent +accounts. To see the totals of all child accounts as well, use the +@option{-s} option: -@option{--by-payee} (@option{-P}) reports subtotals by payee. +@example +ledger --real -B -s bal +@end example -@option{--comm-as-payee} (@option{-x}) changes the payee of every -transaction to be the commodity used in that transaction. This can be -useful when combined with other options, such as @option{-s}. +This reports: -@option{--empty} (@option{-E}) includes even empty accounts in the -@command{balance} report. +@smallexample + $2,980.00 Assets + $1,480.00 Bank:Checking + $1,500.00 Brokerage + $-2,500.00 Equity:Opening Balances + $20.00 Expenses:Books + $-500.00 Income:Salary +@end smallexample -@option{--weekly} (@option{-W}) reports transaction totals by the -week. The week begins on whichever day of the week begins the month -containing that transaction. To set a specific begin date, use a -period string, such as @samp{weekly from DATE}. @option{--monthly} -(@option{-M}) reports transaction totals by month; @option{--yearly} -(@option{-Y}) reports transaction totals by year. For more complex -period, using the @option{--period} option described above. +This shows that the @samp{Assets} total is made up from two child +account, but that the total for each of the other accounts comes from +one child account. -@option{--dow} reports transactions totals for each day of the week. -This is an easy way to see if weekend spending is more than on -weekdays. +Sometimes you may have a lot of children, nested very deeply, but only +want to report the first two levels. This can be done with a display +predicate, using a value expression. In the value expression, +@code{T} represents the reported total, and @code{l} is the display +level for the account: -@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing -the values determined using the value expression @var{EXPR}. For -example, using @option{-S -UT} in the balance report will sort account -balances from greatest to least, using the absolute value of the -total. For more on how to use value expressions, see @ref{Value -expressions}. +@example +ledger --real -B -d "T&l<=2" bal +@end example -@option{--wide} (@option{-w}) causes the default @command{register} -report to assume 132 columns instead of 80. +This reports: -@option{--head} causes only the first N entries to be printed. This -is different from using the command-line utility @command{head}, which -would limit to the first N transactions. @option{--tail} outputs only -the last N entries. Both options may be used simultaneously. If a -negative amount is given, it will invert the meaning of the flag -(instead of the first five entries being printed, for example, it -would print all but the first five). +@smallexample + $2,980.00 Assets + $1,480.00 Bank + $1,500.00 Brokerage + $-2,500.00 Equity:Opening Balances + $20.00 Expenses:Books + $-500.00 Income:Salary +@end smallexample -@option{--pager} tells Ledger to pass its output to the given pager -program---very useful when the output is especially long. This -behavior can be made the default by setting the @env{LEDGER_PAGER} -environment variable. +Instead of reporting @samp{Bank:Checking} as a child of @samp{Assets}, +it report only @samp{Bank}, since that account is a nesting level of +2, while @samp{Checking} is at level 3. -@option{--average} (@option{-A}) reports the average transaction -value. +To review the display predicate used---@code{T&l<=2}---this rather +terse expression means: Display an account only if it has a non-zero +total (@code{T}), and its nesting level is less than or equal to 2 +(@code{l<=2}). -@option{--deviation} (@option{-D}) reports each transaction's -deviation from the average. It is only meaningful in the -@command{register} and @command{prices} reports. +@subsubsection Specific account balances -@option{--percentage} (@option{-%}) shows account subtotals in the -@command{balance} report as percentages of the parent account. +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: -@option{--totals} include running total information in the -@command{xml} report. +@example +ledger bal checking +@end example -@option{--amount-data} (@option{-j}) changes the @command{register} -report so that it output nothing but the date and the value column, -and the latter without commodities. This is only meaningful if the -report uses a single commodity. This data can then be fed to other -programs, which could plot the date, analyze it, etc. +Reports: -@option{--total-data} (@option{-J}) changes the @command{register} -report so that it output nothing but the date and totals column, -without commodities. +@smallexample + $1,480.00 Assets:Bank:Checking +@end smallexample -@option{--display EXPR} (@option{-d EXPR}) limits which transactions -or accounts or actually displayed in a report. They might still be -calculated, and be part of the running total of a register report, for -example, but they will not be displayed. This is useful for seeing -last month's checking transactions, against a running balance which -includes all transaction values: +Any number of names may be used: @example -ledger -d "d>=[last month]" reg checking +ledger bal checking broker liab @end example -The output from this command is very different from the following, -whose running total includes only transactions from the last month -onward: +Reports: -@example -ledger -p "last month" reg checking -@end example +@smallexample + $1,480.00 Assets:Bank:Checking + 50 AAPL Assets:Brokerage + $-2.00 Liabilities +@end smallexample -Which is more useful depends on what you're looking to know: the total -amount for the reporting range (@option{-p}), or simply a display -restricted to the reporting range (using @option{-d}). +In this case no grand total is reported, because you are asking for +specific account balances. -@option{--date-format STR} (@option{-y STR}) changes the basic date -format used by reports. The default uses a date like 2004/08/01, -which represents the default date format of @samp{%Y/%m/%d}. To -change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the Ledger initialization file -@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). +For those comfortable with regular expressions, any Perl regexp is +allowed: -@option{--format STR} (@option{-F STR}) sets the reporting format for -whatever report ledger is about to make. @xref{Format strings}. -There are also specific format commands for each report type: +@example +ledger bal ^assets.*checking ^liab +@end example -@itemize -@item @option{--balance-format STR} -@item @option{--register-format STR} -@item @option{--print-format STR} -@item @option{--plot-amount-format STR} (-j @command{register}) -@item @option{--plot-total-format STR} (-J @command{register}) -@item @option{--equity-format STR} -@item @option{--prices-format STR} -@item @option{--wide-register-format STR} (-w @command{register}) -@end itemize +Reports: -@node Commodity reporting, Environment variables, Output customization, Options -@subsection Commodity reporting +@smallexample + $1,480.00 Assets:Bank:Checking + $-2.00 Liabilities:Taxes +@end smallexample -These options affect how commodity values are displayed: +@subsection The register report -@option{--price-db FILE} sets the file that is used for recording -downloaded commodity prices. It is always read on startup, to -determine historical prices. Other settings can be placed in this -file manually, to prevent downloading quotes for a specific, for -example. This is done by adding a line like the following: +While the @command{balance} command can be very handy for checking +account totals, by far the most powerful of Ledger's reporting tools +is the @command{register} command. In fact, internally both commands +use the same logic, but report the results differently: +@command{balance} shows the summary totals, while @command{register} +reports each transaction and how it contributes to that total. + +Paradoxically, the most basic form of @command{register} is almost +never used, since it displays every transaction: @example -; Don't download quotes for the dollar, or timelog values -N $ -N h +ledger reg @end example -@option{--price-exp MINS} (@option{-L MINS}) sets the expected -freshness of price quotes, in minutes. That is, if the last known -quote for any commodity is older than this value---and if -@option{--download} is being used---then the Internet will be -consulted again for a newer price. Otherwise, the old price is still -considered to be fresh enough. - -@option{--download} (@option{-Q}) causes quotes to be automagically -downloaded, as needed, by running a script named @command{getquote} -and expecting that script to return a value understood by ledger. A -sample implementation of a @command{getquote} script, implemented in -Perl, is provided in the distribution. Downloaded quote price are -then appended to the price database, usually specified using the -environment variable @env{LEDGER_PRICE_DB}. - -There are several different ways that ledger can report the totals it -displays. The most flexible way to adjust them is by using value -expressions, and the @option{-t} and @option{-T} options. However, -there are also several ``default'' reports, which will satisfy most -users basic reporting needs: +@command{reg} is a short-hand for @command{register}. This command +reports: -@table @code -@item -O, --quantity -Reports commodity totals (this is the default) +@smallexample +2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + Equity:Opening Balan.. $-1,000.00 0 +2004/05/01 Investment balance Assets:Brokerage 50 AAPL 50 AAPL + Equity:Opening Balan.. $-1,500.00 $-1,500.00 + 50 AAPL +2004/05/14 Pay day Assets:Bank:Checking $500.00 $-1,000.00 + 50 AAPL + Income:Salary $-500.00 $-1,500.00 + 50 AAPL +2004/05/27 Book Store Expenses:Books $20.00 $-1,480.00 + 50 AAPL + Liabilities:MasterCard $-20.00 $-1,500.00 + 50 AAPL + (Liabilities:Taxes) $-2.00 $-1,502.00 + 50 AAPL +2004/05/27 Credit card company Liabilities:MasterCard $20.00 $-1,482.00 + 50 AAPL + Assets:Bank:Checking $-20.00 $-1,502.00 + 50 AAPL +@end smallexample -@item -B, --basis -Reports the cost basis for all transactions. +This rather verbose output shows every account transaction in +@file{sample.dat}, and how it affects the running total. The final +total is identical to what we saw with the plain @command{balance} +command. To see how things really balance, we can use @samp{--real +-B}, just as we did with @command{balance}: -@item -V, --market -Reports the last known market value for all commodities. +@example +ledger --real -B reg +@end example -@item -g, --performance -Reports the net gain/loss for each transaction in a @command{register} -report. +Reports: -@item -G --gain -Reports the net gain/loss for all commodities in the report that have -a price history. -@end table +@smallexample +2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + Equity:Opening Balan.. $-1,000.00 0 +2004/05/01 Investment balance Assets:Brokerage $1,500.00 $1,500.00 + Equity:Opening Balan.. $-1,500.00 0 +2004/05/14 Pay day Assets:Bank:Checking $500.00 $500.00 + Income:Salary $-500.00 0 +2004/05/27 Book Store Expenses:Books $20.00 $20.00 + Liabilities:MasterCard $-20.00 0 +2004/05/27 Credit card company Liabilities:MasterCard $20.00 $20.00 + Assets:Bank:Checking $-20.00 0 +@end smallexample -@node Environment variables, , Commodity reporting, Options -@subsection Environment variables +Here we see that everything balances to zero in the end, as it must. -Every option to ledger may be set using an environment variable. If -an option has a long name such @option{--this-option}, setting the -environment variable @env{LEDGER_THIS_OPTION} will have the same -affect as specifying that option on the command-line. Options on the -command-line always take precedence over environment variable -settings, however. +@subsubsection Specific register queries -Note that you may also permanently specify option values by placing -option settings in the file @file{~/.ledgerrc}, for example: +The most common use of the register command is to summarize +transactions based on the account(s) they affect. Using +@file{sample.dat} as as example, we could look at all book purchases +using: @example ---cache /tmp/.mycache +ledger reg books @end example -@node Format strings, Value expressions, Options, Running Ledger -@section Format strings +Reports: -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the -@option{--format} (@option{-F}) option. Within that string, -constructs are allowed which make it possible to display the various -parts of an account or transaction in custom ways. +@smallexample +2004/05/29 Book Store Expenses:Books $20.00 $20.00 +@end smallexample -Within a format strings, a substitution is specified using a percent -character (@samp{%}). The basic format of all substitutions is: +If a double-dash (@samp{--}) occurs in the list of regular +expressions, any following arguments are matched against payee names, +instead of account names: @example -%[-][MIN WIDTH][.MAX WIDTH]EXPR +ledger reg ^liab -- credit @end example -If the optional minus sign (@samp{-}) follows the percent character, -whatever is substituted will be left justified. The default is right -justified. If a minimum width is given next, the substituted text -will be at least that wide, perhaps wider. If a period and a maximum -width is given, the substituted text will never be wider than this, -and will be truncated to fit. Here are some examples: +Reports: -@example -%-P An entry's payee, left justified -%20P The same, right justified, at least 20 chars wide -%.20P The same, no more than 20 chars wide -%-.20P Left justified, maximum twenty chars wide -@end example +@smallexample +2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00 +@end smallexample -The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The -allowable expressions are: +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. -@table @code -@item % -Inserts a percent sign. +@subsection Selecting transactions -@item t -Inserts the results of the value expression specified by @option{-t}. -If @option{-t} was not specified, the current report style's value -expression is used. +Although the easiest way to use the register is to report all the +transactions affecting a set of accounts, it can often result in more +information than you want. To cope with an ever-growing amount of +data, there are several options which can help you pinpoint your +report to exactly the transactions that interest you most. This is +called the ``calculation'' phase of Ledger. All of its related +options are documented under @option{--help-calc}. -@item T -Inserts the results of the value expression specified by @option{-T}. -If @option{-T} was not specified, the current report style's value -expression is used. +@subsubsection By date -@item | -Inserts a single space. This is useful if a width is specified, for -inserting a certain number of spaces. +@c -c, --current show only current and past entries (not future) -@item _ -Inserts a space for each level of an account's depth. That is, if an -account has two parents, this construct will insert two spaces. If a -minimum width is specified, that much space is inserted for each level -of depth. Thus @samp{%5_}, for an account with four parents, will -insert twenty spaces. +@option{--current}(@option{-c}) displays entries occurring on or +before the current date. Any entry recorded for a future date will be +ignored, as if it had not been seen. This is useful if you happen to +pre-record entries, but still wish to view your balances in terms of +what is available today. -@item (EXPR) -Inserts the amount resulting from the value expression given in -parentheses. To insert five times the total value of an account, for -example, one could say @samp{%12(5*O)}. Note: It's important to put -the five first in that expression, so that the commodity doesn't get -stripped from the total. +@c -b, --begin DATE set report begin date +@c -e, --end DATE set report end date -@item [DATEFMT] -Inserts the result of formatting a transaction's date with a date -format string, exactly like those supported by @code{strftime}. For -example: @samp{%[%Y/%m/%d %H:%M:%S]}. +@option{--begin DATE} (@option{-b DATE}) limits the report to only +those entries occurring on or after @var{DATE}. The running total in +the register will start at zero with the first transaction, even if +there are earlier entries. -@item S -Insert the pathname of the file from which the entry's data was read. +To limit the display only, but still add earlier transactions to the +running total, use the display expression @samp{-d 'd>=[DATE]'}): -@item B -Inserts the beginning character position of that entry within the file. +@example +ledger --basis -b may -d 'd>=[5/14]' reg ^assets +@end example -@item b -Inserts the beginning line of that entry within the file. +Reports: -@item E -Inserts the ending character position of that entry within the file. +@smallexample +2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 +2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 +@end smallexample -@item e -Inserts the ending line of that entry within the file. +In this example, the displayed transactions start from @samp{5/14}, +but the calculated total starts from the beginning of @samp{may}. -@item D -By default, this is the same as @samp{%[%Y/%m%/d]}. The date format -used can be changed at any time with the @option{-y} flag, however. -Using @samp{%D} gives the user more control over the way dates are -output. +@option{--end DATE} (@option{-e DATE}) states when reporting should +end, both calculation and display. The ending date is inclusive. -@item d -This is the same as the @samp{%D} option, unless the entry has an -effective date, in which case it prints -@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. +The @var{DATE} argument to the @option{-b} and @option{-e} options can +be rather flexible. Assuming the current date to be November 15, +2004, then all of the following are equivalent: -@item X -If a transaction has been cleared, this inserts @samp{*} followed by a -space; otherwise nothing is inserted. +@example +ledger -b oct bal +ledger -b "this oct" bal +ledger -b 2004/10 bal +ledger -b 10 bal +ledger -b last bal +ledger -b "last month" bal +@end example -@item Y -This is the same as @samp{%X}, except that it only displays a state -character if all of the member transactions have the same state. +@c -p, --period STR report using the given period +@c --period-sort EXPR sort each report period's entries by EXPR -@item C -Inserts the checking number for an entry, in parentheses, followed by -a space; if none was specified, nothing is inserted. +To constrain the report to a specific time period, use +@option{--period} (@option{-p}). A time period may have both a +beginning and an end, or neither, as well as a specified interval. +Here are a few examples: + +@example +ledger -p 2004 bal +ledger -p august bal +ledger -p "from aug to oct" bal +ledger -p "daily from 8/1 to 8/15" bal +ledger -p "weekly since august" bal +ledger -p "monthly from feb to oct" bal +ledger -p "quarterly in 2004" bal +ledger -p yearly bal +@end example -@item P -Inserts the payee related to a transaction. +See @ref{Period expressions} for more on syntax. Also, all of the +options @option{-b}, @option{-e} and @option{-p} may be used together, +but whatever information occurs last takes priority. An example of +such usage (in a script, perhaps) would be: -@item a -Inserts the optimal short name for an account. This is normally used -in balance reports. It prints a parent account's name if that name -has not been printed yet, otherwise it just prints the account's name. +@example +ledger -b 2004 -e 2005 -p monthly reg ^expenses +@end example -@item A -Inserts the full name of an account. +This command is identical to: -@item W -This is the same as @samp{%A}, except that it first displays the -transaction's state @emph{if the entry's transaction states are not -all the same}, followed by the full account name. This is offered as -a printing optimization, so that combined with @samp{%Y}, only the -minimum amount of state detail is printed. +@example +ledger -p "monthly in 2004" reg ^expenses +@end example -@item o -Inserts the ``optimized'' form of a transaction's amount. This is -used by the print report. In some cases, this inserts nothing; in -others, it inserts the transaction amount and its cost. It's use is -not recommend unless you are modifying the print report. +The transactions within a period may be sorted using +@option{--period-sort}, which takes a value expression. This is +similar to the @option{--sort} option, except that it sorts within +each period entry, rather than sorting all transactions in the report. +See the documentation on @option{--sort} below for more details. -@item n -Inserts the note associated with a transaction, preceded by two spaces -and a semi-colon, if it exists. Thus, no none becomes an empty -string, while the note @samp{foo} is substituted as @samp{ ; foo}. +@subsubsection By status -@item N -Inserts the note associated with a transaction, if one exists. +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: -@item / -The @samp{%/} construct is special. It separates a format string -between what is printed for the first transaction of an entry, and -what is printed for all subsequent transactions. If not used, the -same format string is used for all transactions. +@table @option +@item -C, --cleared +Consider only cleared transactions. +@item -U, --uncleared +Consider only uncleared and pending transactions. +@item -R, --real +Consider only real (non-virtual) transactions. +@item -L, --actual +Consider only actual (non-automated) transactions. @end table -@node Value expressions, Period expressions, Format strings, Running Ledger -@section Value expressions - -Value expressions are an expression language used by Ledger to -calculate values used by the program for many different purposes: +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. -@enumerate -@item -The values displayed in reports -@item -For predicates (where truth is anything non-zero), to determine which -transactions are calculated (@option{-l}) or displayed (@option{-d}). -@item -For sorting criteria, to yield the sort key. -@item -In the matching criteria used by automated transactions. -@end enumerate +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. -Value expressions support most simple math and logic operators, in -addition to a set of one letter functions and variables. A function's -argument is whatever follows it. The following is a display predicate -that I use with the @command{balance} command: +Actual transactions are those not generated, either as part of an +automated entry, or a budget or forecast report. A useful of when you +might like to filter out generated transactions is with a budget: @example -ledger -d /^Liabilities/?T<0:UT>100 balance +ledger --budget --actual reg ^expenses @end example -The effect is that account totals are displayed only if: 1) A -Liabilities account has a total less than zero; or 2) the absolute -value of the account's total exceeds 100 units of whatever commodity -contains. If it contains multiple commodities, only one of them must -exceed 100 units. +This command outputs all transactions affecting a budgeted account, +but without subtracting the budget amount (because the generated +transactions are suppressed with @option{--actual}). The report shows +how much you actually spent on budgeted items. -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: +@subsubsection By relationship -@example -ledger -d "d>[this month]" register checking -@end example +@c -r, --related calculate report using related transactions -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: +Normally, a register report includes only the transactions that match +the regular expressions specified after the command word. For +example, to report all expenses: @example -ledger -b "this month" register checking +ledger reg ^expenses @end example -@subsection Variables - -Below are the one letter variables available in any value expression. -For the register and print commands, these variables relate to -individual transactions, and sometimes the account affected by a -transaction. For the balance command, these variables relate to -accounts---often with a subtle difference in meaning. The use of each -variable for both is specified. - -@table @code -@item t -This maps to whatever the user specified with @option{-t}. In a -register report, @option{-t} changes the value column; in a balance -report, it has no meaning by default. If @option{-t} was not -specified, the current report style's value expression is used. - -@item T -This maps to whatever the user specified with @option{-T}. In a -register report, @option{-T} changes the totals column; in a balance -report, this is the value given for each account. If @option{-T} was -not specified, the current report style's value expression is used. +This reports: -@item m -This is always the present moment/date. -@end table +@smallexample +2004/05/29 Book Store Expenses:Books $20.00 $20.00 +@end smallexample -@subsubsection Transaction/account details +Using @option{--related} (@option{-r}) reports the transactions that +did not match your query, but only in entries that otherwise would +have matched. This has the effect of indicating where money came +from, or when to: -@table @code -@item d -A transaction's date, as the number of seconds past the epoch. This -is always ``today'' for an account. +@example +ledger -r reg ^expenses +@end example -@item a -The transaction's amount; the balance of an account, without -considering children. +Reports: -@item b -The cost of a transaction; the cost of an account, without its -children. +@smallexample +2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00 +@end smallexample -@item v -The market value of a transaction, or an account without its children. +@subsubsection By budget -@item g -The net gain (market value minus cost basis), for a transaction or an -account without its children. It is the same as @samp{v-b}. +@c --budget generate budget entries based on FILE -@item l -The depth (``level'') of an account. If an account has one parent, -it's depth is one. +There is more information about budgeting and forecasting in +@ref{Budgeting and forecasting}. Basically, if you have any period +entries in your ledger file, you can use these options. A period +entry looks like: -@item n -The index of a transaction, or the count of transactions affecting an -account. +@example +~ Monthly + Assets:Bank:Checking $500.00 + Income:Salary +@end example -@item X -1 if a transaction's entry has been cleared, 0 otherwise. +The difference from a regular entry is that the first line begins with +a tilde (~), and instead of a payee there's a period expression +(@ref{Period expressions}). Otherwise, a period entry is in every +other way the same as a regular entry. -@item R -1 if a transaction is not virtual, 0 otherwise. +With such an entry in your ledger file, the @option{--budget} option +will report only transactions that match a budgeted account. Using +@file{sample.dat} from above: -@item Z -1 if a transaction is not automated, 0 otherwise. -@end table +@example +ledger --budget reg ^income +@end example -@subsubsection Calculated totals +Reports: -@table @code -@item O -The total of all transactions seen so far, or the total of an account -and all its children. +@smallexample +2004/05/01 Budget entry Income:Salary $500.00 $500.00 +2004/05/14 Pay day Income:Salary $-500.00 0 +@end smallexample -@item N -The total count of transactions affecting an account and all its -children. +The final total is zero, indicating that the budget matched exactly +for the reported period. Budgeting is most often helpful with period +reporting; for example, to show monthly budget results use +@option{--budget -p monthly}. -@item B -The total cost of all transactions seen so far; the total cost of an -account and all its children. +@c --add-budget show all transactions plus the budget +@c --unbudgeted show only unbudgeted transactions -@item V -The market value of all transactions seen so far, or of an account and -all its children. +The @option{--add-budget} option reports all matching transactions in +addition to budget transactions; while @option{--unbudgeted} shows +only those that don't match a budgeted account. To summarize: -@item G -The total net gain (market value minus cost basis), for a series of -transactions, or an account and its children. It is the same as -@samp{V-B}. +@table @option +@item --budget +Show transactions matching budgeted accounts. +@item --unbudgeted +Show transactions matching unbudgeted accounts. +@item --add-budget +Show both budgeted and unbudgeted transactions together (i.e., add the +generated budget transactions to the regular report). @end table -@subsection Functions +@c --forecast EXPR generate forecast entries while EXPR is true -The available one letter functions are: +A report with the @option{--forecast} option will add budgeted +transactions while the specified value expression is true. For +example: -@table @code -@item - -Negates the argument. +@example +ledger --forecast 'd<[2005] reg ^income +@end example -@item U -The absolute (unsigned) value of the argument. +Reports: -@item S -Strips the commodity from the argument. +@smallexample +2004/05/14 Pay day Income:Salary $-500.00 $-500.00 +2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00 +2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00 +@end smallexample -@item A -The arithmetic mean of the argument; @samp{Ax} is the same as -@samp{x/n}. +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: -@item P -The present market value of the argument. The syntax @samp{P(x,d)} is -supported, which yields the market value at time @samp{d}. If no date -is given, then the current moment is used. -@end table +@example +ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp +@end example -@subsection Operators +This reports balances projected income against projected expenses, +showing the resulting total in yearly intervals until 2008. For the +case of @file{sample.dat}, which has no budgeted expenses, the result +of the above command (in November 2004) is: -The binary and ternary operators, in order of precedence, are: +@smallexample +2004/01/01 - 2004/12/31 Income:Salary $-1,000.00 $-1,000.00 + Expenses:Books $20.00 $-980.00 +2005/01/01 - 2005/12/31 Income:Salary $-6,000.00 $-6,980.00 +2006/01/01 - 2006/12/31 Income:Salary $-6,000.00 $-12,980.00 +2007/01/01 - 2007/12/31 Income:Salary $-6,000.00 $-18,980.00 +2008/01/01 - 2008/01/01 Income:Salary $-500.00 $-19,480.00 +@end smallexample -@enumerate -@item @samp{* /} -@item @samp{+ -} -@item @samp{! < > =} -@item @samp{& | ?:} -@end enumerate +@subsubsection By value expression -@subsection Complex expressions +@c -l, --limit EXPR calculate only transactions matching EXPR -More complicated expressions are possible using: +Value expressions can be quite complex, and are treated more fully in +@ref{Value expressions}. They can be used for limiting a report with +@option{--limit} (@option{-l}). The following command report income +since august, but expenses since october: -@table @code -@item NUM -A plain integer represents a commodity-less amount. +@example +ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg +@end example -@item @{AMOUNT@} -An amount in braces can be any kind of amount supported by ledger, -with or without a commodity. Use this for decimal values. +The basic form of this value expression is @samp{(A&B)|(A&B)}. The +@samp{A} in each part matches against an account name with +@samp{/name/}, while each @samp{B} part compares the date of the +transaction (@samp{d}) with a specified month. The resulting report +will contain only transactions which match the value expression. -@item /REGEXP/ -@item W/REGEXP/ -A regular expression that matches against an account's full name. If -a transaction, this will match against the account affected by the -transaction. +@c -t, --amount EXPR use EXPR to calculate the displayed amount +@c -T, --total EXPR use EXPR to calculate the displayed total -@item //REGEXP/ -@item p/REGEXP/ -A regular expression that matches against an entry's payee name. +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: -@item ///REGEXP/ -@item w/REGEXP/ -A regular expression that matches against an account's base name. If -a transaction, this will match against the account affected by the -transaction. +@example +ledger -t 'a/2' reg ^exp +@end example -@item c/REGEXP/ -A regular expression that matches against the entry code (the text -that occurs between parentheses before the payee name). +The @option{-t} option doesn't affect the running total, only how the +transaction amount is displayed. To change the running total, use +@option{-T}. In that case, you will likely want to use the total +(@samp{O}) instead of the amount (@samp{a}): -@item e/REGEXP/ -A regular expression that matches against a transaction's note, or -comment field. +@example +ledger -T 'O/2' reg ^exp +@end example -@item (EXPR) -A sub-expression is nested in parenthesis. This can be useful passing -more complicated arguments to functions, or for overriding the natural -precedence order of operators. +@subsection Massaging register output -@item [DATE] -Useful specifying a date in plain terms. For example, you could say -@samp{[2004/06/01]}. -@end table +Even after filtering down your data to just the transactions you're +interested in, the default reporting method of one transaction per +line is often still too much. To combat this complexity, it is +possible to ask Ledger to report the details to you in many different +forms, summarized in various ways. This is the ``display'' phase of +Ledger, and is documented under @option{--help-disp}. -@node Period expressions, File format, Value expressions, Running Ledger -@section Period expressions +@subsubsection Summarizing -A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: +@c -n, --collapse register: collapse entries with multiple transactions + +When multiple transactions relate to a single entry, they are reported +as part of that entry. For example, in the case of @file{sample.dat}: @example -[INTERVAL] [BEGIN] [END] +ledger reg -- book @end example -The optional @var{INTERVAL} part may be any one of: +Reports: -@example -every day -every week -every monthly -every quarter -every year -every N days # N is any integer -every N weeks -every N months -every N quarters -every N years -daily -weekly -biweekly -monthly -bimonthly -quarterly -yearly -@end example +@smallexample +2004/05/29 Book Store Expenses:Books $20.00 $20.00 + Liabilities:MasterCard $-20.00 0 + (Liabilities:Taxes) $-2.00 $-2.00 +@end smallexample -After the interval, a begin time, end time, both or neither may be -specified. As for the begin time, it can be either of: +All three transactions are part of one entry, and as such the entry +details are printed only once. To report every entry on a single +line, use @option{-n} to collapse entries with multiple transactions: @example -from -since +ledger -n reg -- book @end example -The end time can be either of: +Reports: -@example -to -until -@end example +@smallexample +2004/05/29 Book Store $-2.00 $-2.00 +@end smallexample -Where @var{SPEC} can be any of: +In the balance report, @option{-n} causes the grand total not to be +displayed at the bottom of the report. -@example -2004 -2004/10 -2004/10/1 -10/1 -october -oct -this week # or day, month, quarter, year -next week -last week -@end example +@c -s, --subtotal balance: show sub-accounts; other: show subtotals -The beginning and ending can be given at the same time, if it spans a -single period. In that case, just use @var{SPEC} by itself. In that -case, the period @samp{oct}, for example, will cover all the days in -october. The possible forms are: +If an account occurs more than once in a report, it is possible to +combine them all and report the total per-account, using @option{-s}. +For example, this command: @example - -in +ledger -B reg ^assets @end example -Here are a few examples of period expressions: +Reports: -@example -monthly -monthly in 2004 -weekly from oct -weekly from last month -from sep to oct -from 10/1 to 10/5 -monthly until 2005 -from apr -until nov -last oct -weekly last august -@end example +@smallexample +2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 +2004/05/01 Investment balance Assets:Brokerage $1,500.00 $2,500.00 +2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 +2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 +@end smallexample -@node File format, Some typical queries, Period expressions, Running Ledger -@section File format +But if the @option{-s} option is added, the result becomes: -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. +@smallexample +2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00 + Assets:Brokerage $1,500.00 $2,980.00 +@end smallexample -The initial character of each line determines what the line means, and -how it should be interpreted. Allowable initial characters are: +When account subtotaling is used, only one entry is printed, and the +date and name reflect the range of the combined transactions. -@table @code -@item NUMBER -A line beginning with a number denotes an entry. It may be followed -by any number of lines, each beginning with whitespace, to denote the -entry's account transactions. The format of the first line is: +@c -P, --by-payee show summarized totals by payee -@example -DATE[=EDATE] [*|!] [(CODE)] DESC -@end example +With @option{-P}, transactions relating to the same payee are +combined. In this case, the date of the combined entry is that of the +latest transaction. -If @samp{*} appears after the date (with optional effective date), it -indicates the entry is ``cleared'', which can mean whatever the user -wants it t omean. If @samp{!} appears after the date, it indicates d -the entry is ``pending''; i.e., tentatively cleared from the user's -point of view, but not yet actually cleared. If a @samp{CODE} appears -in parentheses, it may be used to indicate a check number, or the type -of the transaction. Following these is the payee, or a description of -the transaction. +@c -x, --comm-as-payee set commodity name as the payee, for reporting -The format of each following transaction is: +@option{-x} changes the payee name for each transaction to be the same +as the commodity it uses. This can be especially useful combined with +other options, like @option{-P}. For example: @example - ACCOUNT AMOUNT [; NOTE] +ledger -Px reg ^assets @end example -The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual -transactions, or square brackets if it is a virtual transactions that -must balance. The @samp{AMOUNT} can be followed by a per-unit -transaction cost, by specifying @samp{@@ AMOUNT}, or a complete -transaction cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may -specify an actual and/or effective date for the transaction by using -the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or -@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. +Reports: -@item = -An automated entry. A value expression must appear after the equal -sign. +@smallexample +2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 +2004/05/01 AAPL Assets:Brokerage 50 AAPL $1,480.00 + 50 AAPL +@end smallexample -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. +This reports shows the subtotal for each commodity held, and where it +is located. To see the basis cost, or initial investment, add +@option{-B}. Applied to the example above: -@item ~ -A period entry. A period expression must appear after the tilde. +@smallexample +2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 +2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00 +@end smallexample -After this initial line there should be a set of one or more -transactions, just as if it were normal entry. +@c -E, --empty balance: show accounts with zero balance -@item ! -A line beginning with an exclamation mark denotes a command directive. -It must be immediately followed by the command word. The supported -commands are: +The only other options which affect summarized totals is @option{-E}, +which works only in the balance report. In this case, it shows +matching accounts with a zero a balance, which are ordinarily +excluded. This can be useful to see all the accounts involved in a +report, even if some have no total. -@table @samp -@item !include -Include the stated ledger file. +@subsubsection Quick periods -@item !account -The account name is given is taken to be the parent of all -transactions that follow, until @samp{!end} is seen. +Although the @option{-p} option (also @option{--period}) is much more +versatile, there are other options to make the most common period +reports easier: -@item !end -Ends an account block. +@table @option +@item -W, --weekly +Show weekly sub-totals. Same as @samp{-p weekly}. +@item -M, --monthly +Show monthly sub-totals. Same as @samp{-p monthly}. +@item -Y, --yearly +Show yearly sub-totals. Same as @samp{-p yearly}. @end table -@item ; -A line beginning with a colon indicates a comment, and is ignored. +@c --dow show a days-of-the-week report -@item Y -If a line begins with a capital Y, it denotes the year used for all -subsequent entries that give a date without a year. The year should -appear immediately after the Y, for example: @samp{Y2004}. This is -useful at the beginning of a file, to specify the year for that file. -If all entries specify a year, however, this command has no effect. +There is one kind of period report cannot be done with @option{-p}. +This is the @option{--dow}, or ``days of the week'' report, which +shows summarized totals for each day of the week. The following +examples shows a ``day of the week'' report of income and expenses: -@item P -Specifies a historical price for a commodity. These are usually found -in a pricing history file (see the @option{-Q} option). The syntax -is: @example -P DATE SYMBOL PRICE +ledger --dow reg ^inc ^exp @end example -@item N SYMBOL -Indicates that pricing information is to be ignored for a given -symbol, nor will quotes ever be downloaded for that symbol. Useful -with a home currency, such as the dollar ($). It is recommended that -these pricing options be set in the price database file, which -defaults to @file{~/.pricedb}. The syntax for this command is: -@example -N SYMBOL -@end example +Reports: + +@smallexample +2004/05/27 Thursdays Expenses:Books $20.00 $20.00 +2004/05/14 Fridays Income:Salary $-500.00 $-480.00 +@end smallexample + +@subsubsection Ordering and width + +@c -S, --sort EXPR sort report according to the value expression EXPR + +The transactions displayed in a report are shown in the same order as +they appear in the ledger file. To change the order and sort a +report, use the @option{--sort} option. @option{--sort} takes a value +expression to determine the value to sort against, making it possible +to sort according to complex criteria. Here are some simple and +useful examples: -@item D AMOUNT -Specifies the default commodity to use, by specifying an amount in the -expected format. The @command{entry} command will use this commodity -as the default when none other can be determined. This command may be -used multiple times, to set the default flags for different -commodities; whichever is seen last is used as the default commodity. -For example, to set US dollars as the default commodity, while also -setting the thousands flag and decimal flag for that commodity, use: @example -D $1,000.00 +ledger --sort d reg ^exp # sort by date +ledger --sort t reg ^exp # sort by amount total +ledger --sort -t reg ^exp # reverse sort by amount total +ledger --sort Ut reg ^exp # sort by abs amount total @end example -@item C AMOUNT1 = AMOUNT2 -Specifies a commodity conversion, where the first amount is given to -be equivalent to the second amount. The first amount should use the -decimal precision desired during reporting: +For the balance report, you will want to use @samp{T} instead of +@samp{t}: + @example -C 1.00 Kb = 1024 bytes +ledger --sort T reg ^exp # sort by amount total +ledger --sort -T reg ^exp # reverse sort by amount total +ledger --sort UT reg ^exp # sort by abs amount total @end example -@item i, o, b, h -These four relate to timeclock support, which permits ledger to read -timelog files. See the timeclock's documentation for more info on the -syntax of its timelog files. -@end table +The @option{--sort} options sorts all transactions in a report. If +periods are used (such as @option{--monthly}), this can get somewhat +confusing. In that case, you'll probably want to sort within periods +using @option{--period-sort} instead of @option{--sort}. -@node Some typical queries, Budgeting and forecasting, File format, Running Ledger -@section Some typical queries +@c -w, --wide for the default register report, use 132 columns -A query such as the following shows all expenses since last -October, sorted by total: +And if the register seems too cramped, and you have a lot of screen +real estate, you can use @option{-w} to format the report within 132 +acolumns, instead of 80. You are more likely then to see full payee +and account names, as well as properly formatted totals when +long-named commodities are used. + +If you want only the first or last N entries to be printed---which can +be very useful for viewing the last 10 entries in your checking +account, while also showing the cumulative balance from all +entries---use the @option{--head} and/or @option{--tail} options. The +two options may be used simultaneously, for example: @example -ledger -b "last oct" -s -S T bal ^expenses +ledger --tail 20 reg checking @end example -From left to right the options mean: Show entries since October, 2003; -show all sub-accounts; sort by the absolute value of the total; and -report the balance for all expenses. +If the output from your command is very long, Ledger can output the +data to a pager utility, such as @command{more} or @command{less}: -@subsection Reporting monthly expenses +@example +ledger --pager /usr/bin/less reg checking +@end example -The following query makes it easy to see monthly expenses, with each -month's expenses sorted by the amount: +@subsubsection Averages and percentages + +@c -A, --average report average transaction amount + +To see the running total changed to a running average, use +@option{-A}. The final transaction's total will be the overall +average of all displayed transactions. The works in conjunction with +period reporting, so that you can see your monthly average expenses +with: @example -ledger -M --period-sort t reg ^expenses +ledger -AM reg ^expenses:food +ledger -AMn reg ^expenses @end example -Now, you might wonder where the money came from to pay for these -things. To see that report, add @option{-r}, which shows the -``related account'' transactions: +This works in the balance report too: @example -ledger -M --period-sort t -r reg ^expenses +ledger -AM bal ^expenses:food +ledger -AMs bal ^expenses @end example -But maybe this prints too much information. You might just want to -see how much you're spending with your MasterCard. That kind of query -requires the use of a display predicate, since the transactions -calculated must match @samp{^expenses}, while the transactions -displayed must match @samp{mastercard}. The command would be: +@c -D, --deviation report deviation from the average + +The @option{-D} option changes the running average into a deviation +from the running average. This only makes sense in the register +report, however. @example -ledger -M -r -d /mastercard/ reg ^expenses +ledger -DM reg ^expenses:food @end example -This query says: Report monthly subtotals; report the ``related -account'' transactions; display only related transactions whose -account matches @samp{mastercard}, and base the calculation on -transactions matching @samp{^expenses}. +@c -%, --percentage report balance totals as a percentile of the parent -This works just as well for report the overall total, too: +In the balance report only, @option{-%} changes the reported totals +into a percentage of the parent account. This kind of report is +confusing if negative amounts are involved, and doesn't work at all if +multiple commodities occur in an account's history. It has a somewhat +limited usefulness, therefore, but in certain cases it can be handy, +such as reviewing overall expenses: @example -ledger -s -r -d /mastercard/ reg ^expenses +ledger -%s -S T bal ^expenses @end example -The @option{-s} option subtotals all transactions, just as @option{-M} -subtotaled by the month. The running total in both cases is off, -however, since a display expression is being used. +@subsubsection Reporting total data -@subsection Visualizing with Gnuplot +@c --totals in the "xml" report, include running total -If you have @command{Gnuplot} installed, you can graph any of the -above register reports. The script to do this is included in the -ledger distribution, and is named @file{scripts/report}. Install -@file{report} anywhere along your @env{PATH}, and then use -@command{report} instead of @command{ledger} when doing a register -report. The only thing to keep in mind is that you must specify -@option{-j} or @option{-J} to indicate whether Gnuplot should plot the -amount, or the running total. For example, this command plots total -monthly expenses made on your MasterCard. +Normally in the @command{xml} report, only transaction amounts are +printed. To include the running total under a @samp{} tag, use +@option{--totals}. This does not affect any other report. + +@c -j, --amount-data print only raw amount data (useful for scripting) +@c -J, --total-data print only raw total data + +In the register report only, the output can be changed with +@option{-j} to show only the date and the amount---without +commodities. This only makes sense if a single commodity appears in +the report, but can be quite useful for scripting, or passing the data +to Gnuplot. To show only the date and running total, use @option{-J}. + +@subsubsection Display by value expression + +@c -d, --display EXPR display only transactions matching EXPR + +With @option{-d} you can decide which transactions (or accounts in the +balance report) are displayed, according to a value expression. The +computed total is not affected, only the display. This can be very +useful for shortening a report without changing the running total: @example -report -j -M -r -d /mastercard/ reg ^expenses +ledger -d 'd>=[last month]' reg checking @end example -The @command{report} script is a very simple Bourne shell script, that -passes a set of scripted commands to Gnuplot. Feel free to modify the -script to your liking, since you may prefer histograms to line plots, -for example. - -@subsubsection Typical plots +This command shows the checking account's register, beginning from +last month, but with the running total reflecting the entire history +of the account. -Here are some useful plots: +@subsubsection Change report format -@smallexample -report -j -M reg ^expenses # monthly expenses -report -J reg checking # checking account balance -report -J reg ^income ^expenses # cash flow report +@c -y, --date-format STR use STR as the date format (default: %Y/%m/%d) -# net worth report, ignoring non-$ transactions +When dates are printed in any report, the default format is +@samp{%Y/%m/%d}, which yields dates of the form @samp{YYYY/mm/dd}. +This can be changed with @option{-y}, whose argument is a +@code{strftime} string---see your system's C library documentation for +the allowable codes. Mostly you will want to use @samp{%Y}, @samp{%m} +and @samp{%d}, in whatever combination is convenient for your locale. -report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab +@c -F, --format STR use STR as the format; for each report type, use: +@c --balance-format --register-format --print-format +@c --plot-amount-format --plot-total-format --equity-format +@c --prices-format --wide-register-format -# 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 +To change the format of the entire reported line, use @option{-F}. It +supports quite a large number of options, which are all documented in +@ref{Format strings}. In addition, each specific kind of report +(except for @command{xml}) can be changed using one of the following +options: -report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab +@table @option +@item --balance-format +@command{balance} report. Default: +@smallexample +%20T %2_%-a\n @end smallexample -The last report uses both a calculation predicate (@option{-l}) and a -display predicate (@option{-d}). The calculation predicates limits -the report to transactions whose amount is greater than $1 (which can -only happen if the transaction amount is in dollars). The display -predicate limits the entries @emph{displayed} to just those since last -February, even those entries from before then will be computed as part -of the balance. - -@node Budgeting and forecasting, , Some typical queries, Running Ledger -@section Budgeting and forecasting +@item --register-format +@command{register} report. Default: +@smallexample +%D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n +@end smallexample -@subsection Budgeting +@item --print-format +@command{print} report. Default: +@smallexample +%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n +@end smallexample -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. +@item --plot-amount-format +@command{register} report when @option{-j} (plot amount) is used. Default: +@smallexample +%D %(St)\n +@end smallexample -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: +@item --plot-total-format +@command{register} report when @option{-J} (plot total) is used. Default: +@smallexample +%D %(ST)\n +@end smallexample +@item --equity-format +@command{equity} report. Default: @smallexample -~ 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 +\n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n +@end smallexample -~ Yearly - Expenses:Auto:Repair $500.00 - Assets +@item --prices-format +@command{prices} report. Default: +@smallexample +\n%D %Y%C%P\n%/ %-34W %12t\n @end smallexample -These two period entries give the usual monthly expenses, as well as -one typical yearly expense. For help on finding out what your average -monthly expense is for any category, use a command like: +@item --wide-register-format +@command{register} report when @option{-w} (wide) is used. Default: +@smallexample +%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n +@end smallexample +@end table -@example -ledger -p "this year" -MAs bal ^expenses -@end example +@subsection Standard queries -The reported totals are the current year's average for each account. +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. -Once these period entries are defined, creating a budget report is as -easy as adding @option{--budget} to the command-line. For example, a -typical monthly expense report would be: +Your @emph{net worth} can be determined by balancing assets against +liabilities: @example -ledger -M reg ^exp +ledger bal ^assets ^liab @end example -To see the same report balanced against your budget, use: +By removing long-term investment and loan accounts, you can see your +current net liquidity (or liquid net worth): @example -ledger --budget -M reg ^exp +ledger bal ^assets ^liab -retirement -brokerage -loan @end example -A budget report includes only those accounts that appear in the -budget. To see all expenses balanced against the budget, use -@option{--add-budget}. You can even see only the unbudgeted expenses -using @option{--unbudgeted}: +Balancing expenses against income yields your @emph{cash flow}, or net +profit/loss: @example -ledger --unbudgeted -M reg ^exp +ledger bal ^exp ^inc @end example -You can also use these flags with the @command{balance} command. +In this case, if the number is positive it means you spent more than +you earned during the report period. -@subsection Forecasting +@c ---------------------------------------------------------------------- -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: +The most often used command is the ``balance'' command: @example -ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities +export LEDGER=/home/johnw/doc/ledger.dat +ledger balance @end example -This report continues outputting transactions until the running total -is greater than $-500.00. A final transaction is always output, to -show you what the total afterwards would be. +Here I've set my Ledger environment variable to point to where my +ledger file is hiding. Thereafter, I needn't specify it again. -Forecasting can also be used with the balance report, but by date -only, and not against the running total: +@subsection Reporting balance totals + +The balance command prints out the summarized balances of all my +top-level accounts, excluding sub-accounts. In order to see the +balances for a specific account, just specify a regular expression +after the balance command: @example -ledger --forecast "d<[2010]" bal ^assets ^liabilities +ledger balance expenses:food @end example -@node Keeping a ledger, Using XML, Running Ledger, Top -@chapter Keeping a ledger - -The most important part of accounting is keeping a good ledger. If -you have a good ledger, tools can be written to work whatever -mathematically tricks you need to better understand your spending -patterns. Without a good ledger, no tool, however smart, can help -you. - -The Ledger program aims at making ledger entry as simple as possible. -Since it is a command-line tool, it does not provide a user interface -for keeping a ledger. If you like, you may use GnuCash to maintain -your ledger, in which case the Ledger program will read GnuCash's data -files directly. In that case, read the GnuCash manual now, and skip -to the next chapter. - -If you are not using GnuCash, but a text editor to maintain your -ledger, read on. Ledger has been designed to make data entry as -simple as possible, by keeping the ledger format easy, and also by -automagically determining as much information as possible based on the -nature of your entries. +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: -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. +@example +ledger -p sep balance expenses:food +@end example -Here is the Pacific Bell example from above, given as a Ledger -transaction: +Or maybe you want to see all of your assets, in which case the -s +(show sub-accounts) option comes in handy: -@smallexample -9/29 (100) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking $-23.00 -@end smallexample +@example +ledger -s balance ^assets +@end example -As you can see, it is very similar to what would be written on paper, -minus the computed balance totals, and adding in account names that -work better with Ledger's scheme of things. In fact, since Ledger is -smart about many things, you don't need to specify the balanced -amount, if it is the same as the first line: +To exclude a particular account, use a regular expression with a +leading minus sign. The following will show all expenses, but without +food spending: -@smallexample -9/29 (100) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking -@end smallexample +@example +ledger balance expenses -food +@end example -For this entry, Ledger will figure out that $-23.00 must come from -@samp{Assets:Checking} in order to balance the entry. +@subsection Reporting percentages -@menu -* Stating where money goes:: -* Assets and Liabilities:: -* Commodities and Currencies:: -* Accounts and Inventories:: -* Understanding Equity:: -* Dealing with Petty Cash:: -* Working with multiple funds and accounts:: -* Archiving previous years:: -* Virtual transactions:: -* Automated transactions:: -* Using Emacs to Keep Your Ledger:: -* Using GnuCash to Keep Your Ledger:: -* Using timeclock to record billable time:: -@end menu +There is no built-in way to report transaction amounts or account +balances in terms of percentages -@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger +@node Stating where money goes, Assets and Liabilities, Usage overview, Ledger in Practice @section Stating where money goes Accountants will talk of ``credits'' and ``debits'', but the meaning @@ -2791,7 +2791,7 @@ place has less money now than when you started your ledger; and every positive figure means that that account or person or place has more money now that when you started your ledger. Make sense? -@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger +@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Ledger in Practice @section Assets and Liabilities Assets are money that you have, and Liabilities are money that you @@ -3006,7 +3006,7 @@ spent using your MasterCard on behalf of Company XYZ, and that Company XYZ spent the money on computer software and paid it back about two weeks later. -@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger +@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Ledger in Practice @section Commodities and Currencies Ledger makes no assumptions about the commodities you use; it only @@ -3172,7 +3172,7 @@ smallest commodity is used. If a commodity could be reported in terms of a higher commodity without resulting to a partial fraction, then the larger commodity is used. -@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger +@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Ledger in Practice @section Accounts and Inventories Since Ledger's accounts and commodity system is so flexible, you can @@ -3210,7 +3210,7 @@ would look like: Now you've turned 2 steaks into 15 gold, courtesy of your customer, Sturm Brightblade. -@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Keeping a ledger +@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Ledger in Practice @section Understanding Equity The most confusing entry in any ledger will be your equity account--- @@ -3249,7 +3249,7 @@ Clear as mud? Keep thinking about it. Until you figure it out, put @samp{-Equity} at the end of your balance command, to remove the confusing figure from the total. -@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Keeping a ledger +@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Ledger in Practice @section Dealing with Petty Cash Something that stops many people from keeping a ledger at all is the @@ -3280,7 +3280,7 @@ the target account: This way, you can still track large cash expenses, while ignoring all of the smaller ones. -@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Keeping a ledger +@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Ledger in Practice @section Working with multiple funds and accounts There are situations when the accounts you're tracking are different @@ -3416,7 +3416,7 @@ you prefer to think of your funds: as virtual accounts, or as tags associated with particular entries. Your own tastes will decide which is best for your situation. -@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Keeping a ledger +@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Ledger in Practice @section Archiving previous years After a while, your ledger can get to be pretty large. While this @@ -3476,7 +3476,7 @@ any electronic statements received during the year. In the arena of organization, just keep in mind this maxim: Do whatever keeps you doing it. -@node Virtual transactions, Automated transactions, Archiving previous years, Keeping a ledger +@node Virtual transactions, Automated transactions, Archiving previous years, Ledger in Practice @section Virtual transactions A virtual transaction is when you, in your mind, see money as moving @@ -3517,7 +3517,7 @@ When balances are displayed, virtual transactions will be factored in. To view balances without any virtual balances factored in, using the @option{-R} flag, for ``reality''. -@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Keeping a ledger +@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Ledger in Practice @section Automated transactions As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. @@ -3595,7 +3595,7 @@ This example causes 10% of the matching account's total to be deferred to the @samp{Savings} account---as a balanced virtual transaction, which may be excluded from reports by using @option{--real}. -@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Keeping a ledger +@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Ledger in Practice @section Using Emacs to Keep Your Ledger In the Ledger tarball is an Emacs module, @file{ledger.el}. This @@ -3698,7 +3698,7 @@ Quit the reconcile buffer. There is also an @command{emacs} command which can be used to output reports in a format directly @code{read}-able from Emacs Lisp. -@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Keeping a ledger +@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Ledger in Practice @section Using GnuCash to Keep Your Ledger The Ledger tool is fast and simple, but it offers no custom method for @@ -3715,7 +3715,7 @@ 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? -@node Using timeclock to record billable time, , Using GnuCash to Keep Your Ledger, Keeping a ledger +@node Using timeclock to record billable time, Using XML, Using GnuCash to Keep Your Ledger, Ledger in Practice @section Using timeclock to record billable time The timeclock tool makes it easy to track time events, like clocking @@ -3806,13 +3806,13 @@ accounting ledger, with the attached prefix @samp{Billable}: Receivable:ClientOne @end smallexample -@node Using XML, , Keeping a ledger, Top -@chapter Using XML +@node Using XML, , Using timeclock to record billable time, Ledger in Practice +@section 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. +display data using XML. This section documents that format. The general format used for Ledger data is: -- cgit v1.2.3