diff options
Diffstat (limited to 'doc/ledger3.texi')
| -rw-r--r-- | doc/ledger3.texi | 1407 |
1 files changed, 761 insertions, 646 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index fa5a4a5a..13baef72 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual Time-stamp: <2011-11-15 13:51 (cpearls)> +@subtitle Draft Manual Time-stamp: <2011-11-16 22:34 (cpearls)> @author John Wiegley @end titlepage @@ -71,8 +71,9 @@ twinkling in their father's CRT. * Ledger Tutorial :: * Principles of Accounting:: * Keeping a Journal:: -* Command-line Syntax:: +* Building Reports:: * Reporting Commands:: +* Command-line Syntax:: * Budgeting and Forecasting:: * Value Expressions:: * Format Strings:: @@ -1432,7 +1433,7 @@ associated with particular transactions. Your own tastes will decide which is best for your situation. -@node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top +@node Keeping a Journal, Building Reports, Principles of Accounting, Top @chapter Keeping a Journal The most important part of accounting is keeping a good journal. If you @@ -2614,7 +2615,7 @@ and saved for future use as a named report from the generated reports buffer. In a report buffer, the following keys are available: -@table @code +@table @code @item (space) scroll up @item e @@ -2630,676 +2631,125 @@ kill the report buffer @end table -@node Command-line Syntax, Reporting Commands, Keeping a Journal, Top -@chapter Command-line Syntax +@node Building Reports, Reporting Commands, Keeping a Journal, Top +@chapter Building Reports @menu -* Basic Usage:: -* Detailed Options Description:: -* Period Expressions:: +* Introduction:: +* Balance Reports:: @end menu -@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax -@section Basic Usage - -This chapter describes Ledger's features and options. You may wish to -survey this to get an overview before diving in to the @ref{Ledger -Tutorial} and more detailed examples that follow. - -Ledger has a very simple command-line interface, named---enticingly -enough---@command{ledger}. It supports a few reporting commands, and -a large number of options for refining the output from those commands. -The basic syntax of any ledger command is: - -@smallexample -ledger [OPTIONS...] COMMAND [ARGS...] -@end smallexample - -After the command word there may appear any number of arguments. For -most commands, these arguments are regular expressions that cause the -output to relate only to postings matching those regular expressions. -For the @command{transaction} command, the arguments have a special -meaning, described below. - -The regular expressions arguments always match the account name that a -posting refers to. To match on the payee of the transaction instead, -precede the regular expression with @samp{payee} or @@. For example, the -following balance command reports account totals for rent, food and -movies, but only those whose payee matches Freddie: - -@smallexample -ledger bal rent food movies payee freddie -@end smallexample -@noindent or -@smallexample -ledger bal rent food movies @@freddie -@end smallexample - -There are many, many command options available with the -@command{ledger} command, and it takes a while to master them. -However, none of them are required to use the basic reporting -commands. - - - - - - - - - -@node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax -@section Detailed Option Description - -With all of the reports, command-line options are useful to modify the -output generated. The basic form for most commands is: - -@smallexample -ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] -@end smallexample - -The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. -You could just use @samp{ledger balance}, without any options---which -prints a summary of all accounts. But for more specific reporting, or -to change the appearance of the output, options are needed. - -@subsection Basic options - -These are the most basic command options. Most likely, the user will -want to set them using environment variables (see @ref{Environment Variables}), -instead of using actual command-line options: - -@option{--help} (@option{-h}) prints a summary of all the options, and -what they are used for. This can be a handy way to remember which -options do what. This help screen is also printed if ledger is run -without a command. - -@option{--version} (@option{-v}) prints the current version of ledger -and exits. This is useful for sending bug reports, to let the author -know which version of ledger you are using. - -@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. -This command may be used multiple times. -Typically, the environment variable -@env{LEDGER_FILE} is set, rather than using this command-line option. - -@option{--output FILE} (@option{-o FILE}) redirects output from any -command to @var{FILE}. By default, all output goes to standard -output. - -@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by -ledger before any other ledger file. This file may not contain any -postings, but it may contain option settings. To specify options -in the init file, use the same syntax as the command-line, but put each -option on it's own line. Here's an example init file: - -@smallexample ---price-db ~/finance/.pricedb - -; ~/.ledgerrc ends here -@end smallexample - -Option settings on the command-line or in the environment always take -precedence over settings in the init file. - - -@option{--account NAME} (@option{-a NAME}) specifies the default -account which QIF file postings are assumed to relate to. - -@subsection Report filtering - -These options change which postings affect the outcome of a -report, in ways other than just using regular expressions: - -@option{--current}(@option{-c}) displays only transactions occurring on or -before the current date. - -@option{--begin DATE} (@option{-b DATE}) constrains the report to -transactions on or after @var{DATE}. Only transactions after that date will be -calculated, which means that the running total in the balance report -will always start at zero with the first matching transaction. (Note: This -is different from using @option{--display} to constrain what is -displayed). - -@option{--end DATE} (@option{-e DATE}) constrains the report so that -transactions on or after @var{DATE} are not considered. The ending date -is inclusive. - -@option{--period STR} (@option{-p STR}) sets the reporting period -to @var{STR}. This will subtotal all matching transactions within each -period separately, making it easy to see weekly, monthly, quarterly, -etc., posting totals. A period string can even specify the -beginning and end of the report range, using simple terms like ``last -june'' or ``next month''. For more using period expressions, see -@ref{Period Expressions}. - -@option{--period-sort EXPR} sorts the postings within each -reporting period using the value expression @var{EXPR}. This is most -often useful when reporting monthly expenses, in order to view the -highest expense categories at the top of each month: - -@smallexample -ledger -M --period-sort -At reg ^Expenses -@end smallexample - -@option{--cleared} (@option{-C}) displays only postings whose transaction -has been marked ``cleared'' (by placing an asterix to the right of the -date). - -@option{--uncleared} (@option{-U}) displays only postings whose -transaction has not been marked ``cleared'' (i.e., if there is no asterix to -the right of the date). - -@option{--real} (@option{-R}) displays only real postings, not virtual. -(A virtual posting is indicated by surrounding the account name with -parentheses or brackets; see @ref{Virtual Transactions} for more -information). - -@option{--actual} (@option{-L}) displays only actual postings, and -not those created due to automated postings. - -@option{--related} (@option{-r}) displays postings that are -related to whichever postings would otherwise have matched the -filtering criteria. In the register report, this shows where money -went to, or the account it came from. In the balance report, it shows -all the accounts affected by transactions having a related posting. -For example, if a file had this transaction: - -@smallexample -2004/03/20 Safeway - Expenses:Food $65.00 - Expenses:Cash $20.00 - Assets:Checking $-85.00 -@end smallexample - -And the register command was: - -@smallexample -ledger -r register food -@end smallexample - -The following would be output, showing the postings related to the -posting that matched: - -@smallexample -2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 -@end smallexample - -@option{--budget} is useful for displaying how close your postings -meet your budget. @option{--add-budget} also shows unbudgeted -postings, while @option{--unbudgeted} shows only those. -@option{--forecast} is a related option that projects your budget into -the future, showing how it will affect future balances. -@xref{Budgeting and Forecasting}. - -@option{--limit EXPR} (@option{-l EXPR}) limits which postings -take part in the calculations of a report. - -@option{--amount EXPR} (@option{-t EXPR}) changes the value expression -used to calculate the ``value'' column in the @command{register} -report, the amount used to calculate account totals in the -@command{balance} report, and the values printed in the -@command{equity} report. @xref{Value Expressions}. - -@option{--total EXPR} (@option{-T EXPR}) sets the value expression -used for the ``totals'' column in the @command{register} and -@command{balance} reports. - +@node Introduction, Balance Reports, Building Reports, Building Reports +@section Introduction +The power of Ledger comes from the incredible flexibility in its +reporting commands, combined with formatting commands. Some options +control what is included in the calculations, and formatting controlls +how it is displayed. The combinations are infinite. This chapter will +show you the basics of combining varous options and commands. In the next +chapters you will find details about the specific commands and +options. + +@node Balance Reports, , Introduction, Building Reports +@section Balance Reports @menu -* Search Terms:: -* Output Customization:: -* Commodity Reporting:: -* Environment Variables:: +* Controlling the Accounts and Payees:: +* Controlling formatting:: @end menu -@node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description -@subsection Search Terms - -Valid Ledger invocations look like: -@smallexample - ledger [OPTIONS] <COMMAND> <SEARCH-TERMS> -@end smallexample - -Where @samp{COMMAND} is any command verb (@pxref{Reporting Commands}), @samp{OPTIONS} can occur -anywhere, and @samp{SEARCH-TERM} is one or more of the following: - -@smallexample - word search for any account containing 'word' - TERM and TERM boolean AND between terms - TERM or TERM boolean OR between terms - not TERM invert the meaning of the term - payee word search for any payee containing 'word' - @@word shorthand for 'payee word' - desc word alternate for 'payee word' - note word search for any note containing 'word' - &word shorthand for 'note word' - tag word search for any metadata tag containing 'word' - tag word=value search for any metadata tag containing 'word' - whose value contains 'value' - %word shorthand for 'tag word' - %word=value shorthand for 'tag word=value' - meta word alternate for 'tag word' - meta word=value alternate for 'tag word=value' - expr 'EXPR' apply the given value expression as a predicate - '=EXPR' shorthand for 'expr EXPR' - \( TERMS \) group terms; useful if using and/or/not -@end smallexample - -So, to list all transaction that charged to ``food'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent: - -@smallexample - ledger reg food not dining @@chang - ledger reg food and not dining and not payee chang - ledger reg food not dining expr 'payee =~ /chang/' -@end smallexample - -@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description -@subsection Output Customization - -These options affect only the output, but not which postings are -used to create it: - -@option{--collapse} (@option{-n}) causes transactions in a -@command{register} report with multiple postings to be collapsed -into a single, subtotaled transaction. - -@option{--subtotal} (@option{-s}) causes all transactions in a -@command{register} report to be collapsed into a single, subtotaled -transaction. - -@option{--by-payee} (@option{-P}) reports subtotals by payee. - -@option{--comm-as-payee} (@option{-x}) changes the payee of every -posting to be the commodity used in that posting. This can be -useful when combined with other options, such as @option{-s}. - -@option{--empty} (@option{-E}) includes even empty accounts in the -@command{balance} report. - -@option{--weekly} (@option{-W}) reports posting totals by the -week. The week begins on whichever day of the week begins the month -containing that posting. To set a specific begin date, use a -period string, such as @samp{weekly from DATE}. @option{--monthly} -(@option{-M}) reports posting totals by month; @option{--yearly} -(@option{-Y}) reports posting totals by year. For more complex -period, using the @option{--period} option described above. - -@option{--dow} reports postings totals for each day of the week. -This is an easy way to see if weekend spending is more than on -weekdays. - -@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing -the values determined using the value expression @var{EXPR}. For -example, using @option{-S -UT} in the balance report will sort account -balances from greatest to least, using the absolute value of the -total. For more on how to use value expressions, see @ref{Value -Expressions}. - -@option{--pivot TAG} produces a pivot table around the tag provided. -This requires meta data using valued tags. - -@option{--wide} (@option{-w}) causes the default @command{register} -report to assume 132 columns instead of 80. - -@option{--head} causes only the first N transactions to be printed. This -is different from using the command-line utility @command{head}, which -would limit to the first N postings. @option{--tail} outputs only -the last N transactions. Both options may be used simultaneously. If a -negative amount is given, it will invert the meaning of the flag -(instead of the first five transactions being printed, for example, it -would print all but the first five). - -@option{--pager} tells Ledger to pass its output to the given pager -program---very useful when the output is especially long. This -behavior can be made the default by setting the @env{LEDGER_PAGER} -environment variable. - -@option{--average} (@option{-A}) reports the average posting -value. - -@option{--deviation} (@option{-D}) reports each posting's -deviation from the average. It is only meaningful in the -@command{register} and @command{prices} reports. - -@option{--percent} (@option{-%}) shows account subtotals in the -@command{balance} report as percentages of the parent account. - -@c @option{--totals} include running total information in the -@c @command{xml} report. - -@option{--amount-data} (@option{-j}) changes the @command{register} -report so that it outputs nothing but the date and the value column, -and the latter without commodities. This is only meaningful if the -report uses a single commodity. This data can then be fed to other -programs, which could plot the date, analyze it, etc. - -@option{--total-data} (@option{-J}) changes the @command{register} -report so that it outputs nothing but the date and totals column, -without commodities. - -@option{--display EXPR} (@option{-d EXPR}) limits which postings -or accounts or actually displayed in a report. They might still be -calculated, and be part of the running total of a register report, for -example, but they will not be displayed. This is useful for seeing -last month's checking postings, against a running balance which -includes all posting values: - -@smallexample -ledger -d "d>=[last month]" reg checking -@end smallexample - -The output from this command is very different from the following, -whose running total includes only postings from the last month -onward: - -@smallexample -ledger -p "last month" reg checking -@end smallexample - -Which is more useful depends on what you're looking to know: the total -amount for the reporting range (@option{-p}), or simply a display -restricted to the reporting range (using @option{-d}). - -@option{--date-format STR} (@option{-y STR}) changes the basic date -format used by reports. The default uses a date like 2004/08/01, -which represents the default date format of @samp{%Y/%m/%d}. To -change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the Ledger initialization file -@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). - -@option{--format STR} (@option{-F STR}) sets the reporting format for -whatever report ledger is about to make. @xref{Format Strings}. -There are also specific format commands for each report type: - -@itemize -@item @option{--balance-format STR} -@item @option{--register-format STR} -@item @option{--print-format STR} -@item @option{--plot-amount-format STR} (-j @command{register}) -@item @option{--plot-total-format STR} (-J @command{register}) -@item @option{--equity-format STR} -@item @option{--prices-format STR} -@item @option{--wide-register-format STR} (-w @command{register}) -@end itemize - -@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description -@subsection Commodity Reporting - -These options affect how commodity values are displayed: - -@option{--price-db FILE} sets the file that is used for recording -downloaded commodity prices. It is always read on startup, to -determine historical prices. Other settings can be placed in this -file manually, to prevent downloading quotes for a specific, for -example. This is done by adding a line like the following: - -@smallexample -; Don't download quotes for the dollar, or timelog values -N $ -N h -@end smallexample - -@option{--price-exp MINS} (@option{-L MINS}) sets the expected -freshness of price quotes, in minutes. That is, if the last known -quote for any commodity is older than this value---and if -@option{--download} is being used---then the Internet will be -consulted again for a newer price. Otherwise, the old price is still -considered to be fresh enough. - -@option{--download} (@option{-Q}) causes quotes to be automagically -downloaded, as needed, by running a script named @command{getquote} -and expecting that script to return a value understood by ledger. A -sample implementation of a @command{getquote} script, implemented in -Perl, is provided in the distribution. Downloaded quote price are -then appended to the price database, usually specified using the -environment variable @env{LEDGER_PRICE_DB}. - -There are several different ways that ledger can report the totals it -displays. The most flexible way to adjust them is by using value -expressions, and the @option{-t} and @option{-T} options. However, -there are also several ``default'' reports, which will satisfy most -users basic reporting needs: - -@table @code -@item -O, --quantity -Reports commodity totals (this is the default) - -@item -B, --basis -Reports the cost basis for all postings. - -@item -V, --market -Reports the last known market value for all commodities. - -@item -G --gain -Reports the net gain/loss for all commodities in the report that have -a price history. -@end table - - -Often you will be more interested in the value of your entire holdings, -in your preferred currency. It might be nice to know you hold 10,000 -shares of PENNY, but you are more interested in whether or not that is -worth $1000.00 or $10,000.00. However, the current day value of a -commodity can mean different things to different people, depending on -the accounts involved, the commodities, the nature of the transactions, -etc. - -When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that -some or all of the commodities be valuated as of today (or whatever -@samp{--now} is set to). But what does such a valuation mean? This -meaning is governed by the presence of a @samp{VALUE} metadata property, -whose content is an expression used to compute that value. - -If no VALUE property is specified, each posting is assumed to have a -default, as if you'd specified a global, automated transaction as -follows: +@node Controlling the Accounts and Payees, Controlling formatting, Balance Reports, Balance Reports +@subsection Controlling the Accounts and Payees +The balance report is the most commonly used report. The simplest invocation is: @smallexample - = expr true - ; VALUE:: market(amount, date, exchange) +ledger balance -f drewr3.dat @end smallexample -This definition emulates the present day behavior of @samp{-V} and @samp{-X} (in the -case of @samp{-X}, the requested commodity is passed via the string 'exchange' -above). - -@cindex Euro conversion -One thing many people have wanted to do is to fixate the valuation of -old European currencies in terms of the Euro after a certain date: - +@noindent which will print the balances of every account in you journal. @smallexample - = expr commodity == "DM" - ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR -@end smallexample - -This says: If @samp{--now} is some old date, use market prices as they -were at that time; but if @samp{--now} is past June 2008, use a fixed -price for converting Deutsch Mark to Euro. - -Or how about never re-valuating commodities used in Expenses, since they -cannot have a different future value: - -@smallexample - = /^Expenses:/ - ; VALUE:: market(amount, post.date, exchange) -@end smallexample - -This says the future valuation is the same as the valuation at the time -of posting. post.date equals the posting's date, while just 'date' is -the value of @samp{--now} (defaults to today). - -Or how about valuating miles based on a reimbursement rate during a -specific time period: - - -@smallexample - = expr commodity == "miles" and date >= [2007] and date < [2008] - ; VALUE:: market($1.05, date, exchange) -@end smallexample - -In this case, miles driven in 2007 will always be valuated at $1.05 -each. If you use @samp{-X EUR} to expressly request all amounts in -Euro, Ledger shall convert $1.05 to Euro by whatever means are -appropriate for dollars. - -Note that you can have a valuation expression specific to a particular -posting or transaction, by overriding these general defaults using -specific metadata: - -@smallexample - 2010-12-26 Example - Expenses:Food $20 - ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what - ; the user asks for with -V or -X - ; VALUE:: 30 DM - Assets:Cash -@end smallexample - -This example demonstrates that your VALUE expression should be as -symbolic as possible, using terms like 'amount' and 'date', rather than -specific amounts and dates. Also, you should pass the amount along to -the function 'market' so it can be further revalued if the user has -asked for a specific currency. - -Or, if it better suits your accounting, you can be less symbolic, which -allows you to report most everything in EUR if you use -X EUR, except -for certain accounts or postings which should always be valuated in -another currency. For example: - -@smallexample - = /^Assets:Brokerage:CAD$/ - ; Always report the value of commodities in this account in - ; terms of present day dollars, despite what was asked for - ; on the command-line VALUE:: market(amount, date, '$') -@end smallexample - -@cindex FIFO/LIFO -@cindex LIFO/FIFO -Ledger presently has no way of handling such things as FIFO and LIFO. - -If you specify an unadorned commodity name, like AAPL, it will balance -against itself. If @samp{--lots} are not being displayed, then it will -appear to balance against any lot of AAPL. - -@cindex adorned commodity -If you specify an adorned commodity, like AAPL @{$10.00@}, it will also -balance against itself, and against any AAPL if @samp{--lots} is not -specified. But if you do specify @samp{--lot-prices}, for example, then -it will balance against that specific price for AAPL. - - -@node Environment Variables, , Commodity Reporting, Detailed Options Description -@subsection Environment variables - -Every option to ledger may be set using an environment variable. If -an option has a long name such @option{--this-option}, setting the -environment variable @env{LEDGER_THIS_OPTION} will have the same -affect as specifying that option on the command-line. Options on the -command-line always take precedence over environment variable -settings, however. - -Note that you may also permanently specify option values by placing -option settings in the file @file{~/.ledgerrc}, for example: - -@smallexample ---pager /bin/cat - -@end smallexample - -@node Period Expressions, , Detailed Options Description, Command-line Syntax -@section Period Expressions - -A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: - -@smallexample -[INTERVAL] [BEGIN] [END] -@end smallexample - -The optional @var{INTERVAL} part may be any one of: - -@smallexample -every day -every week -every monthly -every quarter -every year -every N days # N is any integer -every N weeks -every N months -every N quarters -every N years -daily -weekly -biweekly -monthly -bimonthly -quarterly -yearly + $ -3,804.00 Assets + $ 1,396.00 Checking + $ 30.00 Business + $ -5,200.00 Savings + $ -1,000.00 Equity:Opening Balances + $ 6,654.00 Expenses + $ 5,500.00 Auto + $ 20.00 Books + $ 300.00 Escrow + $ 334.00 Food:Groceries + $ 500.00 Interest:Mortgage + $ -2,030.00 Income + $ -2,000.00 Salary + $ -30.00 Sales + $ -63.60 Liabilities + $ -20.00 MasterCard + $ 200.00 Mortgage:Principal + $ -243.60 Tithe +-------------------- + $ -243.60 @end smallexample -After the interval, a begin time, end time, both or neither may be -specified. As for the begin time, it can be either of: - +Most times this is more than you want. Limiting the results to specific +accounts is as easy as entering the names of the accounts after the +command. @smallexample -from <SPEC> -since <SPEC> +20:37:53 ~/ledger/test/input > ledger balance -f drewr3.dat Auto MasterCard + $ 5,500.00 Expenses:Auto + $ -20.00 Liabilities:MasterCard +-------------------- + $ 5,480.00 +20:39:21 ~/ledger/test/input > @end smallexample +@noindent note the implicit logical and between @samp{Auto} and @samp{Mastercard}. -The end time can be either of: - +If you want the entire contents of a branch of your account tree, use the +highest common name in the branch: @smallexample -to <SPEC> -until <SPEC> +20:39:21 ~/ledger/test/input > ledger balance -f drewr3.dat Income + $ -2,030.00 Income + $ -2,000.00 Salary + $ -30.00 Sales +-------------------- + $ -2,030.00 +20:40:28 ~/ledger/test/input > @end smallexample -Where @var{SPEC} can be any of: - +You can use general regular expressions in nearly anyplace Ledger needs a string: @smallexample -2004 -2004/10 -2004/10/1 -10/1 -october -oct -this week # or day, month, quarter, year -next week -last week +20:40:28 ~/ledger/test/input > ledger balance -f drewr3.dat ^Bo +21:13:29 ~/ledger/test/input > ledger balance -f drewr3.dat Bo + $ 20.00 Expenses:Books @end smallexample -The beginning and ending can be given at the same time, if it spans a -single period. In that case, just use @var{SPEC} by itself. In that -case, the period @samp{oct}, for example, will cover all the days in -october. The possible forms are: +The first example looks for any account starting with ``Bo'', of which +there are none. The second looks for any account with ``Bo'', which is +@samp{Expenses:Books}. +@cindex limit by payees +If you want to know exactly how much you have spent in a particular +account on a particular payee, the following are equivalent: @smallexample -<SPEC> -in <SPEC> +> ledger balance Auto:Fuel and @@Chevron +> ledger balance --limit "(account=~/Fuel/) & (payee=~/Chev/)" @end smallexample +@noindent will show you the amount expended on gasoline at Chevron. The second +example is the first example of the very power expression language +available to shape reports. The first example may be easier to +remember, but learning to use the second will open up far +morepossibilities. -Here are a few examples of period expressions: +@node Controlling formatting, , Controlling the Accounts and Payees, Balance Reports +@subsection Controlling Formatting +These examples all use the default formatting for the balance +report. Customizing the formatting can easily allowing to see only what +you want, or interface Ledger with other programs. -@smallexample -monthly -monthly in 2004 -weekly from oct -weekly from last month -from sep to oct -from 10/1 to 10/5 -monthly until 2005 -from apr -until nov -last oct -weekly last august -@end smallexample -@node Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top +@node Reporting Commands, Command-line Syntax, Building Reports, Top @chapter Reporting Commands @menu -* Primary Financial Reports:: +* Primary Financial Reports:: Reports in other formats:: Reports about * Reports in other formats:: * Reports about your Journals:: * Developer Commands:: @@ -4000,21 +3450,686 @@ nothing for a command line user. @table @code @item args @item eval -@item expr -@item format +evaluate the given value expression against the model transaction +@item expr "LIMIT EXPRESSION" +Print details of how ledger parses the given limit expression and apply it against a model transaction. +@item format "FORMATTING" +Print details of how ledger uses the given formatting description and apply it against a model transaction. @item generate -@item parse +@item parse <VALUE EXPR> +Print details of how ledger uses the given value expression description and apply it against a model transaction. @item period @item query @item template @end table +@node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top +@chapter Command-line Syntax + @menu -* Budgeting and Forecasting:: +* Basic Usage:: +* Detailed Options Description:: +* Period Expressions:: @end menu -@node Budgeting and Forecasting, Value Expressions, Reporting Commands, Top +@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax +@section Basic Usage + +This chapter describes Ledger's features and options. You may wish to +survey this to get an overview before diving in to the @ref{Ledger +Tutorial} and more detailed examples that follow. + +Ledger has a very simple command-line interface, named---enticingly +enough---@command{ledger}. It supports a few reporting commands, and +a large number of options for refining the output from those commands. +The basic syntax of any ledger command is: + +@smallexample +ledger [OPTIONS...] COMMAND [ARGS...] +@end smallexample + +After the command word there may appear any number of arguments. For +most commands, these arguments are regular expressions that cause the +output to relate only to postings matching those regular expressions. +For the @command{transaction} command, the arguments have a special +meaning, described below. + +The regular expressions arguments always match the account name that a +posting refers to. To match on the payee of the transaction instead, +precede the regular expression with @samp{payee} or @@. For example, the +following balance command reports account totals for rent, food and +movies, but only those whose payee matches Freddie: + +@smallexample +ledger bal rent food movies payee freddie +@end smallexample +@noindent or +@smallexample +ledger bal rent food movies @@freddie +@end smallexample + +There are many, many command options available with the +@command{ledger} command, and it takes a while to master them. +However, none of them are required to use the basic reporting +commands. + + + + + + + + + +@node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax +@section Detailed Option Description + +With all of the reports, command-line options are useful to modify the +output generated. The basic form for most commands is: + +@smallexample +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +@end smallexample + +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. + +@subsection Basic options + +These are the most basic command options. Most likely, the user will +want to set them using environment variables (see @ref{Environment Variables}), +instead of using actual command-line options: + +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. + +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. + +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. +Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. + +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. + +@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by +ledger before any other ledger file. This file may not contain any +postings, but it may contain option settings. To specify options +in the init file, use the same syntax as the command-line, but put each +option on it's own line. Here's an example init file: + +@smallexample +--price-db ~/finance/.pricedb + +; ~/.ledgerrc ends here +@end smallexample + +Option settings on the command-line or in the environment always take +precedence over settings in the init file. + + +@option{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file postings are assumed to relate to. + +@subsection Report filtering + +These options change which postings affect the outcome of a +report, in ways other than just using regular expressions: + +@option{--current}(@option{-c}) displays only transactions occurring on or +before the current date. + +@option{--begin DATE} (@option{-b DATE}) constrains the report to +transactions on or after @var{DATE}. Only transactions after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching transaction. (Note: This +is different from using @option{--display} to constrain what is +displayed). + +@option{--end DATE} (@option{-e DATE}) constrains the report so that +transactions on or after @var{DATE} are not considered. The ending date +is inclusive. + +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching transactions within each +period separately, making it easy to see weekly, monthly, quarterly, +etc., posting totals. A period string can even specify the +beginning and end of the report range, using simple terms like ``last +june'' or ``next month''. For more using period expressions, see +@ref{Period Expressions}. + +@option{--period-sort EXPR} sorts the postings within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: + +@smallexample +ledger -M --period-sort -At reg ^Expenses +@end smallexample + +@option{--cleared} (@option{-C}) displays only postings whose transaction +has been marked ``cleared'' (by placing an asterix to the right of the +date). + +@option{--uncleared} (@option{-U}) displays only postings whose +transaction has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). + +@option{--real} (@option{-R}) displays only real postings, not virtual. +(A virtual posting is indicated by surrounding the account name with +parentheses or brackets; see @ref{Virtual Transactions} for more +information). + +@option{--actual} (@option{-L}) displays only actual postings, and +not those created due to automated postings. + +@option{--related} (@option{-r}) displays postings that are +related to whichever postings would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by transactions having a related posting. +For example, if a file had this transaction: + +@smallexample +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 +@end smallexample + +And the register command was: + +@smallexample +ledger -r register food +@end smallexample + +The following would be output, showing the postings related to the +posting that matched: + +@smallexample +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 +@end smallexample + +@option{--budget} is useful for displaying how close your postings +meet your budget. @option{--add-budget} also shows unbudgeted +postings, while @option{--unbudgeted} shows only those. +@option{--forecast} is a related option that projects your budget into +the future, showing how it will affect future balances. +@xref{Budgeting and Forecasting}. + +@option{--limit EXPR} (@option{-l EXPR}) limits which postings +take part in the calculations of a report. + +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +used to calculate the ``value'' column in the @command{register} +report, the amount used to calculate account totals in the +@command{balance} report, and the values printed in the +@command{equity} report. @xref{Value Expressions}. + +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. + +@menu +* Search Terms:: +* Output Customization:: +* Commodity Reporting:: +* Environment Variables:: +@end menu + +@node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description +@subsection Search Terms + +Valid Ledger invocations look like: +@smallexample + ledger [OPTIONS] <COMMAND> <SEARCH-TERMS> +@end smallexample + +Where @samp{COMMAND} is any command verb (@pxref{Reporting Commands}), @samp{OPTIONS} can occur +anywhere, and @samp{SEARCH-TERM} is one or more of the following: + +@smallexample + word search for any account containing 'word' + TERM and TERM boolean AND between terms + TERM or TERM boolean OR between terms + not TERM invert the meaning of the term + payee word search for any payee containing 'word' + @@word shorthand for 'payee word' + desc word alternate for 'payee word' + note word search for any note containing 'word' + &word shorthand for 'note word' + tag word search for any metadata tag containing 'word' + tag word=value search for any metadata tag containing 'word' + whose value contains 'value' + %word shorthand for 'tag word' + %word=value shorthand for 'tag word=value' + meta word alternate for 'tag word' + meta word=value alternate for 'tag word=value' + expr 'EXPR' apply the given value expression as a predicate + '=EXPR' shorthand for 'expr EXPR' + \( TERMS \) group terms; useful if using and/or/not +@end smallexample + +So, to list all transaction that charged to ``food'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent: + +@smallexample + ledger reg food not dining @@chang + ledger reg food and not dining and not payee chang + ledger reg food not dining expr 'payee =~ /chang/' +@end smallexample + +@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description +@subsection Output Customization + +These options affect only the output, but not which postings are +used to create it: + +@option{--collapse} (@option{-n}) causes transactions in a +@command{register} report with multiple postings to be collapsed +into a single, subtotaled transaction. + +@option{--subtotal} (@option{-s}) causes all transactions in a +@command{register} report to be collapsed into a single, subtotaled +transaction. + +@option{--by-payee} (@option{-P}) reports subtotals by payee. + +@option{--comm-as-payee} (@option{-x}) changes the payee of every +posting to be the commodity used in that posting. This can be +useful when combined with other options, such as @option{-s}. + +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. + +@option{--weekly} (@option{-W}) reports posting totals by the +week. The week begins on whichever day of the week begins the month +containing that posting. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports posting totals by month; @option{--yearly} +(@option{-Y}) reports posting totals by year. For more complex +period, using the @option{--period} option described above. + +@option{--dow} reports postings totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. + +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +the values determined using the value expression @var{EXPR}. For +example, using @option{-S -UT} in the balance report will sort account +balances from greatest to least, using the absolute value of the +total. For more on how to use value expressions, see @ref{Value +Expressions}. + +@option{--pivot TAG} produces a pivot table around the tag provided. +This requires meta data using valued tags. + +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. + +@option{--head} causes only the first N transactions to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N postings. @option{--tail} outputs only +the last N transactions. Both options may be used simultaneously. If a +negative amount is given, it will invert the meaning of the flag +(instead of the first five transactions being printed, for example, it +would print all but the first five). + +@option{--pager} tells Ledger to pass its output to the given pager +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. + +@option{--average} (@option{-A}) reports the average posting +value. + +@option{--deviation} (@option{-D}) reports each posting's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. + +@option{--percent} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. + +@c @option{--totals} include running total information in the +@c @command{xml} report. + +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it outputs nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. + +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it outputs nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which postings +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking postings, against a running balance which +includes all posting values: + +@smallexample +ledger -d "d>=[last month]" reg checking +@end smallexample + +The output from this command is very different from the following, +whose running total includes only postings from the last month +onward: + +@smallexample +ledger -p "last month" reg checking +@end smallexample + +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). + +@option{--date-format STR} (@option{-y STR}) changes the basic date +format used by reports. The default uses a date like 2004/08/01, +which represents the default date format of @samp{%Y/%m/%d}. To +change the way dates are printed in general, the easiest way is to put +@option{--date-format FORMAT} in the Ledger initialization file +@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). + +@option{--format STR} (@option{-F STR}) sets the reporting format for +whatever report ledger is about to make. @xref{Format Strings}. +There are also specific format commands for each report type: + +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize + +@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description +@subsection Commodity Reporting + +These options affect how commodity values are displayed: + +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: + +@smallexample +; Don't download quotes for the dollar, or timelog values +N $ +N h +@end smallexample + +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. + +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. + +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: + +@table @code +@item -O, --quantity +Reports commodity totals (this is the default) + +@item -B, --basis +Reports the cost basis for all postings. + +@item -V, --market +Reports the last known market value for all commodities. + +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. +@end table + + +Often you will be more interested in the value of your entire holdings, +in your preferred currency. It might be nice to know you hold 10,000 +shares of PENNY, but you are more interested in whether or not that is +worth $1000.00 or $10,000.00. However, the current day value of a +commodity can mean different things to different people, depending on +the accounts involved, the commodities, the nature of the transactions, +etc. + +When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that +some or all of the commodities be valuated as of today (or whatever +@samp{--now} is set to). But what does such a valuation mean? This +meaning is governed by the presence of a @samp{VALUE} metadata property, +whose content is an expression used to compute that value. + +If no VALUE property is specified, each posting is assumed to have a +default, as if you'd specified a global, automated transaction as +follows: + +@smallexample + = expr true + ; VALUE:: market(amount, date, exchange) +@end smallexample +This definition emulates the present day behavior of @samp{-V} and @samp{-X} (in the +case of @samp{-X}, the requested commodity is passed via the string 'exchange' +above). + +@cindex Euro conversion +One thing many people have wanted to do is to fixate the valuation of +old European currencies in terms of the Euro after a certain date: + + +@smallexample + = expr commodity == "DM" + ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR +@end smallexample + +This says: If @samp{--now} is some old date, use market prices as they +were at that time; but if @samp{--now} is past June 2008, use a fixed +price for converting Deutsch Mark to Euro. + +Or how about never re-valuating commodities used in Expenses, since they +cannot have a different future value: + +@smallexample + = /^Expenses:/ + ; VALUE:: market(amount, post.date, exchange) +@end smallexample + +This says the future valuation is the same as the valuation at the time +of posting. post.date equals the posting's date, while just 'date' is +the value of @samp{--now} (defaults to today). + +Or how about valuating miles based on a reimbursement rate during a +specific time period: + + +@smallexample + = expr commodity == "miles" and date >= [2007] and date < [2008] + ; VALUE:: market($1.05, date, exchange) +@end smallexample + +In this case, miles driven in 2007 will always be valuated at $1.05 +each. If you use @samp{-X EUR} to expressly request all amounts in +Euro, Ledger shall convert $1.05 to Euro by whatever means are +appropriate for dollars. + +Note that you can have a valuation expression specific to a particular +posting or transaction, by overriding these general defaults using +specific metadata: + +@smallexample + 2010-12-26 Example + Expenses:Food $20 + ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what + ; the user asks for with -V or -X + ; VALUE:: 30 DM + Assets:Cash +@end smallexample + +This example demonstrates that your VALUE expression should be as +symbolic as possible, using terms like 'amount' and 'date', rather than +specific amounts and dates. Also, you should pass the amount along to +the function 'market' so it can be further revalued if the user has +asked for a specific currency. + +Or, if it better suits your accounting, you can be less symbolic, which +allows you to report most everything in EUR if you use -X EUR, except +for certain accounts or postings which should always be valuated in +another currency. For example: + +@smallexample + = /^Assets:Brokerage:CAD$/ + ; Always report the value of commodities in this account in + ; terms of present day dollars, despite what was asked for + ; on the command-line VALUE:: market(amount, date, '$') +@end smallexample + +@cindex FIFO/LIFO +@cindex LIFO/FIFO +Ledger presently has no way of handling such things as FIFO and LIFO. + +If you specify an unadorned commodity name, like AAPL, it will balance +against itself. If @samp{--lots} are not being displayed, then it will +appear to balance against any lot of AAPL. + +@cindex adorned commodity +If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +balance against itself, and against any AAPL if @samp{--lots} is not +specified. But if you do specify @samp{--lot-prices}, for example, then +it will balance against that specific price for AAPL. + + +@node Environment Variables, , Commodity Reporting, Detailed Options Description +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. + +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: + +@smallexample +--pager /bin/cat + +@end smallexample + +@node Period Expressions, , Detailed Options Description, Command-line Syntax +@section Period Expressions + +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: + +@smallexample +[INTERVAL] [BEGIN] [END] +@end smallexample + +The optional @var{INTERVAL} part may be any one of: + +@smallexample +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly +@end smallexample + +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: + +@smallexample +from <SPEC> +since <SPEC> +@end smallexample + +The end time can be either of: + +@smallexample +to <SPEC> +until <SPEC> +@end smallexample + +Where @var{SPEC} can be any of: + +@smallexample +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week +@end smallexample + +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: + +@smallexample +<SPEC> +in <SPEC> +@end smallexample + +Here are a few examples of period expressions: + +@smallexample +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +last oct +weekly last august +@end smallexample + + +@node Budgeting and Forecasting, Value Expressions, Command-line Syntax, Top @chapter Budgeting and Forecasting @menu |