diff options
Diffstat (limited to 'docs/ledger.info')
| -rw-r--r-- | docs/ledger.info | 3640 |
1 files changed, 0 insertions, 3640 deletions
diff --git a/docs/ledger.info b/docs/ledger.info deleted file mode 100644 index 651f5d91..00000000 --- a/docs/ledger.info +++ /dev/null @@ -1,3640 +0,0 @@ -This is /Users/johnw/src/ledger/docs/ledger.info, produced by makeinfo -version 4.7 from /Users/johnw/src/ledger/docs/ledger.texi. - -INFO-DIR-SECTION User Applications - Copyright (c) 2003-2006, John Wiegley. All rights reserved. - - Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - - Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the -documentation and/or other materials provided with the distribution. - - - Neither the name of New Artisans LLC nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A -PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -START-INFO-DIR-ENTRY -* Ledger: (ledger). Command Line Accounting -END-INFO-DIR-ENTRY - - -File: ledger.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) - -Overview -******** - -Copyright (c) 2003-2006, John Wiegley. All rights reserved. - - Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - - Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in the -documentation and/or other materials provided with the distribution. - - - Neither the name of New Artisans LLC nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A -PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -* Menu: - -* Introduction:: -* Running Ledger:: -* Keeping a ledger:: -* Using XML:: - - -File: ledger.info, Node: Introduction, Next: Running Ledger, Prev: Top, Up: Top - -1 Introduction -************** - -Ledger is an accounting tool with the moxie to exist. It provides no -bells or whistles, and returns the user to the days before user -interfaces were even a twinkling in their father's CRT. - - What it does offer is a double-entry accounting ledger with all the -flexibility and muscle of its modern day cousins, without any of the -fat. Think of it as the Bran Muffin of accounting tools. - - To use it, you need to start keeping a ledger. This is the basis of -all accounting, and if you haven't started yet, now is the time to -learn. The little booklet that comes with your checkbook is a ledger, -so we'll describe double-entry accounting in terms of that. - - A checkbook ledger records debits (subtractions, or withdrawals) and -credits (additions, or deposits) with reference to a single account: -the checking account. Where the money comes from, and where it goes -to, are described in the payee field, where you write the person or -company's name. The ultimate aim of keeping a checkbook ledger is to -know how much money is available to spend. That's really the aim of -all ledgers. - - What computers add is the ability to walk through these transactions, -and tell you things about your spending habits; to let you devise -budgets and get control over your spending; to squirrel away money into -virtual savings account without having to physically move money around; -etc. As you keep your ledger, you are recording information about your -life and habits, and sometimes that information can start telling you -things you aren't aware of. Such is the aim of all good accounting -tools. - - The next step up from a checkbook ledger, is a ledger that keeps -track of all your accounts, not just checking. In such a ledger, you -record not only who gets paid--in the case of a debit--but where the -money came from. In a checkbook ledger, its assumed that all the money -comes from your checking account. But in a general ledger, you write -transaction two-lines: the source account and target account. _There -must always be a debit from at least one account for every credit made -to another account_. This is what is meant by "double-entry" -accounting: the ledger must always balance to zero, with an equal -number of debits and credits. - - For example, let's say you have a checking account and a brokerage -account, and you can write checks from both of them. Rather than keep -two checkbooks, you decide to use one ledger for both. In this general -ledger you need to record a payment to Pacific Bell for your monthly -phone bill. The cost is $23.00, let's say, and you want to pay it from -your checking account. In the general ledger you need to say where the -money came from, in addition to where it's going to. The entry might -look like this: - - 9/29 BAL Pacific Bell $-200.00 $-200.00 - Equity:Opening Balances $200.00 - 9/29 BAL Checking $100.00 $100.00 - Equity:Opening Balances $-100.00 - 9/29 100 Pacific Bell $23.00 $223.00 - Checking $-23.00 $77.00 - - The first line shows a payment to Pacific Bell for $23.00. Because -there is no "balance" in a general ledger--it's always zero--we write -in the total balance of all payments to "Pacific Bell", which now is -$223.00 (previously the balance was $200.00). This is done by looking -at the last entry for "Pacific Bell" in the ledger, adding $23.00 to -that amount, and writing the total in the balance column. And the -money came from "Checking"--a withdrawal of $23.00--which leaves the -ending balance in "Checking" at $77.00. This is a very manual -procedure; but that's where computers come in... - - The transaction must balance to $0: $23 went to Pacific Bell, $23 -came from Checking. There is nothing left over to be accounted for, -since the money has simply moved from one account to another. This is -the basis of double-entry accounting: that money never pops in or out of -existence; it is always a transaction from one account to another. - - Keeping a general ledger is the same as keeping two separate ledgers: -One for Pacific Bell and one for Checking. In that case, each time a -payment is written into one, you write a corresponding withdrawal into -the other. This makes it easier to write in a "running balance", since -you don't have to look back at the last time the account was -referenced--but it also means having a lot of ledger books, if you deal -with multiple accounts. - - Enter the beauty of computerized accounting. The purpose of the -Ledger program is to make general ledger accounting simple, by keeping -track of the balances for you. Your only job is to enter the -transactions. If a transaction does not balance, Ledger displays an -error and indicates the incorrect transaction.(1) - - In summary, there are two aspects of Ledger use: updating the ledger -data file, and using the Ledger tool to view the summarized result of -your entries. - - And just for the sake of example--as a starting point for those who -want to dive in head-first--here are the ledger entries from above, -formatting as the ledger program wishes to see them: - - 2004/09/29 Pacific Bell - Payable:Pacific Bell $-200.00 - Equity:Opening Balances - - 2004/09/29 Checking - Accounts:Checking $100.00 - Equity:Opening Balances - - 2004/09/29 Pacific Bell - Payable:Pacific Bell $23.00 - Accounts:Checking - - The account balances and registers in this file, if saved as -`ledger.dat', could be reported using: - - $ ledger -f ledger.dat balance - $ ledger -f ledger.dat register checking - $ ledger -f ledger.dat register bell - -* Menu: - -* Building the program:: -* Getting help:: - - ---------- Footnotes ---------- - - (1) In some special cases, it automatically balances this entry for -you. - - -File: ledger.info, Node: Building the program, Next: Getting help, Prev: Introduction, Up: Introduction - -1.1 Building the program -======================== - -Ledger is written in ANSI C++, and should compile on any platform. It -depends on the GNU multiprecision integer library (libgmp), and the -Perl regular expression library (libpcre). It was developed using GNU -make and gcc 3.3, on a PowerBook running OS/X. - - To build and install once you have these libraries on your system, -enter these commands: - - ./configure && make install - - -File: ledger.info, Node: Getting help, Prev: Building the program, Up: Introduction - -1.2 Getting help -================ - -If you need help on how to use Ledger, or run into problems, you can -just the Ledger mailing list at the following Web address: - - https://lists.sourceforge.net/lists/listinfo/ledger-discuss - - You can also find help at the `#ledger' channel on the IRC server -`irc.freenode.net'. - - -File: ledger.info, Node: Running Ledger, Next: Keeping a ledger, Prev: Introduction, Up: Top - -2 Running Ledger -**************** - -Ledger has a very simple command-line interface, named--enticing -enough--`ledger'. It supports a few reporting commands, and a large -number of options for refining the output from those commands. The -basic syntax of any ledger command is: - - ledger [OPTIONS...] COMMAND [ARGS...] - - Command options must always precede the command word. After the -command word there may appear any number of arguments. For most -commands, these arguments are regular expressions that cause the output -to relate only to transactions matching those regular expressions. For -the `entry' command, the arguments have a special meaning, described -below. - - The regular expressions arguments always match the account name that -a transaction refers to. To match on the payee of the entry instead, -precede the regular expression with `--'. For example, the following -balance command reports account totals for rent, food and movies, but -only those whose payee matches Freddie: - - ledger bal rent food movies -- freddie - - There are many, many command options available with the `ledger' -command, and it takes a while to master them. However, none of them -are required to use the basic reporting commands. - -* Menu: - -* Usage overview:: -* Commands:: -* Options:: -* Format strings:: -* Value expressions:: -* Period expressions:: -* File format:: -* Some typical queries:: -* Budgeting and forecasting:: - - -File: ledger.info, Node: Usage overview, Next: Commands, Prev: Running Ledger, Up: Running Ledger - -2.1 Usage overview -================== - -Before getting into the details of how to run Ledger, it will be easier -to introduce the features in the context of their typical usage. To -that end, this section presents a series of recipes, gradually -introducing all of the command-line features of Ledger. - - For the purpose of these examples, assume the environment variable -LEDGER is set to the file `sample.dat' (which is included in the -distribution), and that the contents of that file are: - - = /^Expenses:Books/ - (Liabilities:Taxes) -0.10 - - ~ Monthly - Assets:Bank:Checking $500.00 - Income:Salary - - 2004/05/01 * Checking balance - Assets:Bank:Checking $1,000.00 - Equity:Opening Balances - - 2004/05/01 * Investment balance - Assets:Brokerage 50 AAPL $30.00 - Equity:Opening Balances - - 2004/05/14 * Pay day - Assets:Bank:Checking $500.00 - Income:Salary - - 2004/05/27 Book Store - Expenses:Books $20.00 - Liabilities:MasterCard - - 2004/05/27 (100) Credit card company - Liabilities:MasterCard $20.00 - Assets:Bank:Checking - - This sample file demonstrates a basic principle of accounting which -it is recommended you follow: Keep all of your accounts under five -parent Assets, Liabilities, Income, Expenses and Equity. It is -important to do so in order to make sense out of the following examples. - -2.1.1 Checking balances ------------------------ - -Ledger has seven basic commands, but by far the most often used are -`balance' and `register'. To see a summary balance of all accounts, -use: - - ledger bal - - `bal' is a short-hand for `balance'. This command prints out the -summary totals of the five parent accounts used in `sample.dat': - - $1,480.00 - 50 AAPL Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - $-2.00 Liabilities - -------------------- - $-1,502.00 - 50 AAPL - - None of the child accounts are shown, just the parent account totals. -We can see that in `Assets' there is $1,480.00, and 50 shares of Apple -stock. There is also a negative grand total. Usually the grand total -is zero, which means that all accounts balance(1). In this case, since -the 50 shares of Apple stock cost $1,500.00 dollars, then these two -amounts balance each other in the grand total. The extra $2.00 comes -from a virtual transaction being added by the automatic entry at the -top of the file. The entry is virtual because the account name was -surrounded by parentheses in an automatic entry. Automatic entries -will be discussed later, but first let's remove the virtual transaction -from the balance report by using the `--real' option: - - ledger --real bal - - Now the report is: - - $1,480.00 - 50 AAPL Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - -------------------- - $-1,500.00 - 50 AAPL - - Since the liability was a virtual transaction, it has dropped from -the report and we see that final total is balanced. - - But we only know that it balances because `sample.dat' is quite -simple, and we happen to know that the 50 shares of Apple stock cost -$1,500.00. We can verify that things really balance by reporting the -Apple shares in terms of their cost, instead of their quantity. To do -this requires the `--basis', or `-B', option: - - ledger --real -B bal - - This command reports: - - $2,980.00 Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - - With the basis cost option, the grand total has disappeared, as it is -now zero. The confirms that the cost of everything balances to zero, -_which must always be true_. Reporting the real basis cost should -never yield a remainder(2). - -2.1.1.1 Sub-account balances -............................ - -The totals reported by the balance command are only the topmost parent -accounts. To see the totals of all child accounts as well, use the -`-s' option: - - ledger --real -B -s bal - - This reports: - - $2,980.00 Assets - $1,480.00 Bank:Checking - $1,500.00 Brokerage - $-2,500.00 Equity:Opening Balances - $20.00 Expenses:Books - $-500.00 Income:Salary - - This shows that the `Assets' total is made up from two child -account, but that the total for each of the other accounts comes from -one child account. - - Sometimes you may have a lot of children, nested very deeply, but -only want to report the first two levels. This can be done with a -display predicate, using a value expression. In the value expression, -`T' represents the reported total, and `l' is the display level for the -account: - - ledger --real -B -d "T&l<=2" bal - - This reports: - - $2,980.00 Assets - $1,480.00 Bank - $1,500.00 Brokerage - $-2,500.00 Equity:Opening Balances - $20.00 Expenses:Books - $-500.00 Income:Salary - - Instead of reporting `Bank:Checking' as a child of `Assets', it -report only `Bank', since that account is a nesting level of 2, while -`Checking' is at level 3. - - To review the display predicate used--`T&l<=2'--this rather terse -expression means: Display an account only if it has a non-zero total -(`T'), and its nesting level is less than or equal to 2 (`l<=2'). - -2.1.1.2 Specific account balances -................................. - -While reporting the totals for all accounts can be useful, most often -you will want to check the balance of a specific account or accounts. -To do this, put one or more account names after the balance command. -Since these names are really regular expressions, you can use partial -names if you wish: - - ledger bal checking - - Reports: - - $1,480.00 Assets:Bank:Checking - - Any number of names may be used: - - ledger bal checking broker liab - - Reports: - - $1,480.00 Assets:Bank:Checking - 50 AAPL Assets:Brokerage - $-2.00 Liabilities - - In this case no grand total is reported, because you are asking for -specific account balances. - - For those comfortable with regular expressions, any Perl regexp is -allowed: - - ledger bal ^assets.*checking ^liab - - Reports: - - $1,480.00 Assets:Bank:Checking - $-2.00 Liabilities:Taxes - -2.1.2 The register report -------------------------- - -While the `balance' command can be very handy for checking account -totals, by far the most powerful of Ledger's reporting tools is the -`register' command. In fact, internally both commands use the same -logic, but report the results differently: `balance' shows the summary -totals, while `register' reports each transaction and how it -contributes to that total. - - Paradoxically, the most basic form of `register' is almost never -used, since it displays every transaction: - - ledger reg - - `reg' is a short-hand for `register'. This command reports: - - 2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 - Equity:Opening Balan.. $-1,000.00 0 - 2004/05/01 Investment balance Assets:Brokerage 50 AAPL 50 AAPL - Equity:Opening Balan.. $-1,500.00 $-1,500.00 - 50 AAPL - 2004/05/14 Pay day Assets:Bank:Checking $500.00 $-1,000.00 - 50 AAPL - Income:Salary $-500.00 $-1,500.00 - 50 AAPL - 2004/05/27 Book Store Expenses:Books $20.00 $-1,480.00 - 50 AAPL - Liabilities:MasterCard $-20.00 $-1,500.00 - 50 AAPL - (Liabilities:Taxes) $-2.00 $-1,502.00 - 50 AAPL - 2004/05/27 Credit card company Liabilities:MasterCard $20.00 $-1,482.00 - 50 AAPL - Assets:Bank:Checking $-20.00 $-1,502.00 - 50 AAPL - - This rather verbose output shows every account transaction in -`sample.dat', and how it affects the running total. The final total is -identical to what we saw with the plain `balance' command. To see how -things really balance, we can use `--real -B', just as we did with -`balance': - - ledger --real -B reg - - Reports: - - 2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 - Equity:Opening Balan.. $-1,000.00 0 - 2004/05/01 Investment balance Assets:Brokerage $1,500.00 $1,500.00 - Equity:Opening Balan.. $-1,500.00 0 - 2004/05/14 Pay day Assets:Bank:Checking $500.00 $500.00 - Income:Salary $-500.00 0 - 2004/05/27 Book Store Expenses:Books $20.00 $20.00 - Liabilities:MasterCard $-20.00 0 - 2004/05/27 Credit card company Liabilities:MasterCard $20.00 $20.00 - Assets:Bank:Checking $-20.00 0 - - Here we see that everything balances to zero in the end, as it must. - -2.1.2.1 Specific register queries -................................. - -The most common use of the register command is to summarize -transactions based on the account(s) they affect. Using `sample.dat' -as as example, we could look at all book purchases using: - - ledger reg books - - Reports: - - 2004/05/29 Book Store Expenses:Books $20.00 $20.00 - - If a double-dash (`--') occurs in the list of regular expressions, -any following arguments are matched against payee names, instead of -account names: - - ledger reg ^liab -- credit - - Reports: - - 2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00 - - There are many reporting options for tailoring which transactions are -found, and also how to summarize the various amounts and totals that -result. These are plumbed in greater depth below. - -2.1.3 Selecting transactions ----------------------------- - -Although the easiest way to use the register is to report all the -transactions affecting a set of accounts, it can often result in more -information than you want. To cope with an ever-growing amount of -data, there are several options which can help you pinpoint your report -to exactly the transactions that interest you most. This is called the -"calculation" phase of Ledger. All of its related options are -documented under `--help-calc'. - -2.1.3.1 By date -............... - -`--current'(`-c') displays entries occurring on or before the current -date. Any entry recorded for a future date will be ignored, as if it -had not been seen. This is useful if you happen to pre-record entries, -but still wish to view your balances in terms of what is available -today. - - `--begin DATE' (`-b DATE') limits the report to only those entries -occurring on or after DATE. The running total in the register will -start at zero with the first transaction, even if there are earlier -entries. - - To limit the display only, but still add earlier transactions to the -running total, use the display expression `-d 'd>=[DATE]''): - - ledger --basis -b may -d 'd>=[5/14]' reg ^assets - - Reports: - - 2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 - 2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 - - In this example, the displayed transactions start from `5/14', but -the calculated total starts from the beginning of `may'. - - `--end DATE' (`-e DATE') states when reporting should end, both -calculation and display. The ending date is inclusive. - - The DATE argument to the `-b' and `-e' options can be rather -flexible. Assuming the current date to be November 15, 2004, then all -of the following are equivalent: - - ledger -b oct bal - ledger -b "this oct" bal - ledger -b 2004/10 bal - ledger -b 10 bal - ledger -b last bal - ledger -b "last month" bal - - To constrain the report to a specific time period, use `--period' -(`-p'). A time period may have both a beginning and an end, or -neither, as well as a specified interval. Here are a few examples: - - ledger -p 2004 bal - ledger -p august bal - ledger -p "from aug to oct" bal - ledger -p "daily from 8/1 to 8/15" bal - ledger -p "weekly since august" bal - ledger -p "monthly from feb to oct" bal - ledger -p "quarterly in 2004" bal - ledger -p yearly bal - - See *Note Period expressions:: for more on syntax. Also, all of the -options `-b', `-e' and `-p' may be used together, but whatever -information occurs last takes priority. An example of such usage (in a -script, perhaps) would be: - - ledger -b 2004 -e 2005 -p monthly reg ^expenses - - This command is identical to: - - ledger -p "monthly in 2004" reg ^expenses - - The transactions within a period may be sorted using -`--period-sort', which takes a value expression. This is similar to -the `--sort' option, except that it sorts within each period entry, -rather than sorting all transactions in the report. See the -documentation on `--sort' below for more details. - -2.1.3.2 By status -................. - -By default, all regular transactions are included in each report. To -limit the report to certain kinds of transactions, use one or more of -the following options: - -`-C, --cleared' - Consider only cleared transactions. - -`-U, --uncleared' - Consider only uncleared and pending transactions. - -`-R, --real' - Consider only real (non-virtual) transactions. - -`-L, --actual' - Consider only actual (non-automated) transactions. - - Cleared transactions are indicated by an asterix placed just before -the payee name in a transaction. The meaning of this flag is up to the -user, but typically it means that an entry has been seen on a financial -statement. Pending transactions use an exclamation mark in the same -position, but are mainly used only by reconciling software. Uncleared -transactions are for things like uncashed checks, credit charges that -haven't appeared on a statement yet, etc. - - Real transactions are all non-virtual transactions, where the account -name is not surrounded by parentheses or square brackets. Virtual -transactions are useful for showing a transfer of money that never -really happened, like money set aside for savings without actually -transferring it from the parent account. - - Actual transactions are those not generated, either as part of an -automated entry, or a budget or forecast report. A useful of when you -might like to filter out generated transactions is with a budget: - - ledger --budget --actual reg ^expenses - - This command outputs all transactions affecting a budgeted account, -but without subtracting the budget amount (because the generated -transactions are suppressed with `--actual'). The report shows how -much you actually spent on budgeted items. - -2.1.3.3 By relationship -....................... - -Normally, a register report includes only the transactions that match -the regular expressions specified after the command word. For example, -to report all expenses: - - ledger reg ^expenses - - This reports: - - 2004/05/29 Book Store Expenses:Books $20.00 $20.00 - - Using `--related' (`-r') reports the transactions that did not match -your query, but only in entries that otherwise would have matched. -This has the effect of indicating where money came from, or when to: - - ledger -r reg ^expenses - - Reports: - - 2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00 - -2.1.3.4 By budget -................. - -There is more information about budgeting and forecasting in *Note -Budgeting and forecasting::. Basically, if you have any period entries -in your ledger file, you can use these options. A period entry looks -like: - - ~ Monthly - Assets:Bank:Checking $500.00 - Income:Salary - - The difference from a regular entry is that the first line begins -with a tilde (~), and instead of a payee there's a period expression -(*Note Period expressions::). Otherwise, a period entry is in every -other way the same as a regular entry. - - With such an entry in your ledger file, the `--budget' option will -report only transactions that match a budgeted account. Using -`sample.dat' from above: - - ledger --budget reg ^income - - Reports: - - 2004/05/01 Budget entry Income:Salary $500.00 $500.00 - 2004/05/14 Pay day Income:Salary $-500.00 0 - - The final total is zero, indicating that the budget matched exactly -for the reported period. Budgeting is most often helpful with period -reporting; for example, to show monthly budget results use `--budget -p -monthly'. - - The `--add-budget' option reports all matching transactions in -addition to budget transactions; while `--unbudgeted' shows only those -that don't match a budgeted account. To summarize: - -`--budget' - Show transactions matching budgeted accounts. - -`--unbudgeted' - Show transactions matching unbudgeted accounts. - -`--add-budget' - Show both budgeted and unbudgeted transactions together (i.e., add - the generated budget transactions to the regular report). - - A report with the `--forecast' option will add budgeted transactions -while the specified value expression is true. For example: - - ledger --forecast 'd<[2005] reg ^income - - Reports: - - 2004/05/14 Pay day Income:Salary $-500.00 $-500.00 - 2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00 - 2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00 - - The date this report was made was November 5, 2004; the reason the -first forecast entry is in december is that forecast entries are only -added for the future, and they only stop after the value expression has -matched at least once, which is why the January entry appears. A -forecast report can be very useful for determining when money will run -out in an account, or for projecting future cash flow: - - ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp - - This reports balances projected income against projected expenses, -showing the resulting total in yearly intervals until 2008. For the -case of `sample.dat', which has no budgeted expenses, the result of the -above command (in November 2004) is: - - 2004/01/01 - 2004/12/31 Income:Salary $-1,000.00 $-1,000.00 - Expenses:Books $20.00 $-980.00 - 2005/01/01 - 2005/12/31 Income:Salary $-6,000.00 $-6,980.00 - 2006/01/01 - 2006/12/31 Income:Salary $-6,000.00 $-12,980.00 - 2007/01/01 - 2007/12/31 Income:Salary $-6,000.00 $-18,980.00 - 2008/01/01 - 2008/01/01 Income:Salary $-500.00 $-19,480.00 - -2.1.3.5 By value expression -........................... - -Value expressions can be quite complex, and are treated more fully in -*Note Value expressions::. They can be used for limiting a report with -`--limit' (`-l'). The following command report income since august, -but expenses since october: - - ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg - - The basic form of this value expression is `(A&B)|(A&B)'. The `A' -in each part matches against an account name with `/name/', while each -`B' part compares the date of the transaction (`d') with a specified -month. The resulting report will contain only transactions which match -the value expression. - - Another use of value expressions is to calculate the amount reported -for each line of a register report, or for computing the subtotal of -each account shown in a balance report. This example divides each -transaction amount by two: - - ledger -t 'a/2' reg ^exp - - The `-t' option doesn't affect the running total, only how the -transaction amount is displayed. To change the running total, use -`-T'. In that case, you will likely want to use the total (`O') -instead of the amount (`a'): - - ledger -T 'O/2' reg ^exp - -2.1.4 Massaging register output -------------------------------- - -Even after filtering down your data to just the transactions you're -interested in, the default reporting method of one transaction per line -is often still too much. To combat this complexity, it is possible to -ask Ledger to report the details to you in many different forms, -summarized in various ways. This is the "display" phase of Ledger, and -is documented under `--help-disp'. - -2.1.4.1 Summarizing -................... - -When multiple transactions relate to a single entry, they are reported -as part of that entry. For example, in the case of `sample.dat': - - ledger reg -- book - - Reports: - - 2004/05/29 Book Store Expenses:Books $20.00 $20.00 - Liabilities:MasterCard $-20.00 0 - (Liabilities:Taxes) $-2.00 $-2.00 - - All three transactions are part of one entry, and as such the entry -details are printed only once. To report every entry on a single line, -use `-n' to collapse entries with multiple transactions: - - ledger -n reg -- book - - Reports: - - 2004/05/29 Book Store <Total> $-2.00 $-2.00 - - In the balance report, `-n' causes the grand total not to be -displayed at the bottom of the report. - - If an account occurs more than once in a report, it is possible to -combine them all and report the total per-account, using `-s'. For -example, this command: - - ledger -B reg ^assets - - Reports: - - 2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 - 2004/05/01 Investment balance Assets:Brokerage $1,500.00 $2,500.00 - 2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 - 2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 - - But if the `-s' option is added, the result becomes: - - 2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00 - Assets:Brokerage $1,500.00 $2,980.00 - - When account subtotaling is used, only one entry is printed, and the -date and name reflect the range of the combined transactions. - - With `-P', transactions relating to the same payee are combined. In -this case, the date of the combined entry is that of the latest -transaction. - - `-x' changes the payee name for each transaction to be the same as -the commodity it uses. This can be especially useful combined with -other options, like `-P'. For example: - - ledger -Px reg ^assets - - Reports: - - 2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 - 2004/05/01 AAPL Assets:Brokerage 50 AAPL $1,480.00 - 50 AAPL - - This reports shows the subtotal for each commodity held, and where it -is located. To see the basis cost, or initial investment, add `-B'. -Applied to the example above: - - 2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 - 2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00 - - The only other options which affect summarized totals is `-E', which -works only in the balance report. In this case, it shows matching -accounts with a zero a balance, which are ordinarily excluded. This -can be useful to see all the accounts involved in a report, even if -some have no total. - -2.1.4.2 Quick periods -..................... - -Although the `-p' option (also `--period') is much more versatile, -there are other options to make the most common period reports easier: - -`-W, --weekly' - Show weekly sub-totals. Same as `-p weekly'. - -`-M, --monthly' - Show monthly sub-totals. Same as `-p monthly'. - -`-Y, --yearly' - Show yearly sub-totals. Same as `-p yearly'. - - There is one kind of period report cannot be done with `-p'. This -is the `--dow', or "days of the week" report, which shows summarized -totals for each day of the week. The following examples shows a "day -of the week" report of income and expenses: - - ledger --dow reg ^inc ^exp - - Reports: - - 2004/05/27 Thursdays Expenses:Books $20.00 $20.00 - 2004/05/14 Fridays Income:Salary $-500.00 $-480.00 - -2.1.4.3 Ordering and width -.......................... - -The transactions displayed in a report are shown in the same order as -they appear in the ledger file. To change the order and sort a report, -use the `--sort' option. `--sort' takes a value expression to -determine the value to sort against, making it possible to sort -according to complex criteria. Here are some simple and useful -examples: - - ledger --sort d reg ^exp # sort by date - ledger --sort t reg ^exp # sort by amount total - ledger --sort -t reg ^exp # reverse sort by amount total - ledger --sort Ut reg ^exp # sort by abs amount total - - For the balance report, you will want to use `T' instead of `t': - - ledger --sort T reg ^exp # sort by amount total - ledger --sort -T reg ^exp # reverse sort by amount total - ledger --sort UT reg ^exp # sort by abs amount total - - The `--sort' options sorts all transactions in a report. If periods -are used (such as `--monthly'), this can get somewhat confusing. In -that case, you'll probably want to sort within periods using -`--period-sort' instead of `--sort'. - - And if the register seems too cramped, and you have a lot of screen -real estate, you can use `-w' to format the report within 132 acolumns, -instead of 80. You are more likely then to see full payee and account -names, as well as properly formatted totals when long-named commodities -are used. - - If you want only the first or last N entries to be printed--which can -be very useful for viewing the last 10 entries in your checking -account, while also showing the cumulative balance from all -entries--use the `--head' and/or `--tail' options. The two options may -be used simultaneously, for example: - - ledger --tail 20 reg checking - - If the output from your command is very long, Ledger can output the -data to a pager utility, such as `more' or `less': - - ledger --pager /usr/bin/less reg checking - -2.1.4.4 Averages and percentages -................................ - -To see the running total changed to a running average, use `-A'. The -final transaction's total will be the overall average of all displayed -transactions. The works in conjunction with period reporting, so that -you can see your monthly average expenses with: - - ledger -AM reg ^expenses:food - ledger -AMn reg ^expenses - - This works in the balance report too: - - ledger -AM bal ^expenses:food - ledger -AMs bal ^expenses - - The `-D' option changes the running average into a deviation from -the running average. This only makes sense in the register report, -however. - - ledger -DM reg ^expenses:food - - In the balance report only, `-%' changes the reported totals into a -percentage of the parent account. This kind of report is confusing if -negative amounts are involved, and doesn't work at all if multiple -commodities occur in an account's history. It has a somewhat limited -usefulness, therefore, but in certain cases it can be handy, such as -reviewing overall expenses: - - ledger -%s -S T bal ^expenses - -2.1.4.5 Reporting total data -............................ - -Normally in the `xml' report, only transaction amounts are printed. To -include the running total under a `<total>' tag, use `--totals'. This -does not affect any other report. - - In the register report only, the output can be changed with `-j' to -show only the date and the amount--without commodities. This only -makes sense if a single commodity appears in the report, but can be -quite useful for scripting, or passing the data to Gnuplot. To show -only the date and running total, use `-J'. - -2.1.4.6 Display by value expression -................................... - -With `-d' you can decide which transactions (or accounts in the balance -report) are displayed, according to a value expression. The computed -total is not affected, only the display. This can be very useful for -shortening a report without changing the running total: - - ledger -d 'd>=[last month]' reg checking - - This command shows the checking account's register, beginning from -last month, but with the running total reflecting the entire history of -the account. - -2.1.4.7 Change report format -............................ - -When dates are printed in any report, the default format is `%Y/%m/%d', -which yields dates of the form `YYYY/mm/dd'. This can be changed with -`-y', whose argument is a `strftime' string--see your system's C -library documentation for the allowable codes. Mostly you will want to -use `%Y', `%m' and `%d', in whatever combination is convenient for your -locale. - - To change the format of the entire reported line, use `-F'. It -supports quite a large number of options, which are all documented in -*Note Format strings::. In addition, each specific kind of report -(except for `xml') can be changed using one of the following options: - -`--balance-format' - `balance' report. Default: - %20T %2_%-a\n - -`--register-format' - `register' report. Default: - %D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n - -`--print-format' - `print' report. Default: - %D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n - -`--plot-amount-format' - `register' report when `-j' (plot amount) is used. Default: - %D %(St)\n - -`--plot-total-format' - `register' report when `-J' (plot total) is used. Default: - %D %(ST)\n - -`--equity-format' - `equity' report. Default: - \n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n - -`--prices-format' - `prices' report. Default: - \n%D %Y%C%P\n%/ %-34W %12t\n - -`--wide-register-format' - `register' report when `-w' (wide) is used. Default: - %D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n - -2.1.5 Standard queries ----------------------- - -If your ledger file uses the standard top-level accounts: Assets, -Liabilities, Income, Expenses, Equity: then the following queries will -enable you to generate some typical accounting reports from your data. - - Your _net worth_ can be determined by balancing assets against -liabilities: - - ledger bal ^assets ^liab - - By removing long-term investment and loan accounts, you can see your -current net liquidity (or liquid net worth): - - ledger bal ^assets ^liab -retirement -brokerage -loan - - Balancing expenses against income yields your _cash flow_, or net -profit/loss: - - ledger bal ^exp ^inc - - In this case, if the number is positive it means you spent more than -you earned during the report period. - - The most often used command is the "balance" command: - - export LEDGER=/home/johnw/doc/ledger.dat - ledger balance - - Here I've set my Ledger environment variable to point to where my -ledger file is hiding. Thereafter, I needn't specify it again. - -2.1.6 Reporting balance totals ------------------------------- - -The balance command prints out the summarized balances of all my -top-level accounts, excluding sub-accounts. In order to see the -balances for a specific account, just specify a regular expression -after the balance command: - - ledger balance expenses:food - - This will show all the money that's been spent on food, since the -beginning of the ledger. For food spending just this month -(September), use: - - ledger -p sep balance expenses:food - - Or maybe you want to see all of your assets, in which case the -s -(show sub-accounts) option comes in handy: - - ledger -s balance ^assets - - To exclude a particular account, use a regular expression with a -leading minus sign. The following will show all expenses, but without -food spending: - - ledger balance expenses -food - -2.1.7 Reporting percentages ---------------------------- - -There is no built-in way to report transaction amounts or account -balances in terms of percentages - - ---------- Footnotes ---------- - - (1) It is impossible for accounts not to balance in ledger; it -reports an error if a transaction does not balance - - (2) If it ever does, then generated transactions are involved, which -can be removed using `--actual' - - -File: ledger.info, Node: Commands, Next: Options, Prev: Usage overview, Up: Running Ledger - -2.2 Commands -============ - -2.2.1 balance -------------- - -The `balance' command reports the current balance of all accounts. It -accepts a list of optional regexps, which confine the balance report to -the matching accounts. If an account contains multiple types of -commodities, each commodity's total is reported separately. - -2.2.2 register --------------- - -The `register' command displays all the transactions occurring in a -single account, line by line. The account regexp must be specified as -the only argument to this command. If any regexps occur after the -required account name, the register will contain only those -transactions that match. Very useful for hunting down a particular -transaction. - - The output from `register' is very close to what a typical -checkbook, or single-account ledger, would look like. It also shows a -running balance. The final running balance of any register should -always be the same as the current balance of that account. - - If you have Gnuplot installed, you may plot the amount or running -total of any register by using the script `report', which is included -in the Ledger distribution. The only requirement is that you add -either `-j' or `-J' to your register command, in order to plot either -the amount or total column, respectively. - -2.2.3 print ------------ - -The `print' command prints out ledger entries in a textual format that -can be parsed by Ledger. They will be properly formatted, and output -in the most economic form possible. The "print" command also takes a -list of optional regexps, which will cause only those transactions -which match in some way to be printed. - - The `print' command can be a handy way to clean up a ledger file -whose formatting has gotten out of hand. - -2.2.4 output ------------- - -The `output' command is very similar to the `print' command, except -that it attempts to replicate the specified ledger file exactly. The -format of the command is: - - ledger -f FILENAME output FILENAME - - Where `FILENAME' is the name of the ledger file to output. The -reason for specifying this command is that only entries contained -within that file will be output, and not an included entries (as can -happen with the `print' command). - -2.2.5 xml ---------- - -The `xml' command outputs results similar to what `print' and -`register' display, but as an XML form. This data can then be read in -and processed. Use the `--totals' option to include the running total -with each transaction. - -2.2.6 emacs ------------ - -The `emacs' command outputs results in a form that can be read directly -by Emacs Lisp. The format of the sexp is: - - ((BEG-POS CLEARED DATE CODE PAYEE - (ACCOUNT AMOUNT)...) ; list of transactions - ...) ; list of entries - -2.2.7 equity ------------- - -The `equity' command prints out accounts balances as if they were -entries. This makes it easy to establish the starting balances for an -account, such as when *Note Archiving previous years::. - -2.2.8 prices ------------- - -The `prices' command displays the price history for matching -commodities. The `-A' flag is useful with this report, to display the -running average price, or `-D' to show each price's deviation from that -average. - - There is also a `pricesdb' command which outputs the same -information as `prices', but does in a format that can be parsed by -Ledger. - -2.2.9 entry ------------ - -The `entry' commands simplifies the creation of new entries. It works -on the principle that 80% of all transactions are variants of earlier -transactions. Here's how it works: - - Say you currently have this transaction in your ledger file: - - 2004/03/15 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 - - Now it's `2004/4/9', and you've just eating at `Viva Italiano' -again. The exact amounts are different, but the overall form is the -same. With the `entry' command you can type: - - ledger entry 2004/4/9 viva food 11 tips 2.50 - - This produces the following output: - - 2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 - - It works by finding a past transaction matching the regular -expression `viva', and assuming that any accounts or amounts specified -will be similar to that earlier transaction. If Ledger does not -succeed in generating a new entry, an error is printed and the exit -code is set to `1'. - - There is a shell script in the distribution's `scripts' directory -called `entry', which simplifies the task of adding a new entry to your -ledger. It launches `vi' to confirm that the entry looks appropriate. - - Here are a few more examples of the `entry' command, assuming the -above journal entry: - - ledger entry 4/9 viva 11.50 - ledger entry 4/9 viva 11.50 checking # (from `checking') - ledger entry 4/9 viva food 11.50 tips 8 - ledger entry 4/9 viva food 11.50 tips 8 cash - ledger entry 4/9 viva food $11.50 tips $8 cash - ledger entry 4/9 viva dining "DM 11.50" - - -File: ledger.info, Node: Options, Next: Format strings, Prev: Commands, Up: Running Ledger - -2.3 Options -=========== - -With all of the reports, command-line options are useful to modify the -output generated. These command-line options always occur before the -command word. This is done to distinguish options from exclusive -regular expressions, which also begin with a dash. The basic form for -most commands is: - - ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] - - The OPTIONS and REGEXPS expressions are both optional. You could -just use `ledger balance', without any options--which prints a summary -of all accounts. But for more specific reporting, or to change the -appearance of the output, options are needed. - -* Menu: - -* Basic options:: -* Report filtering:: -* Output customization:: -* Commodity reporting:: -* Environment variables:: - - -File: ledger.info, Node: Basic options, Next: Report filtering, Prev: Options, Up: Options - -2.3.1 Basic options -------------------- - -These are the most basic command options. Most likely, the user will -want to set them using *Note Environment variables::, instead of using -actual command-line options: - - `--help' (`-h') prints a summary of all the options, and what they -are used for. This can be a handy way to remember which options do -what. This help screen is also printed if ledger is run without a -command. - - `--version' (`-v') prints the current version of ledger and exits. -This is useful for sending bug reports, to let the author know which -version of ledger you are using. - - `--file FILE' (`-f FILE') reads FILE as a ledger file. This command -may be used multiple times. FILE may also be a list of file names -separated by colons. Typically, the environment variable `LEDGER_FILE' -is set, rather than using this command-line option. - - `--output FILE' (`-o FILE') redirects output from any command to -FILE. By default, all output goes to standard output. - - `--init-file FILE' (`-i FILE') causes FILE to be read by ledger -before any other ledger file. This file may not contain any -transactions, but it may contain option settings. To specify options -in the init file, use the same syntax as the command-line. Here's an -example init file: - - --price-db ~/finance/.pricedb - - ; ~/.ledgerrc ends here - - Option settings on the command-line or in the environment always take -precedence over settings in the init file. - - `--cache FILE' identifies FILE as the default binary cache file. -That is, if the ledger files to be read are specified using the -environment variable `LEDGER_FILE', then whenever a command is finished -a binary copy will be written to the specified cache, to speed up the -loading time of subsequent queries. This filename can also be given -using the environment variable `LEDGER_CACHE', or by putting the option -into your init file. The `--no-cache' option causes Ledger to always -ignore the binary cache. - - `--account NAME' (`-a NAME') specifies the default account which QIF -file transactions are assumed to relate to. - - -File: ledger.info, Node: Report filtering, Next: Output customization, Prev: Basic options, Up: Options - -2.3.2 Report filtering ----------------------- - -These options change which transactions affect the outcome of a report, -in ways other than just using regular expressions: - - `--current'(`-c') displays only entries occurring on or before the -current date. - - `--begin DATE' (`-b DATE') constrains the report to entries on or -after DATE. Only entries after that date will be calculated, which -means that the running total in the balance report will always start at -zero with the first matching entry. (Note: This is different from -using `--display' to constrain what is displayed). - - `--end DATE' (`-e DATE') constrains the report so that entries on or -after DATE are not considered. The ending date is inclusive. - - `--period STR' (`-p STR') sets the reporting period to STR. This -will subtotal all matching entries within each period separately, -making it easy to see weekly, monthly, quarterly, etc., transaction -totals. A period string can even specify the beginning and end of the -report range, using simple terms like "last june" or "next month". For -more using period expressions, see *Note Period expressions::. - - `--period-sort EXPR' sorts the transactions within each reporting -period using the value expression EXPR. This is most often useful when -reporting monthly expenses, in order to view the highest expense -categories at the top of each month: - - ledger -M --period-sort -At reg ^Expenses - - `--cleared' (`-C') displays only transactions whose entry has been -marked "cleared" (by placing an asterix to the right of the date). - - `--uncleared' (`-U') displays only transactions whose entry has not -been marked "cleared" (i.e., if there is no asterix to the right of the -date). - - `--real' (`-R') displays only real transactions, not virtual. (A -virtual transaction is indicated by surrounding the account name with -parentheses or brackets; see the section on using virtual transactions -for more information). - - `--actual' (`-L') displays only actual transactions, and not those -created due to automated transactions. - - `--related' (`-r') displays transactions that are related to -whichever transactions would otherwise have matched the filtering -criteria. In the register report, this shows where money went to, or -the account it came from. In the balance report, it shows all the -accounts affected by entries having a related transaction. For -example, if a file had this entry: - - 2004/03/20 Safeway - Expenses:Food $65.00 - Expenses:Cash $20.00 - Assets:Checking $-85.00 - - And the register command was: - - ledger -r register food - - The following would be output, showing the transactions related to -the transaction that matched: - - 2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 - - `--budget' is useful for displaying how close your transactions meet -your budget. `--add-budget' also shows unbudgeted transactions, while -`--unbudgeted' shows only those. `--forecast' is a related option that -projects your budget into the future, showing how it will affect future -balances. *Note Budgeting and forecasting::. - - `--limit EXPR' (`-l EXPR') limits which transactions take part in -the calculations of a report. - - `--amount EXPR' (`-t EXPR') changes the value expression used to -calculate the "value" column in the `register' report, the amount used -to calculate account totals in the `balance' report, and the values -printed in the `equity' report. *Note Value expressions::. - - `--total EXPR' (`-T EXPR') sets the value expression used for the -"totals" column in the `register' and `balance' reports. - - -File: ledger.info, Node: Output customization, Next: Commodity reporting, Prev: Report filtering, Up: Options - -2.3.3 Output customization --------------------------- - -These options affect only the output, but not which transactions are -used to create it: - - `--collapse' (`-n') causes entries in a `register' report with -multiple transactions to be collapsed into a single, subtotaled entry. - - `--subtotal' (`-s') causes all entries in a `register' report to be -collapsed into a single, subtotaled entry. - - `--by-payee' (`-P') reports subtotals by payee. - - `--comm-as-payee' (`-x') changes the payee of every transaction to -be the commodity used in that transaction. This can be useful when -combined with other options, such as `-s'. - - `--empty' (`-E') includes even empty accounts in the `balance' -report. - - `--weekly' (`-W') reports transaction totals by the week. The week -begins on whichever day of the week begins the month containing that -transaction. To set a specific begin date, use a period string, such -as `weekly from DATE'. `--monthly' (`-M') reports transaction totals -by month; `--yearly' (`-Y') reports transaction totals by year. For -more complex period, using the `--period' option described above. - - `--dow' reports transactions totals for each day of the week. This -is an easy way to see if weekend spending is more than on weekdays. - - `--sort EXPR' (`-S EXPR') sorts a report by comparing the values -determined using the value expression EXPR. For example, using `-S --UT' in the balance report will sort account balances from greatest to -least, using the absolute value of the total. For more on how to use -value expressions, see *Note Value expressions::. - - `--wide' (`-w') causes the default `register' report to assume 132 -columns instead of 80. - - `--head' causes only the first N entries to be printed. This is -different from using the command-line utility `head', which would limit -to the first N transactions. `--tail' outputs only the last N entries. -Both options may be used simultaneously. If a negative amount is -given, it will invert the meaning of the flag (instead of the first -five entries being printed, for example, it would print all but the -first five). - - `--pager' tells Ledger to pass its output to the given pager -program--very useful when the output is especially long. This behavior -can be made the default by setting the `LEDGER_PAGER' environment -variable. - - `--average' (`-A') reports the average transaction value. - - `--deviation' (`-D') reports each transaction's deviation from the -average. It is only meaningful in the `register' and `prices' reports. - - `--percentage' (`-%') shows account subtotals in the `balance' -report as percentages of the parent account. - - `--totals' include running total information in the `xml' report. - - `--amount-data' (`-j') changes the `register' report so that it -output nothing but the date and the value column, and the latter -without commodities. This is only meaningful if the report uses a -single commodity. This data can then be fed to other programs, which -could plot the date, analyze it, etc. - - `--total-data' (`-J') changes the `register' report so that it -output nothing but the date and totals column, without commodities. - - `--display EXPR' (`-d EXPR') limits which transactions or accounts -or actually displayed in a report. They might still be calculated, and -be part of the running total of a register report, for example, but -they will not be displayed. This is useful for seeing last month's -checking transactions, against a running balance which includes all -transaction values: - - ledger -d "d>=[last month]" reg checking - - The output from this command is very different from the following, -whose running total includes only transactions from the last month -onward: - - ledger -p "last month" reg checking - - Which is more useful depends on what you're looking to know: the -total amount for the reporting range (`-p'), or simply a display -restricted to the reporting range (using `-d'). - - `--date-format STR' (`-y STR') changes the basic date format used by -reports. The default uses a date like 2004/08/01, which represents the -default date format of `%Y/%m/%d'. To change the way dates are printed -in general, the easiest way is to put `--date-format FORMAT' in the -Ledger initialization file `~/.ledgerrc' (or the file referred to by -`LEDGER_INIT'). - - `--format STR' (`-F STR') sets the reporting format for whatever -report ledger is about to make. *Note Format strings::. There are -also specific format commands for each report type: - - * `--balance-format STR' - - * `--register-format STR' - - * `--print-format STR' - - * `--plot-amount-format STR' (-j `register') - - * `--plot-total-format STR' (-J `register') - - * `--equity-format STR' - - * `--prices-format STR' - - * `--wide-register-format STR' (-w `register') - - -File: ledger.info, Node: Commodity reporting, Next: Environment variables, Prev: Output customization, Up: Options - -2.3.4 Commodity reporting -------------------------- - -These options affect how commodity values are displayed: - - `--price-db FILE' sets the file that is used for recording -downloaded commodity prices. It is always read on startup, to -determine historical prices. Other settings can be placed in this file -manually, to prevent downloading quotes for a specific, for example. -This is done by adding a line like the following: - - ; Don't download quotes for the dollar, or timelog values - N $ - N h - - `--price-exp MINS' (`-L MINS') sets the expected freshness of price -quotes, in minutes. That is, if the last known quote for any commodity -is older than this value--and if `--download' is being used--then the -Internet will be consulted again for a newer price. Otherwise, the old -price is still considered to be fresh enough. - - `--download' (`-Q') causes quotes to be automagically downloaded, as -needed, by running a script named `getquote' and expecting that script -to return a value understood by ledger. A sample implementation of a -`getquote' script, implemented in Perl, is provided in the -distribution. Downloaded quote price are then appended to the price -database, usually specified using the environment variable -`LEDGER_PRICE_DB'. - - There are several different ways that ledger can report the totals it -displays. The most flexible way to adjust them is by using value -expressions, and the `-t' and `-T' options. However, there are also -several "default" reports, which will satisfy most users basic -reporting needs: - -`-O, --quantity' - Reports commodity totals (this is the default) - -`-B, --basis' - Reports the cost basis for all transactions. - -`-V, --market' - Reports the last known market value for all commodities. - -`-g, --performance' - Reports the net gain/loss for each transaction in a `register' - report. - -`-G --gain' - Reports the net gain/loss for all commodities in the report that - have a price history. - - -File: ledger.info, Node: Environment variables, Prev: Commodity reporting, Up: Options - -2.3.5 Environment variables ---------------------------- - -Every option to ledger may be set using an environment variable. If an -option has a long name such `--this-option', setting the environment -variable `LEDGER_THIS_OPTION' will have the same affect as specifying -that option on the command-line. Options on the command-line always -take precedence over environment variable settings, however. - - Note that you may also permanently specify option values by placing -option settings in the file `~/.ledgerrc', for example: - - --cache /tmp/.mycache - - -File: ledger.info, Node: Format strings, Next: Value expressions, Prev: Options, Up: Running Ledger - -2.4 Format strings -================== - -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the `--format' -(`-F') option. Within that string, constructs are allowed which make -it possible to display the various parts of an account or transaction -in custom ways. - - Within a format strings, a substitution is specified using a percent -character (`%'). The basic format of all substitutions is: - - %[-][MIN WIDTH][.MAX WIDTH]EXPR - - If the optional minus sign (`-') follows the percent character, -whatever is substituted will be left justified. The default is right -justified. If a minimum width is given next, the substituted text will -be at least that wide, perhaps wider. If a period and a maximum width -is given, the substituted text will never be wider than this, and will -be truncated to fit. Here are some examples: - - %-P An entry's payee, left justified - %20P The same, right justified, at least 20 chars wide - %.20P The same, no more than 20 chars wide - %-.20P Left justified, maximum twenty chars wide - - The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The -allowable expressions are: - -`%' - Inserts a percent sign. - -`t' - Inserts the results of the value expression specified by `-t'. If - `-t' was not specified, the current report style's value - expression is used. - -`T' - Inserts the results of the value expression specified by `-T'. If - `-T' was not specified, the current report style's value - expression is used. - -`|' - Inserts a single space. This is useful if a width is specified, - for inserting a certain number of spaces. - -`_' - Inserts a space for each level of an account's depth. That is, if - an account has two parents, this construct will insert two spaces. - If a minimum width is specified, that much space is inserted for - each level of depth. Thus `%5_', for an account with four - parents, will insert twenty spaces. - -`(EXPR)' - Inserts the amount resulting from the value expression given in - parentheses. To insert five times the total value of an account, - for example, one could say `%12(5*O)'. Note: It's important to put - the five first in that expression, so that the commodity doesn't - get stripped from the total. - -`[DATEFMT]' - Inserts the result of formatting a transaction's date with a date - format string, exactly like those supported by `strftime'. For - example: `%[%Y/%m/%d %H:%M:%S]'. - -`S' - Insert the pathname of the file from which the entry's data was - read. - -`B' - Inserts the beginning character position of that entry within the - file. - -`b' - Inserts the beginning line of that entry within the file. - -`E' - Inserts the ending character position of that entry within the - file. - -`e' - Inserts the ending line of that entry within the file. - -`D' - By default, this is the same as `%[%Y/%m%/d]'. The date format - used can be changed at any time with the `-y' flag, however. - Using `%D' gives the user more control over the way dates are - output. - -`d' - This is the same as the `%D' option, unless the entry has an - effective date, in which case it prints - `[ACTUAL_DATE=EFFECtIVE_DATE]'. - -`X' - If a transaction has been cleared, this inserts `*' followed by a - space; otherwise nothing is inserted. - -`Y' - This is the same as `%X', except that it only displays a state - character if all of the member transactions have the same state. - -`C' - Inserts the checking number for an entry, in parentheses, followed - by a space; if none was specified, nothing is inserted. - -`P' - Inserts the payee related to a transaction. - -`a' - Inserts the optimal short name for an account. This is normally - used in balance reports. It prints a parent account's name if - that name has not been printed yet, otherwise it just prints the - account's name. - -`A' - Inserts the full name of an account. - -`W' - This is the same as `%A', except that it first displays the - transaction's state _if the entry's transaction states are not all - the same_, followed by the full account name. This is offered as - a printing optimization, so that combined with `%Y', only the - minimum amount of state detail is printed. - -`o' - Inserts the "optimized" form of a transaction's amount. This is - used by the print report. In some cases, this inserts nothing; in - others, it inserts the transaction amount and its cost. It's use - is not recommend unless you are modifying the print report. - -`n' - Inserts the note associated with a transaction, preceded by two - spaces and a semi-colon, if it exists. Thus, no none becomes an - empty string, while the note `foo' is substituted as ` ; foo'. - -`N' - Inserts the note associated with a transaction, if one exists. - -`/' - The `%/' construct is special. It separates a format string - between what is printed for the first transaction of an entry, and - what is printed for all subsequent transactions. If not used, the - same format string is used for all transactions. - - -File: ledger.info, Node: Value expressions, Next: Period expressions, Prev: Format strings, Up: Running Ledger - -2.5 Value expressions -===================== - -Value expressions are an expression language used by Ledger to -calculate values used by the program for many different purposes: - - 1. The values displayed in reports - - 2. For predicates (where truth is anything non-zero), to determine - which transactions are calculated (`-l') or displayed (`-d'). - - 3. For sorting criteria, to yield the sort key. - - 4. In the matching criteria used by automated transactions. - - Value expressions support most simple math and logic operators, in -addition to a set of one letter functions and variables. A function's -argument is whatever follows it. The following is a display predicate -that I use with the `balance' command: - - ledger -d /^Liabilities/?T<0:UT>100 balance - - The effect is that account totals are displayed only if: 1) A -Liabilities account has a total less than zero; or 2) the absolute -value of the account's total exceeds 100 units of whatever commodity -contains. If it contains multiple commodities, only one of them must -exceed 100 units. - - Display predicates are also very handy with register reports, to -constrain which entries are printed. For example, the following -command shows only entries from the beginning of the current month, -while still calculating the running balance based on all entries: - - ledger -d "d>[this month]" register checking - - This advantage to this command's complexity is that it prints the -running total in terms of all entries in the register. The following, -simpler command is similar, but totals only the displayed transactions: - - ledger -b "this month" register checking - -2.5.1 Variables ---------------- - -Below are the one letter variables available in any value expression. -For the register and print commands, these variables relate to -individual transactions, and sometimes the account affected by a -transaction. For the balance command, these variables relate to -accounts--often with a subtle difference in meaning. The use of each -variable for both is specified. - -`t' - This maps to whatever the user specified with `-t'. In a register - report, `-t' changes the value column; in a balance report, it has - no meaning by default. If `-t' was not specified, the current - report style's value expression is used. - -`T' - This maps to whatever the user specified with `-T'. In a register - report, `-T' changes the totals column; in a balance report, this - is the value given for each account. If `-T' was not specified, - the current report style's value expression is used. - -`m' - This is always the present moment/date. - -2.5.1.1 Transaction/account details -................................... - -`d' - A transaction's date, as the number of seconds past the epoch. - This is always "today" for an account. - -`a' - The transaction's amount; the balance of an account, without - considering children. - -`b' - The cost of a transaction; the cost of an account, without its - children. - -`v' - The market value of a transaction, or an account without its - children. - -`g' - The net gain (market value minus cost basis), for a transaction or - an account without its children. It is the same as `v-b'. - -`l' - The depth ("level") of an account. If an account has one parent, - it's depth is one. - -`n' - The index of a transaction, or the count of transactions affecting - an account. - -`X' - 1 if a transaction's entry has been cleared, 0 otherwise. - -`R' - 1 if a transaction is not virtual, 0 otherwise. - -`Z' - 1 if a transaction is not automated, 0 otherwise. - -2.5.1.2 Calculated totals -......................... - -`O' - The total of all transactions seen so far, or the total of an - account and all its children. - -`N' - The total count of transactions affecting an account and all its - children. - -`B' - The total cost of all transactions seen so far; the total cost of - an account and all its children. - -`V' - The market value of all transactions seen so far, or of an account - and all its children. - -`G' - The total net gain (market value minus cost basis), for a series of - transactions, or an account and its children. It is the same as - `V-B'. - -2.5.2 Functions ---------------- - -The available one letter functions are: - -`-' - Negates the argument. - -`U' - The absolute (unsigned) value of the argument. - -`S' - Strips the commodity from the argument. - -`A' - The arithmetic mean of the argument; `Ax' is the same as `x/n'. - -`P' - The present market value of the argument. The syntax `P(x,d)' is - supported, which yields the market value at time `d'. If no date - is given, then the current moment is used. - -2.5.3 Operators ---------------- - -The binary and ternary operators, in order of precedence, are: - - 1. `* /' - - 2. `+ -' - - 3. `! < > =' - - 4. `& | ?:' - -2.5.4 Complex expressions -------------------------- - -More complicated expressions are possible using: - -`NUM' - A plain integer represents a commodity-less amount. - -`{AMOUNT}' - An amount in braces can be any kind of amount supported by ledger, - with or without a commodity. Use this for decimal values. - -`/REGEXP/' - -`W/REGEXP/' - A regular expression that matches against an account's full name. - If a transaction, this will match against the account affected by - the transaction. - -`//REGEXP/' - -`p/REGEXP/' - A regular expression that matches against an entry's payee name. - -`///REGEXP/' - -`w/REGEXP/' - A regular expression that matches against an account's base name. - If a transaction, this will match against the account affected by - the transaction. - -`c/REGEXP/' - A regular expression that matches against the entry code (the text - that occurs between parentheses before the payee name). - -`e/REGEXP/' - A regular expression that matches against a transaction's note, or - comment field. - -`(EXPR)' - A sub-expression is nested in parenthesis. This can be useful - passing more complicated arguments to functions, or for overriding - the natural precedence order of operators. - -`[DATE]' - Useful specifying a date in plain terms. For example, you could - say `[2004/06/01]'. - - -File: ledger.info, Node: Period expressions, Next: File format, Prev: Value expressions, Up: Running Ledger - -2.6 Period expressions -====================== - -A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: - - [INTERVAL] [BEGIN] [END] - - The optional INTERVAL part may be any one of: - - every day - every week - every monthly - every quarter - every year - every N days # N is any integer - every N weeks - every N months - every N quarters - every N years - daily - weekly - biweekly - monthly - bimonthly - quarterly - yearly - - After the interval, a begin time, end time, both or neither may be -specified. As for the begin time, it can be either of: - - from <SPEC> - since <SPEC> - - The end time can be either of: - - to <SPEC> - until <SPEC> - - Where SPEC can be any of: - - 2004 - 2004/10 - 2004/10/1 - 10/1 - october - oct - this week # or day, month, quarter, year - next week - last week - - The beginning and ending can be given at the same time, if it spans a -single period. In that case, just use SPEC by itself. In that case, -the period `oct', for example, will cover all the days in october. The -possible forms are: - - <SPEC> - in <SPEC> - - Here are a few examples of period expressions: - - monthly - monthly in 2004 - weekly from oct - weekly from last month - from sep to oct - from 10/1 to 10/5 - monthly until 2005 - from apr - until nov - last oct - weekly last august - - -File: ledger.info, Node: File format, Next: Some typical queries, Prev: Period expressions, Up: Running Ledger - -2.7 File format -=============== - -The ledger file format is quite simple, but also very flexible. It -supports many options, though typically the user can ignore most of -them. They are summarized below. - - The initial character of each line determines what the line means, -and how it should be interpreted. Allowable initial characters are: - -`NUMBER' - A line beginning with a number denotes an entry. It may be - followed by any number of lines, each beginning with whitespace, - to denote the entry's account transactions. The format of the - first line is: - - DATE[=EDATE] [*|!] [(CODE)] DESC - - If `*' appears after the date (with optional effective date), it - indicates the entry is "cleared", which can mean whatever the user - wants it t omean. If `!' appears after the date, it indicates d - the entry is "pending"; i.e., tentatively cleared from the user's - point of view, but not yet actually cleared. If a `CODE' appears - in parentheses, it may be used to indicate a check number, or the - type of the transaction. Following these is the payee, or a - description of the transaction. - - The format of each following transaction is: - - ACCOUNT AMOUNT [; NOTE] - - The `ACCOUNT' may be surrounded by parentheses if it is a virtual - transactions, or square brackets if it is a virtual transactions - that must balance. The `AMOUNT' can be followed by a per-unit - transaction cost, by specifying ` AMOUNT', or a complete - transaction cost with `@ AMOUNT'. Lastly, the `NOTE' may specify - an actual and/or effective date for the transaction by using the - syntax `[ACTUAL_DATE]' or `[=EFFECTIVE_DATE]' or - `[ACTUAL_DATE=EFFECtIVE_DATE]'. - -`=' - An automated entry. A value expression must appear after the equal - sign. - - After this initial line there should be a set of one or more - transactions, just as if it were normal entry. If the amounts of - the transactions have no commodity, they will be applied as - modifiers to whichever real transaction is matched by the value - expression. - -`~' - A period entry. A period expression must appear after the tilde. - - After this initial line there should be a set of one or more - transactions, just as if it were normal entry. - -`!' - A line beginning with an exclamation mark denotes a command - directive. It must be immediately followed by the command word. - The supported commands are: - - `!include' - Include the stated ledger file. - - `!account' - The account name is given is taken to be the parent of all - transactions that follow, until `!end' is seen. - - `!end' - Ends an account block. - -`;' - A line beginning with a colon indicates a comment, and is ignored. - -`Y' - If a line begins with a capital Y, it denotes the year used for all - subsequent entries that give a date without a year. The year - should appear immediately after the Y, for example: `Y2004'. This - is useful at the beginning of a file, to specify the year for that - file. If all entries specify a year, however, this command has no - effect. - -`P' - Specifies a historical price for a commodity. These are usually - found in a pricing history file (see the `-Q' option). The syntax - is: - P DATE SYMBOL PRICE - -`N SYMBOL' - Indicates that pricing information is to be ignored for a given - symbol, nor will quotes ever be downloaded for that symbol. Useful - with a home currency, such as the dollar ($). It is recommended - that these pricing options be set in the price database file, which - defaults to `~/.pricedb'. The syntax for this command is: - N SYMBOL - -`D AMOUNT' - Specifies the default commodity to use, by specifying an amount in - the expected format. The `entry' command will use this commodity - as the default when none other can be determined. This command - may be used multiple times, to set the default flags for different - commodities; whichever is seen last is used as the default - commodity. For example, to set US dollars as the default - commodity, while also setting the thousands flag and decimal flag - for that commodity, use: - D $1,000.00 - -`C AMOUNT1 = AMOUNT2' - Specifies a commodity conversion, where the first amount is given - to be equivalent to the second amount. The first amount should - use the decimal precision desired during reporting: - C 1.00 Kb = 1024 bytes - -`i, o, b, h' - These four relate to timeclock support, which permits ledger to - read timelog files. See the timeclock's documentation for more - info on the syntax of its timelog files. - - -File: ledger.info, Node: Some typical queries, Next: Budgeting and forecasting, Prev: File format, Up: Running Ledger - -2.8 Some typical queries -======================== - -A query such as the following shows all expenses since last October, -sorted by total: - - ledger -b "last oct" -s -S T bal ^expenses - - From left to right the options mean: Show entries since October, -2003; show all sub-accounts; sort by the absolute value of the total; -and report the balance for all expenses. - -2.8.1 Reporting monthly expenses --------------------------------- - -The following query makes it easy to see monthly expenses, with each -month's expenses sorted by the amount: - - ledger -M --period-sort t reg ^expenses - - Now, you might wonder where the money came from to pay for these -things. To see that report, add `-r', which shows the "related -account" transactions: - - ledger -M --period-sort t -r reg ^expenses - - But maybe this prints too much information. You might just want to -see how much you're spending with your MasterCard. That kind of query -requires the use of a display predicate, since the transactions -calculated must match `^expenses', while the transactions displayed -must match `mastercard'. The command would be: - - ledger -M -r -d /mastercard/ reg ^expenses - - This query says: Report monthly subtotals; report the "related -account" transactions; display only related transactions whose account -matches `mastercard', and base the calculation on transactions matching -`^expenses'. - - This works just as well for report the overall total, too: - - ledger -s -r -d /mastercard/ reg ^expenses - - The `-s' option subtotals all transactions, just as `-M' subtotaled -by the month. The running total in both cases is off, however, since a -display expression is being used. - -2.8.2 Visualizing with Gnuplot ------------------------------- - -If you have `Gnuplot' installed, you can graph any of the above -register reports. The script to do this is included in the ledger -distribution, and is named `scripts/report'. Install `report' anywhere -along your `PATH', and then use `report' instead of `ledger' when doing -a register report. The only thing to keep in mind is that you must -specify `-j' or `-J' to indicate whether Gnuplot should plot the -amount, or the running total. For example, this command plots total -monthly expenses made on your MasterCard. - - report -j -M -r -d /mastercard/ reg ^expenses - - The `report' script is a very simple Bourne shell script, that -passes a set of scripted commands to Gnuplot. Feel free to modify the -script to your liking, since you may prefer histograms to line plots, -for example. - -2.8.2.1 Typical plots -..................... - -Here are some useful plots: - - report -j -M reg ^expenses # monthly expenses - report -J reg checking # checking account balance - report -J reg ^income ^expenses # cash flow report - - # net worth report, ignoring non-$ transactions - - report -J -l "Ua>={\$0.01}" reg ^assets ^liab - - # net worth report starting last February. the use of a display - # predicate (-d) is needed, otherwise the balance will start at - # zero, and thus the y-axis will not reflect the true balance - - report -J -l "Ua>={\$0.01}" -d "d>=[last feb]" reg ^assets ^liab - - The last report uses both a calculation predicate (`-l') and a -display predicate (`-d'). The calculation predicates limits the report -to transactions whose amount is greater than $1 (which can only happen -if the transaction amount is in dollars). The display predicate limits -the entries _displayed_ to just those since last February, even those -entries from before then will be computed as part of the balance. - - -File: ledger.info, Node: Budgeting and forecasting, Prev: Some typical queries, Up: Running Ledger - -2.9 Budgeting and forecasting -============================= - -2.9.1 Budgeting ---------------- - -Keeping a budget allows you to pay closer attention to your income and -expenses, by reporting how far your actual financial activity is from -your expectations. - - To start keeping a budget, put some period entries at the top of your -ledger file. A period entry is almost identical to a regular entry, -except that it begins with a tilde and has a period expression in place -of a payee. For example: - - ~ Monthly - Expenses:Rent $500.00 - Expenses:Food $450.00 - Expenses:Auto:Gas $120.00 - Expenses:Insurance $150.00 - Expenses:Phone $125.00 - Expenses:Utilities $100.00 - Expenses:Movies $50.00 - Expenses $200.00 ; all other expenses - Assets - - ~ Yearly - Expenses:Auto:Repair $500.00 - Assets - - These two period entries give the usual monthly expenses, as well as -one typical yearly expense. For help on finding out what your average -monthly expense is for any category, use a command like: - - ledger -p "this year" -MAs bal ^expenses - - The reported totals are the current year's average for each account. - - Once these period entries are defined, creating a budget report is as -easy as adding `--budget' to the command-line. For example, a typical -monthly expense report would be: - - ledger -M reg ^exp - - To see the same report balanced against your budget, use: - - ledger --budget -M reg ^exp - - A budget report includes only those accounts that appear in the -budget. To see all expenses balanced against the budget, use -`--add-budget'. You can even see only the unbudgeted expenses using -`--unbudgeted': - - ledger --unbudgeted -M reg ^exp - - You can also use these flags with the `balance' command. - -2.9.2 Forecasting ------------------ - -Sometimes it's useful to know what your finances will look like in the -future, such as determining when an account will reach zero. Ledger -makes this easy to do, using the same period entries as are used for -budgeting. An example forecast report can be generated with: - - ledger --forecast "T>{\$-500.00}" register ^assets ^liabilities - - This report continues outputting transactions until the running total -is greater than $-500.00. A final transaction is always output, to -show you what the total afterwards would be. - - Forecasting can also be used with the balance report, but by date -only, and not against the running total: - - ledger --forecast "d<[2010]" bal ^assets ^liabilities - - -File: ledger.info, Node: Keeping a ledger, Next: Using XML, Prev: Running Ledger, Up: Top - -3 Keeping a ledger -****************** - -The most important part of accounting is keeping a good ledger. If you -have a good ledger, tools can be written to work whatever -mathematically tricks you need to better understand your spending -patterns. Without a good ledger, no tool, however smart, can help you. - - The Ledger program aims at making ledger entry as simple as possible. -Since it is a command-line tool, it does not provide a user interface -for keeping a ledger. If you like, you may use GnuCash to maintain -your ledger, in which case the Ledger program will read GnuCash's data -files directly. In that case, read the GnuCash manual now, and skip to -the next chapter. - - If you are not using GnuCash, but a text editor to maintain your -ledger, read on. Ledger has been designed to make data entry as simple -as possible, by keeping the ledger format easy, and also by -automagically determining as much information as possible based on the -nature of your entries. - - For example, you do not need to tell Ledger about the accounts you -use. Any time Ledger sees a transaction involving an account it knows -nothing about, it will create it. If you use a commodity that is new -to Ledger, it will create that commodity, and determine its display -characteristics (placement of the symbol before or after the amount, -display precision, etc) based on how you used the commodity in the -transaction. - - Here is the Pacific Bell example from above, given as a Ledger -transaction: - - 9/29 (100) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking $-23.00 - - As you can see, it is very similar to what would be written on paper, -minus the computed balance totals, and adding in account names that -work better with Ledger's scheme of things. In fact, since Ledger is -smart about many things, you don't need to specify the balanced amount, -if it is the same as the first line: - - 9/29 (100) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking - - For this entry, Ledger will figure out that $-23.00 must come from -`Assets:Checking' in order to balance the entry. - -* Menu: - -* Stating where money goes:: -* Assets and Liabilities:: -* Commodities and Currencies:: -* Accounts and Inventories:: -* Understanding Equity:: -* Dealing with Petty Cash:: -* Working with multiple funds and accounts:: -* Archiving previous years:: -* Virtual transactions:: -* Automated transactions:: -* Using Emacs to Keep Your Ledger:: -* Using GnuCash to Keep Your Ledger:: -* Using timeclock to record billable time:: - - -File: ledger.info, Node: Stating where money goes, Next: Assets and Liabilities, Prev: Keeping a ledger, Up: Keeping a ledger - -3.1 Stating where money goes -============================ - -Accountants will talk of "credits" and "debits", but the meaning is -often different from the layman's understanding. To avoid confusion, -Ledger uses only subtractions and additions, although the underlying -intent is the same as standard accounting principles. - - Recall that every transaction will involve two or more accounts. -Money is transferred from one or more accounts to one or more other -accounts. To record the transaction, an amount is _subtracted_ from -the source accounts, and _added_ to the target accounts. - - In order to write a Ledger entry correctly, you must determine where -the money comes from and where it goes to. For example, when you are -paid a salary, you must add money to your bank account and also -subtract it from an income account: - - 9/29 My Employer - Assets:Checking $500.00 - Income:Salary $-500.00 - - Why is the Income a negative figure? When you look at the balance -totals for your ledger, you may be surprised to see that Expenses are a -positive figure, and Income is a negative figure. It may take some -getting used to, but to properly use a general ledger you must think in -terms of how money moves. Rather than Ledger "fixing" the minus signs, -let's understand why they are there. - - When you earn money, the money has to come from somewhere. Let's -call that somewhere "society". In order for society to give you an -income, you must take money away (withdraw) from society in order to -put it into (make a payment to) your bank. When you then spend that -money, it leaves your bank account (a withdrawal) and goes back to -society (a payment). This is why Income will appear negative--it -reflects the money you have drawn from society--and why Expenses will -be positive--it is the amount you've given back. These additions and -subtractions will always cancel each other out in the end, because you -don't have the ability to create new money: it must always come from -somewhere, and in the end must always leave. This is the beginning of -economy, after which the explanation gets terribly difficult. - - Based on that explanation, here's another way to look at your balance -report: every negative figure means that that account or person or -place has less money now than when you started your ledger; and every -positive figure means that that account or person or place has more -money now that when you started your ledger. Make sense? - - -File: ledger.info, Node: Assets and Liabilities, Next: Commodities and Currencies, Prev: Stating where money goes, Up: Keeping a ledger - -3.2 Assets and Liabilities -========================== - -Assets are money that you have, and Liabilities are money that you owe. -"Liabilities" is just a more inclusive name for Debts. - - An Asset is typically increased by transferring money from an Income -account, such as when you get paid. Here is a typical entry: - - 2004/09/29 My Employer - Assets:Checking $500.00 - Income:Salary - - Money, here, comes from an Income account belonging to "My -Employer", and is transferred to your checking account. The money is -now yours, which makes it an Asset. - - Liabilities track money owed to others. This can happen when you -borrow money to buy something, or if you owe someone money. Here is an -example of increasing a MasterCard liability by spending money with it: - - 2004/09/30 Restaurant - Expenses:Dining $25.00 - Liabilities:MasterCard - - The Dining account balance now shows $25 spent on Dining, and a -corresponding $25 owed on the MasterCard--and therefore shown as -$-25.00. The MasterCard liability shows up as negative because it -offsets the value of your assets. - - The combined total of your Assets and Liabilities is your net worth. -So to see your current net worth, use this command: - - ledger balance ^assets ^liabilities - - Relatedly, your Income accounts show up negative, because they -transfer money _from_ an account in order to increase your assets. -Your Expenses show up positive because that is where the money went to. -The combined total of Income and Expenses is your cash flow. A -positive cash flow means you are spending more than you make, since -income is always a negative figure. To see your current cash flow, use -this command: - - ledger balance ^income ^expenses - - Another common question to ask of your expenses is: How much do I -spend each month on X? Ledger provides a simple way of displaying -monthly totals for any account. Here is an example that summarizes -your monthly automobile expenses: - - ledger -M register expenses:auto - - This assumes, of course, that you use account names like -`Expenses:Auto:Gas' and `Expenses:Auto:Repair'. - -3.2.1 Tracking reimbursable expenses ------------------------------------- - -Sometimes you will want to spend money on behalf of someone else, which -will eventually get repaid. Since the money is still "yours", it is -really an asset. And since the expenditure was for someone else, you -don't want it contaminating your Expenses reports. You will need to -keep an account for tracking reimbursements. - - This is fairly easy to do in ledger. When spending the money, spend -it _to_ your Assets:Reimbursements, using a different account for each -person or business that you spend money for. For example: - - 2004/09/29 Circuit City - Assets:Reimbursements:Company XYZ $100.00 - Liabilities:MasterCard - - This shows $100.00 spent on a MasterCard at Circuit City, with the -expense was made on behalf of Company XYZ. Later, when Company XYZ -pays the amount back, the money will transfer from that reimbursement -account back to a regular asset account: - - 2004/09/29 Company XYZ - Assets:Checking $100.00 - Assets:Reimbursements:Company XYZ - - This deposits the money owed from Company XYZ into a checking -account, presumably because they paid the amount back with a check. - - But what to do if you run your own business, and you want to keep -track of expenses made on your own behalf, while still tracking -everything in a single ledger file? This is more complex, because you -need to track two separate things: 1) The fact that the money should be -reimbursed to you, and 2) What the expense account was, so that you can -later determine where your company is spending its money. - - This kind of transaction is best handled with mirrored transactions -in two different files, one for your personal accounts, and one for your -company accounts. But keeping them in one file involves the same kinds -of transactions, so those are what is shown here. First, the personal -entry, which shows the need for reimbursement: - - 2004/09/29 Circuit City - Assets:Reimbursements:Company XYZ $100.00 - Liabilities:MasterCard - - This is the same as above, except that you own Company XYZ, and are -keeping track of its expenses in the same ledger file. This entry -should be immediately followed by an equivalent entry, which shows the -kind of expense, and also notes the fact that $100.00 is now payable to -you: - - 2004/09/29 Circuit City - Company XYZ:Expenses:Computer:Software $100.00 - Company XYZ:Accounts Payable:Your Name - - This second entry shows that Company XYZ has just spent $100.00 on -software, and that this $100.00 came from Your Name, which must be paid -back. - - These two entries can also be merged, to make things a little -clearer. Note that all amounts must be specified now: - - 2004/09/29 Circuit City - Assets:Reimbursements:Company XYZ $100.00 - Liabilities:MasterCard $-100.00 - Company XYZ:Expenses:Computer:Software $100.00 - Company XYZ:Accounts Payable:Your Name $-100.00 - - To "pay back" the reimbursement, just reverse the order of -everything, except this time drawing the money from a company asset, -paying it to accounts payable, and then drawing it again from the -reimbursement account, and paying it to your personal asset account. -It's easier shown than said: - - 2004/10/15 Company XYZ - Assets:Checking $100.00 - Assets:Reimbursements:Company XYZ $-100.00 - Company XYZ:Accounts Payable:Your Name $100.00 - Company XYZ:Assets:Checking $-100.00 - - And now the reimbursements account is paid off, accounts payable is -paid off, and $100.00 has been effectively transferred from the -company's checking account to your personal checking account. The -money simply "waited"--in both `Assets:Reimbursements:Company XYZ', and -`Company XYZ:Accounts Payable:Your Name'--until such time as it could -be paid off. - - The value of tracking expenses from both sides like that is that you -do not contaminate your personal expense report with expenses made on -behalf of others, while at the same time making it possible to generate -accurate reports of your company's expenditures. It is more verbose -than just paying for things with your personal assets, but it gives you -a very accurate information trail. - - The advantage to keep these doubled entries together is that they -always stay in sync. The advantage to keeping them apart is that it -clarifies the transfer's point of view. To keep the transactions in -separate files, just separate the two entries that were joined above. -For example, for both the expense and the pay-back shown above, the -following four entries would be created. Two in your personal ledger -file: - - 2004/09/29 Circuit City - Assets:Reimbursements:Company XYZ $100.00 - Liabilities:MasterCard $-100.00 - - 2004/10/15 Company XYZ - Assets:Checking $100.00 - Assets:Reimbursements:Company XYZ $-100.00 - - And two in your company ledger file: - - !account Company XYZ - - 2004/09/29 Circuit City - Expenses:Computer:Software $100.00 - Accounts Payable:Your Name $-100.00 - - 2004/10/15 Company XYZ - Accounts Payable:Your Name $100.00 - Assets:Checking $-100.00 - - !end - - (Note: The `!account' above means that all accounts mentioned in the -file are children of that account. In this case it means that all -activity in the file relates to Company XYZ). - - After creating these entries, you will always know that $100.00 was -spent using your MasterCard on behalf of Company XYZ, and that Company -XYZ spent the money on computer software and paid it back about two -weeks later. - - -File: ledger.info, Node: Commodities and Currencies, Next: Accounts and Inventories, Prev: Assets and Liabilities, Up: Keeping a ledger - -3.3 Commodities and Currencies -============================== - -Ledger makes no assumptions about the commodities you use; it only -requires that you specify a commodity. The commodity may be any -non-numeric string that does not contain a period, comma, forward slash -or at-sign. It may appear before or after the amount, although it is -assumed that symbols appearing before the amount refer to currencies, -while non-joined symbols appearing after the amount refer to -commodities. Here are some valid currency and commodity specifiers: - - $20.00 ; currency: twenty US dollars - 40 AAPL ; commodity: 40 shares of Apple stock - 60 DM ; currency: 60 Deutsch Mark - £50 ; currency: 50 British pounds - 50 EUR ; currency: 50 Euros (or use appropriate symbol) - - Ledger will examine the first use of any commodity to determine how -that commodity should be printed on reports. It pays attention to -whether the name of commodity was separated from the amount, whether it -came before or after, the precision used in specifying the amount, -whether thousand marks were used, etc. This is done so that printing -the commodity looks the same as the way you use it. - - An account may contain multiple commodities, in which case it will -have separate totals for each. For example, if your brokerage account -contains both cash, gold, and several stock quantities, the balance -might look like: - - $200.00 - 100.00 AU - AAPL 40 - BORL 100 - FEQTX 50 Assets:Brokerage - - This balance report shows how much of each commodity is in your -brokerage account. - - Sometimes, you will want to know the current street value of your -balance, and not the commodity totals. For this to happen, you must -specify what the current price is for each commodity. The price can be -any commodity, in which case the balance will be computed in terms of -that commodity. The usual way to specify prices is with a price -history file, which might look like this: - - P 2004/06/21 02:18:01 FEQTX $22.49 - P 2004/06/21 02:18:01 BORL $6.20 - P 2004/06/21 02:18:02 AAPL $32.91 - P 2004/06/21 02:18:02 AU $400.00 - - Specify the price history to use with the `--price-db' option, with -the `-V' option to report in terms of current market value: - - ledger --price-db prices.db -V balance brokerage - - The balance for your brokerage account will be reported in US -dollars, since the prices database uses that currency. - - $40880.00 Assets:Brokerage - - You can convert from any commodity to any other commodity. Let's say -you had $5000 in your checking account, and for whatever reason you -wanted to know many ounces of gold that would buy, in terms of the -current price of gold: - - ledger -T "{1 AU}*(O/P{1 AU})" balance checking - - Although the total expression appears complex, it is simply saying -that the reported total should be in multiples of AU units, where the -quantity is the account total divided by the price of one AU. Without -the initial multiplication, the reported total would still use the -dollars commodity, since multiplying or dividing amounts always keeps -the left value's commodity. The result of this command might be: - - 14.01 AU Assets:Checking - -3.3.1 Commodity price histories -------------------------------- - -Whenever a commodity is purchased using a different commodity (such as -a share of common stock using dollars), it establishes a price for that -commodity on that day. It is also possible, by recording price details -in a ledger file, to specify other prices for commodities at any given -time. Such price entries might look like those below: - - P 2004/06/21 02:17:58 TWCUX $27.76 - P 2004/06/21 02:17:59 AGTHX $25.41 - P 2004/06/21 02:18:00 OPTFX $39.31 - P 2004/06/21 02:18:01 FEQTX $22.49 - P 2004/06/21 02:18:02 AAPL $32.91 - - By default, ledger will not consider commodity prices when generating -its various reports. It will always report balances in terms of the -commodity total, rather than the current value of those commodities. -To enable pricing reports, use one of the commodity reporting options. - -3.3.2 Commodity equivalencies ------------------------------ - -Sometimes a commodity has several forms which are all equivalent. An -example of this is time. Whether tracked in terms of minutes, hours or -days, it should be possible to convert between the various forms. -Doing this requires the use of commodity equivalencies. - - For example, you might have the following two transactions, one which -transfers an hour of time into a `Billable' account, and another which -decreases the same account by ten minutes. The resulting report will -indicate that fifty minutes remain: - - 2005/10/01 Work done for company - Billable:Client 1h - Project:XYZ - - 2005/10/02 Return ten minutes to the project - Project:XYZ 10m - Billable:Client - - Reporting the balance for this ledger file produces: - - 50.0m Billable:Client - -50.0m Project:XYZ - - This example works because ledger already knows how to handle -seconds, minutes and hours, as part of its time tracking support. -Defining other equivalencies is simple. The following is an example -that creates data equivalencies, helpful for tracking bytes, kilobytes, -megabytes, and more: - - C 1.00 Kb = 1024 b - C 1.00 Mb = 1024 Kb - C 1.00 Gb = 1024 Mb - C 1.00 Tb = 1024 Gb - - Each of these definitions correlates a commodity (such as `Kb') and -a default precision, with a certain quantity of another commodity. In -the above example, kilobytes are reporetd with two decimal places of -precision and each kilobyte is equal to 1024 bytes. - - Equivalency chains can be as long as desired. Whenever a commodity -would report as a decimal amount (less than `1.00'), the next smallest -commodity is used. If a commodity could be reported in terms of a -higher commodity without resulting to a partial fraction, then the -larger commodity is used. - - -File: ledger.info, Node: Accounts and Inventories, Next: Understanding Equity, Prev: Commodities and Currencies, Up: Keeping a ledger - -3.4 Accounts and Inventories -============================ - -Since Ledger's accounts and commodity system is so flexible, you can -have accounts that don't really exist, and use commodities that no one -else recognizes. For example, let's say you are buying and selling -various items in EverQuest, and want to keep track of them using a -ledger. Just add items of whatever quantity you wish into your -EverQuest account: - - 9/29 Get some stuff at the Inn - Places:Black's Tavern -3 Apples - Places:Black's Tavern -5 Steaks - EverQuest:Inventory - - Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The -amounts are negative, because you are taking _from_ Black's Tavern in -order to add to your Inventory account. Note that you don't have to -use `Places:Black's Tavern' as the source account. You could use -`EverQuest:System' to represent the fact that you acquired them online. -The only purpose for choosing one kind of source account over another -is for generate more informative reports later on. The more you know, -the better analysis you can perform. - - If you later sell some of these items to another player, the entry -would look like: - - 10/2 Sturm Brightblade - EverQuest:Inventory -2 Steaks - EverQuest:Inventory 15 Gold - - Now you've turned 2 steaks into 15 gold, courtesy of your customer, -Sturm Brightblade. - - -File: ledger.info, Node: Understanding Equity, Next: Dealing with Petty Cash, Prev: Accounts and Inventories, Up: Keeping a ledger - -3.5 Understanding Equity -======================== - -The most confusing entry in any ledger will be your equity account-- -because starting balances can't come out of nowhere. - - When you first start your ledger, you will likely already have money -in some of your accounts. Let's say there's $100 in your checking -account; then add an entry to your ledger to reflect this amount. -Where will money come from? The answer: your equity. - - 10/2 Opening Balance - Assets:Checking $100.00 - Equity:Opening Balances - - But what is equity? You may have heard of equity when people talked -about house mortgages, as "the part of the house that you own". -Basically, equity is like the value of something. If you own a car -worth $5000, then you have $5000 in equity in that car. In order to -turn that car (a commodity) into a cash flow, or a credit to your bank -account, you will have to debit the equity by selling it. - - When you start a ledger, you are probably already worth something. -Your net worth is your current equity. By transferring the money in -the ledger from your equity to your bank accounts, you are crediting -the ledger account based on your prior equity. That is why, when you -look at the balance report, you will see a large negative number for -Equity that never changes: Because that is what you were worth (what -you debited from yourself in order to start the ledger) before the -money started moving around. If the total positive value of your -assets is greater than the absolute value of your starting equity, it -means you are making money. - - Clear as mud? Keep thinking about it. Until you figure it out, put -`-Equity' at the end of your balance command, to remove the confusing -figure from the total. - - -File: ledger.info, Node: Dealing with Petty Cash, Next: Working with multiple funds and accounts, Prev: Understanding Equity, Up: Keeping a ledger - -3.6 Dealing with Petty Cash -=========================== - -Something that stops many people from keeping a ledger at all is the -insanity of tracking small cash expenses. They rarely generate a -receipt, and there are often a lot of small transactions, rather than a -few large ones, as with checks. - - One solution is: don't bother. Move your spending to a debit card, -but in general ignore cash. Once you withdraw it from the ATM, mark it -as already spent to an `Expenses:Cash' category: - - 2004/03/15 ATM - Expenses:Cash $100.00 - Assets:Checking - - If at some point you make a large cash expense that you want to -track, just "move" the amount of the expense from `Expenses:Cash' into -the target account: - - 2004/03/20 Somebody - Expenses:Food $65.00 - Expenses:Cash - - This way, you can still track large cash expenses, while ignoring all -of the smaller ones. - - -File: ledger.info, Node: Working with multiple funds and accounts, Next: Archiving previous years, Prev: Dealing with Petty Cash, Up: Keeping a ledger - -3.7 Working with multiple funds and accounts -============================================ - -There are situations when the accounts you're tracking are different -between your clients and the financial institutions where money is -kept. An example of this is working as the treasurer for a religious -institution. From the secular point of view, you might be working with -three different accounts: - - * Checking - - * Savings - - * Credit Card - - From a religious point of view, the community expects to divide its -resources into multiple "funds", from which it makes purchases or -reserves resources for later: - - * School fund - - * Building fund - - * Community fund - - The problem with this kind of setup is that when you spend money, it -comes from two or more places at once: the account and the fund. And -yet, the correlation of amounts between funds and accounts is rarely -one-to-one. What if the school fund has `$500.00', but `$400.00' of -that comes from Checking, and `$100.00' from Savings? - - Traditional finance packages require that the money reside in only -one place. But there are really two "views" of the data: from the -account point of view and from the fund point of view - yet both sets -should reflect the same overall expenses and cash flow. It's simply -where the money resides that differs. - - This situation can be handled one of two ways. The first is using -virtual transactions to represent the fact that money is moving to and -from two kind of accounts at the same time: - - 2004/03/20 Contributions - Assets:Checking $500.00 - Income:Donations - - 2004/03/25 Distribution of donations - [Funds:School] $300.00 - [Funds:Building] $200.00 - [Assets:Checking] $-500.00 - - The use of square brackets in the second entry ensures that the -virtual transactions balance to zero. Now money can be spent directly -from a fund at the same time as money is drawn from a physical account: - - 2004/03/25 Payment for books (paid from Checking) - Expenses:Books $100.00 - Assets:Checking $-100.00 - (Funds:School) $-100.00 - - When reports are generated, by default they'll appear in terms of the -funds. In this case, you will likely want to mask out your `Assets' -account, because otherwise the balance won't make much sense: - - ledger bal -^Assets - - If the `--real' option is used, the report will be in terms of the -real accounts: - - ledger --real bal - - If more asset accounts are needed as the source of a transaction, -just list them as you would normally, for example: - - 2004/03/25 Payment for books (paid from Checking) - Expenses:Books $100.00 - Assets:Checking $-50.00 - Liabilities:Credit Card $-50.00 - (Funds:School) $-100.00 - - The second way of tracking funds is to use entry codes. In this -respect the codes become like virtual accounts that embrace the entire -set of transactions. Basically, we are associating an entry with a -fund by setting its code. Here are two entries that desposit money -into, and spend money from, the `Funds:School' fund: - - 2004/03/25 (Funds:School) Donations - Assets:Checking $100.00 - Income:Donations - - 2004/04/25 (Funds:School) Payment for books - Expenses:Books $50.00 - Assets:Checking - - Note how the accounts now relate only to the real accounts, and any -balance or registers reports will reflect this. That the entries -relate to a particular fund is kept only in the code. - - How does this become a fund report? By using the `--code-as-payee' -option, you can generate a register report where the payee for each -transaction shows the code. Alone, this is not terribly interesting; -but when combined with the `--by-payee' option, you will now see -account subtotals for any transactions related to a specific fund. So, -to see the current monetary balances of all funds, the command would be: - - ledger --code-as-payee -P reg ^Assets - - Or to see a particular funds expenses, the `School' fund in this -case: - - ledger --code-as-payee -P reg ^Expenses -- School - - Both approaches yield different kinds of flexibility, depending on -how you prefer to think of your funds: as virtual accounts, or as tags -associated with particular entries. Your own tastes will decide which -is best for your situation. - - -File: ledger.info, Node: Archiving previous years, Next: Virtual transactions, Prev: Working with multiple funds and accounts, Up: Keeping a ledger - -3.8 Archiving previous years -============================ - -After a while, your ledger can get to be pretty large. While this will -not slow down the ledger program much--it's designed to process ledger -files very quickly--things can start to feel "messy"; and it's a -universal complaint that when finances feel messy, people avoid them. - - Thus, archiving the data from previous years into their own files can -offer a sense of completion, and freedom from the past. But how to -best accomplish this with the ledger program? There are two commands -that make it very simple: `print', and `equity'. - - Let's take an example file, with data ranging from year 2000 until -2004. We want to archive years 2000 and 2001 to their own file, -leaving just 2003 and 2004 in the current file. So, use `print' to -output all the earlier entries to a file called `ledger-old.dat': - - ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat - - To delete older data from the current ledger file, use `print' -again, this time specifying year 2002 as the starting date: - - ledger -f ledger.dat -b 2002 print > x - mv x ledger.dat - - However, now the current file contains _only_ transactions from 2002 -onward, which will not yield accurate present-day balances, because the -net income from previous years is no longer being tallied. To -compensate for this, we must append an equity report for the old ledger -at the beginning of the new one: - - ledger -f ledger-old.dat equity > equity.dat - cat equity.dat ledger.dat > x - mv x ledger.dat - rm equity.dat - - Now the balances reported from `ledger.dat' are identical to what -they were before the data was split. - - How often should you split your ledger? You never need to, if you -don't want to. Even eighty years of data will not slow down ledger -much--and that's just using present day hardware! Or, you can keep the -previous and current year in one file, and each year before that in its -own file. It's really up to you, and how you want to organize your -finances. For those who also keep an accurate paper trail, it might be -useful to archive the older years to their own files, then burn those -files to a CD to keep with the paper records--along with any electronic -statements received during the year. In the arena of organization, -just keep in mind this maxim: Do whatever keeps you doing it. - - -File: ledger.info, Node: Virtual transactions, Next: Automated transactions, Prev: Archiving previous years, Up: Keeping a ledger - -3.9 Virtual transactions -======================== - -A virtual transaction is when you, in your mind, see money as moving to -a certain place, when in reality that money has not moved at all. -There are several scenarios in which this type of tracking comes in -handy, and each of them will be discussed in detail. - - To enter a virtual transaction, surround the account name in -parentheses. This form of usage does not need to balance. However, if -you want to ensure the virtual transaction balances with other virtual -transactions in the same entry, use square brackets. For example: - - 10/2 Paycheck - Assets:Checking $1000.00 - Income:Salary $-1000.00 - (Debt:Alimony) $200.00 - - In this example, after receiving a paycheck an alimony debt is -increased--even though no money has moved around yet. - - 10/2 Paycheck - Assets:Checking $1000.00 - Income:Salary $-1000.00 - [Savings:Trip] $200.00 - [Assets:Checking] $-200.00 - - In this example, $200 has been deducted from checking toward savings -for a trip. It will appear as though the money has been moved from the -account into `Savings:Trip', although no money has actually moved -anywhere. - - When balances are displayed, virtual transactions will be factored -in. To view balances without any virtual balances factored in, using -the `-R' flag, for "reality". - - -File: ledger.info, Node: Automated transactions, Next: Using Emacs to Keep Your Ledger, Prev: Virtual transactions, Up: Keeping a ledger - -3.10 Automated transactions -=========================== - -As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire -assets. It is similar to tithing for Jews and Christians, or to Zakát -for Muslims. The exact details of computing Huqúqu'lláh are somewhat -complex, but if you have further interest, please consult the Web. - - Ledger makes this otherwise difficult law very easy. Just set up an -automated transaction at the top of your ledger file: - - ; This automated entry will compute Huqúqu'lláh based on this - ; journal's transactions. Any that match will affect the - ; Liabilities:Huququ'llah account by 19% of the value of that - ; transaction. - - = /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ - (Liabilities:Huququ'llah) 0.19 - - This automated transaction works by looking at each transaction in -the ledger file. If any match the given value expression, 19% of the -transaction's value is applied to the `Liabilities:Huququ'llah' -account. So, if $1000 is earned from `Income:Salary', $190 is added to -`Liabilities:Huqúqu'lláh'; if $1000 is spent on Rent, $190 is -subtracted. The ultimate balance of Huqúqu'lláh reflects how much is -owed in order to fulfill one's obligation to Huqúqu'lláh. When ready -to pay, just write a check to cover the amount shown in -`Liabilities:Huququ'llah'. That entry would look like: - - 2003/01/01 (101) Baha'i Huqúqu'lláh Trust - Liabilities:Huququ'llah $1,000.00 - Assets:Checking - - That's it. To see how much Huqúq is currently owed based on your -ledger entries, use: - - ledger balance Liabilities:Huquq - - This works fine, but omits one aspect of the law: that Huquq is only -due once the liability exceeds the value of 19 mithqáls of gold (which -is roughly 2.22 ounces). So what we want is for the liability to -appear in the balance report only when it exceeds the present day value -of 2.22 ounces of gold. This can be accomplished using the command: - - ledger -Q -t "/Liab.*Huquq/?(a/P{2.22 AU}<={-1.0}&a):a" -s bal liab - - With this command, the current price for gold is downloaded, and the -Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces -of gold. If you wish the liability to be reflected in the parent -subtotal either way, use this instead: - - ledger -Q -T "/Liab.*Huquq/?(O/P{2.22 AU}<={-1.0}&O):O" -s bal liab - - In some cases, you may wish to refer to the account of whichever -transaction matched your automated entry's value expression. To do -this, use the special account name `$account': - - = /^Some:Long:Account:Name/ - [$account] -0.10 - [Savings] 0.10 - - This example causes 10% of the matching account's total to be -deferred to the `Savings' account--as a balanced virtual transaction, -which may be excluded from reports by using `--real'. - - -File: ledger.info, Node: Using Emacs to Keep Your Ledger, Next: Using GnuCash to Keep Your Ledger, Prev: Automated transactions, Up: Keeping a ledger - -3.11 Using Emacs to Keep Your Ledger -==================================== - -In the Ledger tarball is an Emacs module, `ledger.el'. This module -makes the process of keeping a text ledger much easier for Emacs users. -I recommend putting this at the top of your ledger file: - - ; -*-ledger-*- - - And this in your `.emacs' file, after copying `ledger.el' to your -`site-lisp' directory: - - (load "ledger") - - Now when you edit your ledger file, it will be in `ledger-mode'. -`ledger-mode' adds these commands: - -*C-c C-a* - For quickly adding new entries based on the form of older ones (see - previous section). - -*C-c C-c* - Toggles the "cleared" flag of the transaction under point. - -*C-c C-d* - Delete the entry under point. - -*C-c C-r* - Reconciles an account by displaying the transactions in another - buffer, where simply hitting the spacebar will toggle the pending - flag of the transaction in the ledger. Once all the appropriate - transactions have been marked, press C-c C-c in the reconcile - buffer to "commit" the reconciliation, which will mark all of the - entries as cleared, and display the new cleared balance in the - minibuffer. - -*C-c C-m* - Set the default month for new entries added with C-c C-a. This is - handy if you have a large number of transactions to enter from a - previous month. - -*C-c C-y* - Set the default year for new entries added with C-c C-a. This is - handy if you have a large number of transactions to enter from a - previous year. - - Once you enter the reconcile buffer, there are several key commands -available: - -*RET* - Visit the ledger file entry corresponding to the reconcile entry. - -*C-c C-c* - Commit the reconcialation. This marks all of the marked - transactions as "cleared", saves the ledger file, and then - displays the new cleared balance. - -*C-l* - Refresh the reconcile buffer by re-reading transactions from the - ledger data file. - -*SPC* - Toggle the transaction under point as cleared. - -*a* - Add a new entry to the ledger data file, and refresh the reconcile - buffer to include its transactions (if the entry is added to the - same account as the one being reconciled). - -*d* - Delete the entry related to the transaction under point. Note: - This may result in multiple transactions being deleted. - -*n* - Move to the next line. - -*p* - Move to the previous line. - -*C-c C-r* - -*r* - Attempt to auto-reconcile the transactions to the entered balance. - If it can do so, it will mark all those transactions as pending - that would yield the specified balance. - -*C-x C-s* - -*s* - Save the ledger data file, and show the current cleared balance for - the account being reconciled. - -*q* - Quit the reconcile buffer. - - There is also an `emacs' command which can be used to output reports -in a format directly `read'-able from Emacs Lisp. - - -File: ledger.info, Node: Using GnuCash to Keep Your Ledger, Next: Using timeclock to record billable time, Prev: Using Emacs to Keep Your Ledger, Up: Keeping a ledger - -3.12 Using GnuCash to Keep Your Ledger -====================================== - -The Ledger tool is fast and simple, but it offers no custom method for -actually editing the ledger. It assumes you know how to use a text -editor, and like doing so. Perhaps an Emacs mode will appear someday -soon to make editing Ledger's data files much easier. - - Until then, you are free to use GnuCash to maintain your ledger, and -the Ledger program for querying and reporting on the contents of that -ledger. It takes a little longer to parse the XML data format that -GnuCash uses, but the end result is identical. - - Then again, why would anyone use a Gnome-centric, 35 megabyte -behemoth to edit their data, and a one megabyte binary to query it? - - -File: ledger.info, Node: Using timeclock to record billable time, Prev: Using GnuCash to Keep Your Ledger, Up: Keeping a ledger - -3.13 Using timeclock to record billable time -============================================ - -The timeclock tool makes it easy to track time events, like clocking -into and out of a particular job. These events accumulate in a timelog -file. - - Each in/out event may have an optional description. If the "in" -description is a ledger account name, these in/out pairs may be viewed -as virtual transactions, adding time commodities (hours) to that -account. - - For example, the command-line version of the timeclock tool could be -used to begin a timelog file like: - - export TIMELOG=$HOME/.timelog - ti ClientOne category - sleep 10 - to waited for ten seconds - - The `.timelog' file now contains: - - i 2004/10/06 15:21:00 ClientOne category - o 2004/10/06 15:21:10 waited for ten seconds - - Ledger parses this directly, as if it had seen the following entry: - - 2004/10/06 category - (ClientOne) 10s - - In other words, the timelog event pair is seen as adding 0.00277h -(ten seconds) worth of time to the `ClientOne' account. This would be -considered billable time, which later could be invoiced and credited to -accounts receivable: - - 2004/11/01 (INV#1) ClientOne, Inc. - Receivable:ClientOne $0.10 - ClientOne -0.00277h @ $35.00 - - The above transaction converts the clocked time into an invoice for -the time spent, at an hourly rate of $35. Once the invoice is paid, -the money is deposited from the receivable account into a checking -account: - - 2004/12/01 ClientOne, Inc. - Assets:Checking $0.10 - Receivable:ClientOne - - And now the time spent has been turned into hard cash in the checking -account. - - The advantage to using timeclock and invoicing to bill time is that -you will always know, by looking at the balance report, exactly how -much unbilled and unpaid time you've spent working for any particular -client. - - I like to `!include' my timelog at the top of my company's -accounting ledger, with the attached prefix `Billable': - - ; -*-ledger-*- - - ; This is the ledger file for my company. But first, include the - ; timelog data, entering all of the time events within the umbrella - ; account "Billable". - - !account Billable - !include /home/johnw/.timelog - !end - - ; Here follows this fiscal year's transactions for the company. - - 2004/11/01 (INV#1) ClientOne, Inc. - Receivable:ClientOne $0.10 - Billable:ClientOne -0.00277h @ $35.00 - - 2004/12/01 ClientOne, Inc. - Assets:Checking $0.10 - Receivable:ClientOne - - -File: ledger.info, Node: Using XML, Prev: Keeping a ledger, Up: Top - -4 Using XML -*********** - -By default, Ledger uses a human-readable data format, and displays its -reports in a manner meant to be read on screen. For the purpose of -writing tools which use Ledger, however, it is possible to read and -display data using XML. This chapter documents that format. - - The general format used for Ledger data is: - - <?xml version="1.0"?> - <ledger> - <entry>...</entry> - <entry>...</entry> - <entry>...</entry>... - </ledger> - - The data stream is enclosed in a `ledger' tag, which contains a -series of one or more entries. Each `entry' describes the entry and -contains a series of one or more transactions: - - <entry> - <en:date>2004/03/01</en:date> - <en:cleared/> - <en:code>100</en:code> - <en:payee>John Wiegley</en:payee> - <en:transactions> - <transaction>...</transaction> - <transaction>...</transaction> - <transaction>...</transaction>... - </en:transactions> - </entry> - - The date format for `en:date' is always `YYYY/MM/DD'. The -`en:cleared' tag is optional, and indicates whether the transaction has -been cleared or not. There is also an `en:pending' tag, for marking -pending transactions. The `en:code' and `en:payee' tags both contain -whatever text the user wishes. - - After the initial entry data, there must follow a set of transactions -marked with `en:transactions'. Typically these transactions will all -balance each other, but if not they will be automatically balanced into -an account named `<Unknown>'. - - Within the `en:transactions' tag is a series of one or more -`transaction''s, which have the following form: - - <transaction> - <tr:account>Expenses:Computer:Hardware</tr:account> - <tr:amount> - <value type="amount"> - <amount> - <commodity flags="PT">$</commodity> - <quantity>90.00</quantity> - </amount> - </value> - </tr:amount> - </transaction> - - This is a basic transaction. It may also be begin with `tr:virtual' -and/or `tr:generated' tags, to indicate virtual and auto-generated -transactions. Then follows the `tr:account' tag, which contains the -full name of the account the transaction is related to. Colons -separate parent from child in an account name. - - Lastly follows the amount of the transaction, indicated by -`tr:amount'. Within this tag is a `value' tag, of which there are four -different kinds, each with its own format: - - 1. boolean - - 2. integer - - 3. amount - - 4. balance - - The format of a boolean value is `true' or `false' surrounded by a -`boolean' tag, for example: - - <boolean>true</boolean> - - The format of an integer value is the numerical value surrounded by -an `integer' tag, for example: - - <integer>12036</integer> - - The format of an amount contains two members, the commodity and the -quantity. The commodity can have a set of flags that indicate how to -display it. The meaning of the flags (all of which are optional) are: - -*P* - The commodity is prefixed to the value. - -*S* - The commodity is separated from the value by a space. - -*T* - Thousands markers are used to display the amount. - -*E* - The format of the amount is European, with period used as a - thousands marker, and comma used as the decimal point. - - The actual quantity for an amount is an integer of arbitrary size. -Ledger uses the GNU multi-precision math library to handle such values. -The XML format assumes the reader to be equally capable. Here is an -example amount: - - <value type="amount"> - <amount> - <commodity flags="PT">$</commodity> - <quantity>90.00</quantity> - </amount> - </value> - - Lastly, a balance value contains a series of amounts, each with a -different commodity. Unlike the name, such a value does need to -balance. It is called a balance because it sums several amounts. For -example: - - <value type="balance"> - <balance> - <amount> - <commodity flags="PT">$</commodity> - <quantity>90.00</quantity> - </amount> - <amount> - <commodity flags="TE">DM</commodity> - <quantity>200.00</quantity> - </amount> - </balance> - </value> - - That is the extent of the XML data format used by Ledger. It will -output such data if the `xml' command is used, and can read the same -data as long as the `expat' library was available when Ledger was built. - - - -Tag Table: -Node: Top1762 -Node: Introduction3440 -Ref: Introduction-Footnote-19380 -Node: Building the program9457 -Node: Getting help10004 -Node: Running Ledger10414 -Node: Usage overview11934 -Ref: Usage overview-Footnote-145404 -Ref: Usage overview-Footnote-245522 -Node: Commands45627 -Node: Options50856 -Node: Basic options51717 -Node: Report filtering53902 -Node: Output customization57782 -Node: Commodity reporting62687 -Node: Environment variables64785 -Node: Format strings65433 -Node: Value expressions70805 -Node: Period expressions77136 -Node: File format78724 -Node: Some typical queries83592 -Node: Budgeting and forecasting87314 -Node: Keeping a ledger90054 -Node: Stating where money goes92763 -Node: Assets and Liabilities95416 -Node: Commodities and Currencies103561 -Node: Accounts and Inventories109722 -Node: Understanding Equity111317 -Node: Dealing with Petty Cash113224 -Node: Working with multiple funds and accounts114321 -Node: Archiving previous years119037 -Node: Virtual transactions121561 -Node: Automated transactions123237 -Node: Using Emacs to Keep Your Ledger126257 -Node: Using GnuCash to Keep Your Ledger129328 -Node: Using timeclock to record billable time130237 -Node: Using XML132997 - -End Tag Table |