diff options
| author | John Wiegley <johnw@newartisans.com> | 2007-04-30 06:26:38 +0000 |
|---|---|---|
| committer | John Wiegley <johnw@newartisans.com> | 2008-04-13 03:38:33 -0400 |
| commit | c8899addfd2deed3d84be2de234681db64987722 (patch) | |
| tree | 07f9a5eb603ff4ec83fe18c83083575d2b7a439a /docs | |
| parent | aa9cc125796711afcaa459898e95527fdae8e912 (diff) | |
| download | fork-ledger-c8899addfd2deed3d84be2de234681db64987722.tar.gz fork-ledger-c8899addfd2deed3d84be2de234681db64987722.tar.bz2 fork-ledger-c8899addfd2deed3d84be2de234681db64987722.zip | |
Rearranged the sources a bit.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Doxyfile | 275 | ||||
| -rw-r--r-- | docs/ledger.info | 3640 | ||||
| -rw-r--r-- | docs/ledger.texi | 3960 |
3 files changed, 7875 insertions, 0 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000..a03b54d4 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,275 @@ +# Doxyfile 1.5.1 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = Ledger +PROJECT_NUMBER = 3.0 +OUTPUT_DIRECTORY = %builddir%/docs +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +USE_WINDOWS_ENCODING = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = /Applications/Copied/ +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = %srcdir% +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py \ + *.C \ + *.CC \ + *.C++ \ + *.II \ + *.I++ \ + *.H \ + *.HH \ + *.H++ \ + *.CS \ + *.PHP \ + *.PHP3 \ + *.M \ + *.MM \ + *.PY +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = YES +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = usletter +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = YES +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = /Applications/Copied/Doxygen.app/Contents/Resources/dot +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 1024 +MAX_DOT_GRAPH_HEIGHT = 1024 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/docs/ledger.info b/docs/ledger.info new file mode 100644 index 00000000..651f5d91 --- /dev/null +++ b/docs/ledger.info @@ -0,0 +1,3640 @@ +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 diff --git a/docs/ledger.texi b/docs/ledger.texi new file mode 100644 index 00000000..bd42a3b0 --- /dev/null +++ b/docs/ledger.texi @@ -0,0 +1,3960 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ledger.info +@settitle Ledger: Command-Line Accounting + +@dircategory User Applications +@copying +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. +@end copying + +@documentencoding iso-8859-1 + +@iftex +@finalout +@end iftex + +@titlepage +@title Ledger: Command-Line Accounting +@author John Wiegley +@end titlepage + +@direntry +* Ledger: (ledger). Command Line Accounting +@end direntry + +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Overview + +@insertcopying +@end ifnottex + +@menu +* Introduction:: +* Running Ledger:: +* Keeping a ledger:: +* Using XML:: +@end menu + +@node Introduction, Running Ledger, Top, Top +@chapter Introduction + +Ledger is an accounting tool with the moxie to exist. It provides no +bells or whistles, and returns the user to the days before user +interfaces were even a twinkling in their father's CRT. + +What it does offer is a double-entry accounting ledger with all the +flexibility and muscle of its modern day cousins, without any of the +fat. Think of it as the Bran Muffin of accounting tools. + +To use it, you need to start keeping a ledger. This is the basis of +all accounting, and if you haven't started yet, now is the time to +learn. The little booklet that comes with your checkbook is a ledger, +so we'll describe double-entry accounting in terms of that. + +A checkbook ledger records debits (subtractions, or withdrawals) and +credits (additions, or deposits) with reference to a single account: +the checking account. Where the money comes from, and where it goes +to, are described in the payee field, where you write the person or +company's name. The ultimate aim of keeping a checkbook ledger is to +know how much money is available to spend. That's really the aim of +all ledgers. + +What computers add is the ability to walk through these transactions, +and tell you things about your spending habits; to let you devise +budgets and get control over your spending; to squirrel away money +into virtual savings account without having to physically move money +around; etc. As you keep your ledger, you are recording information +about your life and habits, and sometimes that information can start +telling you things you aren't aware of. Such is the aim of all good +accounting tools. + +The next step up from a checkbook ledger, is a ledger that keeps track +of all your accounts, not just checking. In such a ledger, you record +not only who gets paid---in the case of a debit---but where the money +came from. In a checkbook ledger, its assumed that all the money +comes from your checking account. But in a general ledger, you write +transaction two-lines: the source account and target account. +@emph{There must always be a debit from at least one account for every +credit made to another account}. This is what is meant by +``double-entry'' accounting: the ledger must always balance to zero, +with an equal number of debits and credits. + +For example, let's say you have a checking account and a brokerage +account, and you can write checks from both of them. Rather than keep +two checkbooks, you decide to use one ledger for both. In this +general ledger you need to record a payment to Pacific Bell for your +monthly phone bill. The cost is $23.00, let's say, and you want to +pay it from your checking account. In the general ledger you need to +say where the money came from, in addition to where it's going to. +The entry might look like this: + +@smallexample +9/29 BAL Pacific Bell $-200.00 $-200.00 + Equity:Opening Balances $200.00 +9/29 BAL Checking $100.00 $100.00 + Equity:Opening Balances $-100.00 +9/29 100 Pacific Bell $23.00 $223.00 + Checking $-23.00 $77.00 +@end smallexample + +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.@footnote{In some +special cases, it automatically balances this entry for you.} + +In summary, there are two aspects of Ledger use: updating the ledger +data file, and using the Ledger tool to view the summarized result of +your entries. + +And just for the sake of example---as a starting point for those who +want to dive in head-first---here are the ledger entries from above, +formatting as the ledger program wishes to see them: + +@smallexample +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 +@end smallexample + +The account balances and registers in this file, if saved as +@file{ledger.dat}, could be reported using: + +@example +$ ledger -f ledger.dat balance +$ ledger -f ledger.dat register checking +$ ledger -f ledger.dat register bell +@end example + +@menu +* Building the program:: +* Getting help:: +@end menu + +@node Building the program, Getting help, Introduction, Introduction +@section 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: + +@example +./configure && make install +@end example + +@node Getting help, , Building the program, Introduction +@section 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: + +@example +https://lists.sourceforge.net/lists/listinfo/ledger-discuss +@end example + +You can also find help at the @samp{#ledger} channel on the IRC server +@samp{irc.freenode.net}. + +@node Running Ledger, Keeping a ledger, Introduction, Top +@chapter Running Ledger + +Ledger has a very simple command-line interface, named---enticing +enough---@command{ledger}. It supports a few reporting commands, and +a large number of options for refining the output from those commands. +The basic syntax of any ledger command is: + +@example +ledger [OPTIONS...] COMMAND [ARGS...] +@end example + +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 @command{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 @samp{--}. For example, the +following balance command reports account totals for rent, food and +movies, but only those whose payee matches Freddie: + +@example +ledger bal rent food movies -- freddie +@end example + +There are many, many command options available with the +@command{ledger} command, and it takes a while to master them. +However, none of them are required to use the basic reporting +commands. + +@menu +* Usage overview:: +* Commands:: +* Options:: +* Format strings:: +* Value expressions:: +* Period expressions:: +* File format:: +* Some typical queries:: +* Budgeting and forecasting:: +@end menu + +@node Usage overview, Commands, Running Ledger, Running Ledger +@section Usage overview + +Before getting into the details of how to run Ledger, it will be +easier to introduce the features in the context of their typical +usage. To that end, this section presents a series of recipes, +gradually introducing all of the command-line features of Ledger. + +For the purpose of these examples, assume the environment variable +@var{LEDGER} is set to the file @file{sample.dat} (which is included +in the distribution), and that the contents of that file are: + +@smallexample += /^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 +@end smallexample + +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. + +@subsection Checking balances + +Ledger has seven basic commands, but by far the most often used are +@command{balance} and @command{register}. To see a summary balance of +all accounts, use: + +@example +ledger bal +@end example + +@command{bal} is a short-hand for @command{balance}. This command +prints out the summary totals of the five parent accounts used in +@file{sample.dat}: + +@smallexample + $1,480.00 + 50 AAPL Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income + $-2.00 Liabilities +-------------------- + $-1,502.00 + 50 AAPL +@end smallexample + +None of the child accounts are shown, just the parent account totals. +We can see that in @samp{Assets} there is $1,480.00, and 50 shares of +Apple stock. There is also a negative grand total. Usually the grand +total is zero, which means that all accounts balance@footnote{It is +impossible for accounts not to balance in ledger; it reports an error +if a transaction does not balance}. In this case, since the 50 shares +of Apple stock cost $1,500.00 dollars, then these two amounts balance +each other in the grand total. The extra $2.00 comes from a virtual +transaction being added by the automatic entry at the top of the file. +The entry is virtual because the account name was surrounded by +parentheses in an automatic entry. Automatic entries will be +discussed later, but first let's remove the virtual transaction from +the balance report by using the @option{--real} option: + +@example +ledger --real bal +@end example + +Now the report is: + +@smallexample + $1,480.00 + 50 AAPL Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income +-------------------- + $-1,500.00 + 50 AAPL +@end smallexample + +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 @file{sample.dat} is quite +simple, and we happen to know that the 50 shares of Apple stock cost +$1,500.00. We can verify that things really balance by reporting the +Apple shares in terms of their cost, instead of their quantity. To do +this requires the @option{--basis}, or @option{-B}, option: + +@example +ledger --real -B bal +@end example + +This command reports: + +@smallexample + $2,980.00 Assets + $-2,500.00 Equity + $20.00 Expenses + $-500.00 Income +@end smallexample + +With the basis cost option, the grand total has disappeared, as it is +now zero. The confirms that the cost of everything balances to zero, +@emph{which must always be true}. Reporting the real basis cost +should never yield a remainder@footnote{If it ever does, then +generated transactions are involved, which can be removed using +@option{--actual}}. + +@subsubsection 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 +@option{-s} option: + +@example +ledger --real -B -s bal +@end example + +This reports: + +@smallexample + $2,980.00 Assets + $1,480.00 Bank:Checking + $1,500.00 Brokerage + $-2,500.00 Equity:Opening Balances + $20.00 Expenses:Books + $-500.00 Income:Salary +@end smallexample + +This shows that the @samp{Assets} total is made up from two child +account, but that the total for each of the other accounts comes from +one child account. + +Sometimes you may have a lot of children, nested very deeply, but only +want to report the first two levels. This can be done with a display +predicate, using a value expression. In the value expression, +@code{T} represents the reported total, and @code{l} is the display +level for the account: + +@example +ledger --real -B -d "T&l<=2" bal +@end example + +This reports: + +@smallexample + $2,980.00 Assets + $1,480.00 Bank + $1,500.00 Brokerage + $-2,500.00 Equity:Opening Balances + $20.00 Expenses:Books + $-500.00 Income:Salary +@end smallexample + +Instead of reporting @samp{Bank:Checking} as a child of @samp{Assets}, +it report only @samp{Bank}, since that account is a nesting level of +2, while @samp{Checking} is at level 3. + +To review the display predicate used---@code{T&l<=2}---this rather +terse expression means: Display an account only if it has a non-zero +total (@code{T}), and its nesting level is less than or equal to 2 +(@code{l<=2}). + +@subsubsection 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: + +@example +ledger bal checking +@end example + +Reports: + +@smallexample + $1,480.00 Assets:Bank:Checking +@end smallexample + +Any number of names may be used: + +@example +ledger bal checking broker liab +@end example + +Reports: + +@smallexample + $1,480.00 Assets:Bank:Checking + 50 AAPL Assets:Brokerage + $-2.00 Liabilities +@end smallexample + +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: + +@example +ledger bal ^assets.*checking ^liab +@end example + +Reports: + +@smallexample + $1,480.00 Assets:Bank:Checking + $-2.00 Liabilities:Taxes +@end smallexample + +@subsection The register report + +While the @command{balance} command can be very handy for checking +account totals, by far the most powerful of Ledger's reporting tools +is the @command{register} command. In fact, internally both commands +use the same logic, but report the results differently: +@command{balance} shows the summary totals, while @command{register} +reports each transaction and how it contributes to that total. + +Paradoxically, the most basic form of @command{register} is almost +never used, since it displays every transaction: + +@example +ledger reg +@end example + +@command{reg} is a short-hand for @command{register}. This command +reports: + +@smallexample +2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + Equity:Opening Balan.. $-1,000.00 0 +2004/05/01 Investment balance Assets:Brokerage 50 AAPL 50 AAPL + Equity:Opening Balan.. $-1,500.00 $-1,500.00 + 50 AAPL +2004/05/14 Pay day Assets:Bank:Checking $500.00 $-1,000.00 + 50 AAPL + Income:Salary $-500.00 $-1,500.00 + 50 AAPL +2004/05/27 Book Store Expenses:Books $20.00 $-1,480.00 + 50 AAPL + Liabilities:MasterCard $-20.00 $-1,500.00 + 50 AAPL + (Liabilities:Taxes) $-2.00 $-1,502.00 + 50 AAPL +2004/05/27 Credit card company Liabilities:MasterCard $20.00 $-1,482.00 + 50 AAPL + Assets:Bank:Checking $-20.00 $-1,502.00 + 50 AAPL +@end smallexample + +This rather verbose output shows every account transaction in +@file{sample.dat}, and how it affects the running total. The final +total is identical to what we saw with the plain @command{balance} +command. To see how things really balance, we can use @samp{--real +-B}, just as we did with @command{balance}: + +@example +ledger --real -B reg +@end example + +Reports: + +@smallexample +2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 + Equity:Opening Balan.. $-1,000.00 0 +2004/05/01 Investment balance Assets:Brokerage $1,500.00 $1,500.00 + Equity:Opening Balan.. $-1,500.00 0 +2004/05/14 Pay day Assets:Bank:Checking $500.00 $500.00 + Income:Salary $-500.00 0 +2004/05/27 Book Store Expenses:Books $20.00 $20.00 + Liabilities:MasterCard $-20.00 0 +2004/05/27 Credit card company Liabilities:MasterCard $20.00 $20.00 + Assets:Bank:Checking $-20.00 0 +@end smallexample + +Here we see that everything balances to zero in the end, as it must. + +@subsubsection Specific register queries + +The most common use of the register command is to summarize +transactions based on the account(s) they affect. Using +@file{sample.dat} as as example, we could look at all book purchases +using: + +@example +ledger reg books +@end example + +Reports: + +@smallexample +2004/05/29 Book Store Expenses:Books $20.00 $20.00 +@end smallexample + +If a double-dash (@samp{--}) occurs in the list of regular +expressions, any following arguments are matched against payee names, +instead of account names: + +@example +ledger reg ^liab -- credit +@end example + +Reports: + +@smallexample +2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00 +@end smallexample + +There are many reporting options for tailoring which transactions are +found, and also how to summarize the various amounts and totals that +result. These are plumbed in greater depth below. + +@subsection 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 @option{--help-calc}. + +@subsubsection By date + +@c -c, --current show only current and past entries (not future) + +@option{--current}(@option{-c}) displays entries occurring on or +before the current date. Any entry recorded for a future date will be +ignored, as if it had not been seen. This is useful if you happen to +pre-record entries, but still wish to view your balances in terms of +what is available today. + +@c -b, --begin DATE set report begin date +@c -e, --end DATE set report end date + +@option{--begin DATE} (@option{-b DATE}) limits the report to only +those entries occurring on or after @var{DATE}. The running total in +the register will start at zero with the first transaction, even if +there are earlier entries. + +To limit the display only, but still add earlier transactions to the +running total, use the display expression @samp{-d 'd>=[DATE]'}): + +@example +ledger --basis -b may -d 'd>=[5/14]' reg ^assets +@end example + +Reports: + +@smallexample +2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 +2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 +@end smallexample + +In this example, the displayed transactions start from @samp{5/14}, +but the calculated total starts from the beginning of @samp{may}. + +@option{--end DATE} (@option{-e DATE}) states when reporting should +end, both calculation and display. The ending date is inclusive. + +The @var{DATE} argument to the @option{-b} and @option{-e} options can +be rather flexible. Assuming the current date to be November 15, +2004, then all of the following are equivalent: + +@example +ledger -b oct bal +ledger -b "this oct" bal +ledger -b 2004/10 bal +ledger -b 10 bal +ledger -b last bal +ledger -b "last month" bal +@end example + +@c -p, --period STR report using the given period +@c --period-sort EXPR sort each report period's entries by EXPR + +To constrain the report to a specific time period, use +@option{--period} (@option{-p}). A time period may have both a +beginning and an end, or neither, as well as a specified interval. +Here are a few examples: + +@example +ledger -p 2004 bal +ledger -p august bal +ledger -p "from aug to oct" bal +ledger -p "daily from 8/1 to 8/15" bal +ledger -p "weekly since august" bal +ledger -p "monthly from feb to oct" bal +ledger -p "quarterly in 2004" bal +ledger -p yearly bal +@end example + +See @ref{Period expressions} for more on syntax. Also, all of the +options @option{-b}, @option{-e} and @option{-p} may be used together, +but whatever information occurs last takes priority. An example of +such usage (in a script, perhaps) would be: + +@example +ledger -b 2004 -e 2005 -p monthly reg ^expenses +@end example + +This command is identical to: + +@example +ledger -p "monthly in 2004" reg ^expenses +@end example + +The transactions within a period may be sorted using +@option{--period-sort}, which takes a value expression. This is +similar to the @option{--sort} option, except that it sorts within +each period entry, rather than sorting all transactions in the report. +See the documentation on @option{--sort} below for more details. + +@subsubsection 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: + +@table @option +@item -C, --cleared +Consider only cleared transactions. +@item -U, --uncleared +Consider only uncleared and pending transactions. +@item -R, --real +Consider only real (non-virtual) transactions. +@item -L, --actual +Consider only actual (non-automated) transactions. +@end table + +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: + +@example +ledger --budget --actual reg ^expenses +@end example + +This command outputs all transactions affecting a budgeted account, +but without subtracting the budget amount (because the generated +transactions are suppressed with @option{--actual}). The report shows +how much you actually spent on budgeted items. + +@subsubsection By relationship + +@c -r, --related calculate report using related transactions + +Normally, a register report includes only the transactions that match +the regular expressions specified after the command word. For +example, to report all expenses: + +@example +ledger reg ^expenses +@end example + +This reports: + +@smallexample +2004/05/29 Book Store Expenses:Books $20.00 $20.00 +@end smallexample + +Using @option{--related} (@option{-r}) reports the transactions that +did not match your query, but only in entries that otherwise would +have matched. This has the effect of indicating where money came +from, or when to: + +@example +ledger -r reg ^expenses +@end example + +Reports: + +@smallexample +2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00 +@end smallexample + +@subsubsection By budget + +@c --budget generate budget entries based on FILE + +There is more information about budgeting and forecasting in +@ref{Budgeting and forecasting}. Basically, if you have any period +entries in your ledger file, you can use these options. A period +entry looks like: + +@example +~ Monthly + Assets:Bank:Checking $500.00 + Income:Salary +@end example + +The difference from a regular entry is that the first line begins with +a tilde (~), and instead of a payee there's a period expression +(@ref{Period expressions}). Otherwise, a period entry is in every +other way the same as a regular entry. + +With such an entry in your ledger file, the @option{--budget} option +will report only transactions that match a budgeted account. Using +@file{sample.dat} from above: + +@example +ledger --budget reg ^income +@end example + +Reports: + +@smallexample +2004/05/01 Budget entry Income:Salary $500.00 $500.00 +2004/05/14 Pay day Income:Salary $-500.00 0 +@end smallexample + +The final total is zero, indicating that the budget matched exactly +for the reported period. Budgeting is most often helpful with period +reporting; for example, to show monthly budget results use +@option{--budget -p monthly}. + +@c --add-budget show all transactions plus the budget +@c --unbudgeted show only unbudgeted transactions + +The @option{--add-budget} option reports all matching transactions in +addition to budget transactions; while @option{--unbudgeted} shows +only those that don't match a budgeted account. To summarize: + +@table @option +@item --budget +Show transactions matching budgeted accounts. +@item --unbudgeted +Show transactions matching unbudgeted accounts. +@item --add-budget +Show both budgeted and unbudgeted transactions together (i.e., add the +generated budget transactions to the regular report). +@end table + +@c --forecast EXPR generate forecast entries while EXPR is true + +A report with the @option{--forecast} option will add budgeted +transactions while the specified value expression is true. For +example: + +@example +ledger --forecast 'd<[2005] reg ^income +@end example + +Reports: + +@smallexample +2004/05/14 Pay day Income:Salary $-500.00 $-500.00 +2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00 +2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00 +@end smallexample + +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: + +@example +ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp +@end example + +This reports balances projected income against projected expenses, +showing the resulting total in yearly intervals until 2008. For the +case of @file{sample.dat}, which has no budgeted expenses, the result +of the above command (in November 2004) is: + +@smallexample +2004/01/01 - 2004/12/31 Income:Salary $-1,000.00 $-1,000.00 + Expenses:Books $20.00 $-980.00 +2005/01/01 - 2005/12/31 Income:Salary $-6,000.00 $-6,980.00 +2006/01/01 - 2006/12/31 Income:Salary $-6,000.00 $-12,980.00 +2007/01/01 - 2007/12/31 Income:Salary $-6,000.00 $-18,980.00 +2008/01/01 - 2008/01/01 Income:Salary $-500.00 $-19,480.00 +@end smallexample + +@subsubsection By value expression + +@c -l, --limit EXPR calculate only transactions matching EXPR + +Value expressions can be quite complex, and are treated more fully in +@ref{Value expressions}. They can be used for limiting a report with +@option{--limit} (@option{-l}). The following command report income +since august, but expenses since october: + +@example +ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg +@end example + +The basic form of this value expression is @samp{(A&B)|(A&B)}. The +@samp{A} in each part matches against an account name with +@samp{/name/}, while each @samp{B} part compares the date of the +transaction (@samp{d}) with a specified month. The resulting report +will contain only transactions which match the value expression. + +@c -t, --amount EXPR use EXPR to calculate the displayed amount +@c -T, --total EXPR use EXPR to calculate the displayed total + +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: + +@example +ledger -t 'a/2' reg ^exp +@end example + +The @option{-t} option doesn't affect the running total, only how the +transaction amount is displayed. To change the running total, use +@option{-T}. In that case, you will likely want to use the total +(@samp{O}) instead of the amount (@samp{a}): + +@example +ledger -T 'O/2' reg ^exp +@end example + +@subsection Massaging register output + +Even after filtering down your data to just the transactions you're +interested in, the default reporting method of one transaction per +line is often still too much. To combat this complexity, it is +possible to ask Ledger to report the details to you in many different +forms, summarized in various ways. This is the ``display'' phase of +Ledger, and is documented under @option{--help-disp}. + +@subsubsection Summarizing + +@c -n, --collapse register: collapse entries with multiple transactions + +When multiple transactions relate to a single entry, they are reported +as part of that entry. For example, in the case of @file{sample.dat}: + +@example +ledger reg -- book +@end example + +Reports: + +@smallexample +2004/05/29 Book Store Expenses:Books $20.00 $20.00 + Liabilities:MasterCard $-20.00 0 + (Liabilities:Taxes) $-2.00 $-2.00 +@end smallexample + +All three transactions are part of one entry, and as such the entry +details are printed only once. To report every entry on a single +line, use @option{-n} to collapse entries with multiple transactions: + +@example +ledger -n reg -- book +@end example + +Reports: + +@smallexample +2004/05/29 Book Store <Total> $-2.00 $-2.00 +@end smallexample + +In the balance report, @option{-n} causes the grand total not to be +displayed at the bottom of the report. + +@c -s, --subtotal balance: show sub-accounts; other: show subtotals + +If an account occurs more than once in a report, it is possible to +combine them all and report the total per-account, using @option{-s}. +For example, this command: + +@example +ledger -B reg ^assets +@end example + +Reports: + +@smallexample +2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00 +2004/05/01 Investment balance Assets:Brokerage $1,500.00 $2,500.00 +2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00 +2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00 +@end smallexample + +But if the @option{-s} option is added, the result becomes: + +@smallexample +2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00 + Assets:Brokerage $1,500.00 $2,980.00 +@end smallexample + +When account subtotaling is used, only one entry is printed, and the +date and name reflect the range of the combined transactions. + +@c -P, --by-payee show summarized totals by payee + +With @option{-P}, transactions relating to the same payee are +combined. In this case, the date of the combined entry is that of the +latest transaction. + +@c -x, --comm-as-payee set commodity name as the payee, for reporting + +@option{-x} changes the payee name for each transaction to be the same +as the commodity it uses. This can be especially useful combined with +other options, like @option{-P}. For example: + +@example +ledger -Px reg ^assets +@end example + +Reports: + +@smallexample +2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 +2004/05/01 AAPL Assets:Brokerage 50 AAPL $1,480.00 + 50 AAPL +@end smallexample + +This reports shows the subtotal for each commodity held, and where it +is located. To see the basis cost, or initial investment, add +@option{-B}. Applied to the example above: + +@smallexample +2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 +2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00 +@end smallexample + +@c -E, --empty balance: show accounts with zero balance + +The only other options which affect summarized totals is @option{-E}, +which works only in the balance report. In this case, it shows +matching accounts with a zero a balance, which are ordinarily +excluded. This can be useful to see all the accounts involved in a +report, even if some have no total. + +@subsubsection Quick periods + +Although the @option{-p} option (also @option{--period}) is much more +versatile, there are other options to make the most common period +reports easier: + +@table @option +@item -W, --weekly +Show weekly sub-totals. Same as @samp{-p weekly}. +@item -M, --monthly +Show monthly sub-totals. Same as @samp{-p monthly}. +@item -Y, --yearly +Show yearly sub-totals. Same as @samp{-p yearly}. +@end table + +@c --dow show a days-of-the-week report + +There is one kind of period report cannot be done with @option{-p}. +This is the @option{--dow}, or ``days of the week'' report, which +shows summarized totals for each day of the week. The following +examples shows a ``day of the week'' report of income and expenses: + +@example +ledger --dow reg ^inc ^exp +@end example + +Reports: + +@smallexample +2004/05/27 Thursdays Expenses:Books $20.00 $20.00 +2004/05/14 Fridays Income:Salary $-500.00 $-480.00 +@end smallexample + +@subsubsection Ordering and width + +@c -S, --sort EXPR sort report according to the value expression EXPR + +The transactions displayed in a report are shown in the same order as +they appear in the ledger file. To change the order and sort a +report, use the @option{--sort} option. @option{--sort} takes a value +expression to determine the value to sort against, making it possible +to sort according to complex criteria. Here are some simple and +useful examples: + +@example +ledger --sort d reg ^exp # sort by date +ledger --sort t reg ^exp # sort by amount total +ledger --sort -t reg ^exp # reverse sort by amount total +ledger --sort Ut reg ^exp # sort by abs amount total +@end example + +For the balance report, you will want to use @samp{T} instead of +@samp{t}: + +@example +ledger --sort T reg ^exp # sort by amount total +ledger --sort -T reg ^exp # reverse sort by amount total +ledger --sort UT reg ^exp # sort by abs amount total +@end example + +The @option{--sort} options sorts all transactions in a report. If +periods are used (such as @option{--monthly}), this can get somewhat +confusing. In that case, you'll probably want to sort within periods +using @option{--period-sort} instead of @option{--sort}. + +@c -w, --wide for the default register report, use 132 columns + +And if the register seems too cramped, and you have a lot of screen +real estate, you can use @option{-w} to format the report within 132 +acolumns, instead of 80. You are more likely then to see full payee +and account names, as well as properly formatted totals when +long-named commodities are used. + +If you want only the first or last N entries to be printed---which can +be very useful for viewing the last 10 entries in your checking +account, while also showing the cumulative balance from all +entries---use the @option{--head} and/or @option{--tail} options. The +two options may be used simultaneously, for example: + +@example +ledger --tail 20 reg checking +@end example + +If the output from your command is very long, Ledger can output the +data to a pager utility, such as @command{more} or @command{less}: + +@example +ledger --pager /usr/bin/less reg checking +@end example + +@subsubsection Averages and percentages + +@c -A, --average report average transaction amount + +To see the running total changed to a running average, use +@option{-A}. The final transaction's total will be the overall +average of all displayed transactions. The works in conjunction with +period reporting, so that you can see your monthly average expenses +with: + +@example +ledger -AM reg ^expenses:food +ledger -AMn reg ^expenses +@end example + +This works in the balance report too: + +@example +ledger -AM bal ^expenses:food +ledger -AMs bal ^expenses +@end example + +@c -D, --deviation report deviation from the average + +The @option{-D} option changes the running average into a deviation +from the running average. This only makes sense in the register +report, however. + +@example +ledger -DM reg ^expenses:food +@end example + +@c -%, --percentage report balance totals as a percentile of the parent + +In the balance report only, @option{-%} changes the reported totals +into a percentage of the parent account. This kind of report is +confusing if negative amounts are involved, and doesn't work at all if +multiple commodities occur in an account's history. It has a somewhat +limited usefulness, therefore, but in certain cases it can be handy, +such as reviewing overall expenses: + +@example +ledger -%s -S T bal ^expenses +@end example + +@subsubsection Reporting total data + +@c --totals in the "xml" report, include running total + +Normally in the @command{xml} report, only transaction amounts are +printed. To include the running total under a @samp{<total>} tag, use +@option{--totals}. This does not affect any other report. + +@c -j, --amount-data print only raw amount data (useful for scripting) +@c -J, --total-data print only raw total data + +In the register report only, the output can be changed with +@option{-j} to show only the date and the amount---without +commodities. This only makes sense if a single commodity appears in +the report, but can be quite useful for scripting, or passing the data +to Gnuplot. To show only the date and running total, use @option{-J}. + +@subsubsection Display by value expression + +@c -d, --display EXPR display only transactions matching EXPR + +With @option{-d} you can decide which transactions (or accounts in the +balance report) are displayed, according to a value expression. The +computed total is not affected, only the display. This can be very +useful for shortening a report without changing the running total: + +@example +ledger -d 'd>=[last month]' reg checking +@end example + +This command shows the checking account's register, beginning from +last month, but with the running total reflecting the entire history +of the account. + +@subsubsection Change report format + +@c -y, --date-format STR use STR as the date format (default: %Y/%m/%d) + +When dates are printed in any report, the default format is +@samp{%Y/%m/%d}, which yields dates of the form @samp{YYYY/mm/dd}. +This can be changed with @option{-y}, whose argument is a +@code{strftime} string---see your system's C library documentation for +the allowable codes. Mostly you will want to use @samp{%Y}, @samp{%m} +and @samp{%d}, in whatever combination is convenient for your locale. + +@c -F, --format STR use STR as the format; for each report type, use: +@c --balance-format --register-format --print-format +@c --plot-amount-format --plot-total-format --equity-format +@c --prices-format --wide-register-format + +To change the format of the entire reported line, use @option{-F}. It +supports quite a large number of options, which are all documented in +@ref{Format strings}. In addition, each specific kind of report +(except for @command{xml}) can be changed using one of the following +options: + +@table @option +@item --balance-format +@command{balance} report. Default: +@smallexample +%20T %2_%-a\n +@end smallexample + +@item --register-format +@command{register} report. Default: +@smallexample +%D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n +@end smallexample + +@item --print-format +@command{print} report. Default: +@smallexample +%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n +@end smallexample + +@item --plot-amount-format +@command{register} report when @option{-j} (plot amount) is used. Default: +@smallexample +%D %(St)\n +@end smallexample + +@item --plot-total-format +@command{register} report when @option{-J} (plot total) is used. Default: +@smallexample +%D %(ST)\n +@end smallexample + +@item --equity-format +@command{equity} report. Default: +@smallexample +\n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n +@end smallexample + +@item --prices-format +@command{prices} report. Default: +@smallexample +\n%D %Y%C%P\n%/ %-34W %12t\n +@end smallexample + +@item --wide-register-format +@command{register} report when @option{-w} (wide) is used. Default: +@smallexample +%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n +@end smallexample +@end table + +@subsection Standard queries + +If your ledger file uses the standard top-level accounts: Assets, +Liabilities, Income, Expenses, Equity: then the following queries will +enable you to generate some typical accounting reports from your data. + +Your @emph{net worth} can be determined by balancing assets against +liabilities: + +@example +ledger bal ^assets ^liab +@end example + +By removing long-term investment and loan accounts, you can see your +current net liquidity (or liquid net worth): + +@example +ledger bal ^assets ^liab -retirement -brokerage -loan +@end example + +Balancing expenses against income yields your @emph{cash flow}, or net +profit/loss: + +@example +ledger bal ^exp ^inc +@end example + +In this case, if the number is positive it means you spent more than +you earned during the report period. + +@c ---------------------------------------------------------------------- + +The most often used command is the ``balance'' command: + +@example +export LEDGER=/home/johnw/doc/ledger.dat +ledger balance +@end example + +Here I've set my Ledger environment variable to point to where my +ledger file is hiding. Thereafter, I needn't specify it again. + +@subsection Reporting balance totals + +The balance command prints out the summarized balances of all my +top-level accounts, excluding sub-accounts. In order to see the +balances for a specific account, just specify a regular expression +after the balance command: + +@example +ledger balance expenses:food +@end example + +This will show all the money that's been spent on food, since the +beginning of the ledger. For food spending just this month +(September), use: + +@example +ledger -p sep balance expenses:food +@end example + +Or maybe you want to see all of your assets, in which case the -s +(show sub-accounts) option comes in handy: + +@example +ledger -s balance ^assets +@end example + +To exclude a particular account, use a regular expression with a +leading minus sign. The following will show all expenses, but without +food spending: + +@example +ledger balance expenses -food +@end example + +@subsection Reporting percentages + +There is no built-in way to report transaction amounts or account +balances in terms of percentages + +@node Commands, Options, Usage overview, Running Ledger +@section Commands + +@subsection balance + +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. + +@subsection register + +The @command{register} command displays all the transactions occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +transactions that match. Very useful for hunting down a particular +transaction. + +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +always be the same as the current balance of that account. + +If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script @file{report}, which is +included in the Ledger distribution. The only requirement is that you +add either @option{-j} or @option{-J} to your register command, in +order to plot either the amount or total column, respectively. + +@subsection print + +The @command{print} command prints out ledger entries in a textual +format that can be parsed by Ledger. They will be properly formatted, +and output in the most economic form possible. The ``print'' command +also takes a list of optional regexps, which will cause only those +transactions which match in some way to be printed. + +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. + +@subsection output + +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: + +@example +ledger -f FILENAME output FILENAME +@end example + +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only entries contained +within that file will be output, and not an included entries (as can +happen with the @command{print} command). + +@subsection xml + +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +transaction. + +@subsection emacs + +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: + +@example +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of transactions + ...) ; list of entries +@end example + +@subsection equity + +The @command{equity} command prints out accounts balances as if they +were entries. This makes it easy to establish the starting balances +for an account, such as when @ref{Archiving previous years}. + +@subsection prices + +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +deviation from that average. + +There is also a @command{pricesdb} command which outputs the same +information as @command{prices}, but does in a format that can be +parsed by Ledger. + +@subsection entry + +The @command{entry} commands simplifies the creation of new entries. +It works on the principle that 80% of all transactions are variants of +earlier transactions. Here's how it works: + +Say you currently have this transaction in your ledger file: + +@smallexample +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample + +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{entry} command you can type: + +@example +ledger entry 2004/4/9 viva food 11 tips 2.50 +@end example + +This produces the following output: + +@smallexample +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end smallexample + +It works by finding a past transaction matching the regular expression +@samp{viva}, and assuming that any accounts or amounts specified will +be similar to that earlier transaction. If Ledger does not succeed in +generating a new entry, an error is printed and the exit code is set +to @samp{1}. + +There is a shell script in the distribution's @file{scripts} directory +called @file{entry}, which simplifies the task of adding a new entry +to your ledger. It launches @command{vi} to confirm that the entry +looks appropriate. + +Here are a few more examples of the @command{entry} command, assuming +the above journal entry: + +@example +ledger entry 4/9 viva 11.50 +ledger entry 4/9 viva 11.50 checking # (from `checking') +ledger entry 4/9 viva food 11.50 tips 8 +ledger entry 4/9 viva food 11.50 tips 8 cash +ledger entry 4/9 viva food $11.50 tips $8 cash +ledger entry 4/9 viva dining "DM 11.50" +@end example + +@node Options, Format strings, Commands, Running Ledger +@section 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: + +@example +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +@end example + +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. + +@menu +* Basic options:: +* Report filtering:: +* Output customization:: +* Commodity reporting:: +* Environment variables:: +@end menu + +@node Basic options, Report filtering, Options, Options +@subsection Basic options + +These are the most basic command options. Most likely, the user will +want to set them using @ref{Environment variables}, instead of using +actual command-line options: + +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. + +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. + +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. FILE may also be a list of +file names separated by colons. Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. + +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. + +@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by +ledger before any other ledger file. This file may not contain any +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: + +@smallexample +--price-db ~/finance/.pricedb + +; ~/.ledgerrc ends here +@end smallexample + +Option settings on the command-line or in the environment always take +precedence over settings in the init file. + +@option{--cache FILE} identifies FILE as the default binary cache +file. That is, if the ledger files to be read are specified using the +environment variable @env{LEDGER_FILE}, then whenever a command is +finished a binary copy will be written to the specified cache, to +speed up the loading time of subsequent queries. This filename can +also be given using the environment variable @env{LEDGER_CACHE}, or by +putting the option into your init file. The @option{--no-cache} +option causes Ledger to always ignore the binary cache. + +@option{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file transactions are assumed to relate to. + +@node Report filtering, Output customization, Basic options, Options +@subsection Report filtering + +These options change which transactions affect the outcome of a +report, in ways other than just using regular expressions: + +@option{--current}(@option{-c}) displays only entries occurring on or +before the current date. + +@option{--begin DATE} (@option{-b DATE}) constrains the report to +entries on or after @var{DATE}. Only entries after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching entry. (Note: This +is different from using @option{--display} to constrain what is +displayed). + +@option{--end DATE} (@option{-e DATE}) constrains the report so that +entries on or after @var{DATE} are not considered. The ending date +is inclusive. + +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching entries within each +period separately, making it easy to see weekly, monthly, quarterly, +etc., transaction totals. A period string can even specify the +beginning and end of the report range, using simple terms like ``last +june'' or ``next month''. For more using period expressions, see +@ref{Period expressions}. + +@option{--period-sort EXPR} sorts the transactions within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: + +@example +ledger -M --period-sort -At reg ^Expenses +@end example + +@option{--cleared} (@option{-C}) displays only transactions whose entry +has been marked ``cleared'' (by placing an asterix to the right of the +date). + +@option{--uncleared} (@option{-U}) displays only transactions whose +entry has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). + +@option{--real} (@option{-R}) displays only real transactions, not +virtual. (A virtual transaction is indicated by surrounding the +account name with parentheses or brackets; see the section on using +virtual transactions for more information). + +@option{--actual} (@option{-L}) displays only actual transactions, and +not those created due to automated transactions. + +@option{--related} (@option{-r}) displays transactions that are +related to whichever transactions would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by entries having a related transaction. +For example, if a file had this entry: + +@smallexample +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 +@end smallexample + +And the register command was: + +@example +ledger -r register food +@end example + +The following would be output, showing the transactions related to the +transaction that matched: + +@smallexample +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 +@end smallexample + +@option{--budget} is useful for displaying how close your transactions +meet your budget. @option{--add-budget} also shows unbudgeted +transactions, while @option{--unbudgeted} shows only those. +@option{--forecast} is a related option that projects your budget into +the future, showing how it will affect future balances. +@xref{Budgeting and forecasting}. + +@option{--limit EXPR} (@option{-l EXPR}) limits which transactions +take part in the calculations of a report. + +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +used to calculate the ``value'' column in the @command{register} +report, the amount used to calculate account totals in the +@command{balance} report, and the values printed in the +@command{equity} report. @xref{Value expressions}. + +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. + +@node Output customization, Commodity reporting, Report filtering, Options +@subsection Output customization + +These options affect only the output, but not which transactions are +used to create it: + +@option{--collapse} (@option{-n}) causes entries in a +@command{register} report with multiple transactions to be collapsed +into a single, subtotaled entry. + +@option{--subtotal} (@option{-s}) causes all entries in a +@command{register} report to be collapsed into a single, subtotaled +entry. + +@option{--by-payee} (@option{-P}) reports subtotals by payee. + +@option{--comm-as-payee} (@option{-x}) changes the payee of every +transaction to be the commodity used in that transaction. This can be +useful when combined with other options, such as @option{-s}. + +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. + +@option{--weekly} (@option{-W}) reports transaction totals by the +week. The week begins on whichever day of the week begins the month +containing that transaction. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports transaction totals by month; @option{--yearly} +(@option{-Y}) reports transaction totals by year. For more complex +period, using the @option{--period} option described above. + +@option{--dow} reports transactions totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. + +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +the values determined using the value expression @var{EXPR}. For +example, using @option{-S -UT} in the balance report will sort account +balances from greatest to least, using the absolute value of the +total. For more on how to use value expressions, see @ref{Value +expressions}. + +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. + +@option{--head} causes only the first N entries to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N transactions. @option{--tail} outputs only +the last N entries. Both options may be used simultaneously. If a +negative amount is given, it will invert the meaning of the flag +(instead of the first five entries being printed, for example, it +would print all but the first five). + +@option{--pager} tells Ledger to pass its output to the given pager +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. + +@option{--average} (@option{-A}) reports the average transaction +value. + +@option{--deviation} (@option{-D}) reports each transaction's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. + +@option{--percentage} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. + +@option{--totals} include running total information in the +@command{xml} report. + +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it output nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. + +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it output nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which transactions +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking transactions, against a running balance which +includes all transaction values: + +@example +ledger -d "d>=[last month]" reg checking +@end example + +The output from this command is very different from the following, +whose running total includes only transactions from the last month +onward: + +@example +ledger -p "last month" reg checking +@end example + +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). + +@option{--date-format STR} (@option{-y STR}) changes the basic date +format used by reports. The default uses a date like 2004/08/01, +which represents the default date format of @samp{%Y/%m/%d}. To +change the way dates are printed in general, the easiest way is to put +@option{--date-format FORMAT} in the Ledger initialization file +@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). + +@option{--format STR} (@option{-F STR}) sets the reporting format for +whatever report ledger is about to make. @xref{Format strings}. +There are also specific format commands for each report type: + +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize + +@node Commodity reporting, Environment variables, Output customization, Options +@subsection Commodity reporting + +These options affect how commodity values are displayed: + +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: + +@example +; Don't download quotes for the dollar, or timelog values +N $ +N h +@end example + +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. + +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. + +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: + +@table @code +@item -O, --quantity +Reports commodity totals (this is the default) + +@item -B, --basis +Reports the cost basis for all transactions. + +@item -V, --market +Reports the last known market value for all commodities. + +@item -g, --performance +Reports the net gain/loss for each transaction in a @command{register} +report. + +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. +@end table + +@node Environment variables, , Commodity reporting, Options +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. + +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: + +@example +--cache /tmp/.mycache +@end example + +@node Format strings, Value expressions, Options, Running Ledger +@section Format strings + +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the +@option{--format} (@option{-F}) option. Within that string, +constructs are allowed which make it possible to display the various +parts of an account or transaction in custom ways. + +Within a format strings, a substitution is specified using a percent +character (@samp{%}). The basic format of all substitutions is: + +@example +%[-][MIN WIDTH][.MAX WIDTH]EXPR +@end example + +If the optional minus sign (@samp{-}) follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text +will be at least that wide, perhaps wider. If a period and a maximum +width is given, the substituted text will never be wider than this, +and will be truncated to fit. Here are some examples: + +@example +%-P An entry's payee, left justified +%20P The same, right justified, at least 20 chars wide +%.20P The same, no more than 20 chars wide +%-.20P Left justified, maximum twenty chars wide +@end example + +The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: + +@table @code +@item % +Inserts a percent sign. + +@item t +Inserts the results of the value expression specified by @option{-t}. +If @option{-t} was not specified, the current report style's value +expression is used. + +@item T +Inserts the results of the value expression specified by @option{-T}. +If @option{-T} was not specified, the current report style's value +expression is used. + +@item | +Inserts a single space. This is useful if a width is specified, for +inserting a certain number of spaces. + +@item _ +Inserts a space for each level of an account's depth. That is, if an +account has two parents, this construct will insert two spaces. If a +minimum width is specified, that much space is inserted for each level +of depth. Thus @samp{%5_}, for an account with four parents, will +insert twenty spaces. + +@item (EXPR) +Inserts the amount resulting from the value expression given in +parentheses. To insert five times the total value of an account, for +example, one could say @samp{%12(5*O)}. Note: It's important to put +the five first in that expression, so that the commodity doesn't get +stripped from the total. + +@item [DATEFMT] +Inserts the result of formatting a transaction's date with a date +format string, exactly like those supported by @code{strftime}. For +example: @samp{%[%Y/%m/%d %H:%M:%S]}. + +@item S +Insert the pathname of the file from which the entry's data was read. + +@item B +Inserts the beginning character position of that entry within the file. + +@item b +Inserts the beginning line of that entry within the file. + +@item E +Inserts the ending character position of that entry within the file. + +@item e +Inserts the ending line of that entry within the file. + +@item D +By default, this is the same as @samp{%[%Y/%m%/d]}. The date format +used can be changed at any time with the @option{-y} flag, however. +Using @samp{%D} gives the user more control over the way dates are +output. + +@item d +This is the same as the @samp{%D} option, unless the entry has an +effective date, in which case it prints +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. + +@item X +If a transaction has been cleared, this inserts @samp{*} followed by a +space; otherwise nothing is inserted. + +@item Y +This is the same as @samp{%X}, except that it only displays a state +character if all of the member transactions have the same state. + +@item C +Inserts the checking number for an entry, in parentheses, followed by +a space; if none was specified, nothing is inserted. + +@item P +Inserts the payee related to a transaction. + +@item a +Inserts the optimal short name for an account. This is normally used +in balance reports. It prints a parent account's name if that name +has not been printed yet, otherwise it just prints the account's name. + +@item A +Inserts the full name of an account. + +@item W +This is the same as @samp{%A}, except that it first displays the +transaction's state @emph{if the entry's transaction states are not +all the same}, followed by the full account name. This is offered as +a printing optimization, so that combined with @samp{%Y}, only the +minimum amount of state detail is printed. + +@item o +Inserts the ``optimized'' form of a transaction's amount. This is +used by the print report. In some cases, this inserts nothing; in +others, it inserts the transaction amount and its cost. It's use is +not recommend unless you are modifying the print report. + +@item n +Inserts the note associated with a transaction, preceded by two spaces +and a semi-colon, if it exists. Thus, no none becomes an empty +string, while the note @samp{foo} is substituted as @samp{ ; foo}. + +@item N +Inserts the note associated with a transaction, if one exists. + +@item / +The @samp{%/} construct is special. It separates a format string +between what is printed for the first transaction of an entry, and +what is printed for all subsequent transactions. If not used, the +same format string is used for all transactions. +@end table + +@node Value expressions, Period expressions, Format strings, Running Ledger +@section Value expressions + +Value expressions are an expression language used by Ledger to +calculate values used by the program for many different purposes: + +@enumerate +@item +The values displayed in reports +@item +For predicates (where truth is anything non-zero), to determine which +transactions are calculated (@option{-l}) or displayed (@option{-d}). +@item +For sorting criteria, to yield the sort key. +@item +In the matching criteria used by automated transactions. +@end enumerate + +Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +argument is whatever follows it. The following is a display predicate +that I use with the @command{balance} command: + +@example +ledger -d /^Liabilities/?T<0:UT>100 balance +@end example + +The effect is that account totals are displayed only if: 1) A +Liabilities account has a total less than zero; or 2) the absolute +value of the account's total exceeds 100 units of whatever commodity +contains. If it contains multiple commodities, only one of them must +exceed 100 units. + +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: + +@example +ledger -d "d>[this month]" register checking +@end example + +This advantage to this command's complexity is that it prints the +running total in terms of all entries in the register. The following, +simpler command is similar, but totals only the displayed +transactions: + +@example +ledger -b "this month" register checking +@end example + +@subsection Variables + +Below are the one letter variables available in any value expression. +For the register and print commands, these variables relate to +individual transactions, and sometimes the account affected by a +transaction. For the balance command, these variables relate to +accounts---often with a subtle difference in meaning. The use of each +variable for both is specified. + +@table @code +@item t +This maps to whatever the user specified with @option{-t}. In a +register report, @option{-t} changes the value column; in a balance +report, it has no meaning by default. If @option{-t} was not +specified, the current report style's value expression is used. + +@item T +This maps to whatever the user specified with @option{-T}. In a +register report, @option{-T} changes the totals column; in a balance +report, this is the value given for each account. If @option{-T} was +not specified, the current report style's value expression is used. + +@item m +This is always the present moment/date. +@end table + +@subsubsection Transaction/account details + +@table @code +@item d +A transaction's date, as the number of seconds past the epoch. This +is always ``today'' for an account. + +@item a +The transaction's amount; the balance of an account, without +considering children. + +@item b +The cost of a transaction; the cost of an account, without its +children. + +@item v +The market value of a transaction, or an account without its children. + +@item g +The net gain (market value minus cost basis), for a transaction or an +account without its children. It is the same as @samp{v-b}. + +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. + +@item n +The index of a transaction, or the count of transactions affecting an +account. + +@item X +1 if a transaction's entry has been cleared, 0 otherwise. + +@item R +1 if a transaction is not virtual, 0 otherwise. + +@item Z +1 if a transaction is not automated, 0 otherwise. +@end table + +@subsubsection Calculated totals + +@table @code +@item O +The total of all transactions seen so far, or the total of an account +and all its children. + +@item N +The total count of transactions affecting an account and all its +children. + +@item B +The total cost of all transactions seen so far; the total cost of an +account and all its children. + +@item V +The market value of all transactions seen so far, or of an account and +all its children. + +@item G +The total net gain (market value minus cost basis), for a series of +transactions, or an account and its children. It is the same as +@samp{V-B}. +@end table + +@subsection Functions + +The available one letter functions are: + +@table @code +@item - +Negates the argument. + +@item U +The absolute (unsigned) value of the argument. + +@item S +Strips the commodity from the argument. + +@item A +The arithmetic mean of the argument; @samp{Ax} is the same as +@samp{x/n}. + +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. If no date +is given, then the current moment is used. +@end table + +@subsection Operators + +The binary and ternary operators, in order of precedence, are: + +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate + +@subsection Complex expressions + +More complicated expressions are possible using: + +@table @code +@item NUM +A plain integer represents a commodity-less amount. + +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. + +@item /REGEXP/ +@item W/REGEXP/ +A regular expression that matches against an account's full name. If +a transaction, this will match against the account affected by the +transaction. + +@item //REGEXP/ +@item p/REGEXP/ +A regular expression that matches against an entry's payee name. + +@item ///REGEXP/ +@item w/REGEXP/ +A regular expression that matches against an account's base name. If +a transaction, this will match against the account affected by the +transaction. + +@item c/REGEXP/ +A regular expression that matches against the entry code (the text +that occurs between parentheses before the payee name). + +@item e/REGEXP/ +A regular expression that matches against a transaction's note, or +comment field. + +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. + +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table + +@node Period expressions, File format, Value expressions, Running Ledger +@section Period expressions + +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: + +@example +[INTERVAL] [BEGIN] [END] +@end example + +The optional @var{INTERVAL} part may be any one of: + +@example +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly +@end example + +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: + +@example +from <SPEC> +since <SPEC> +@end example + +The end time can be either of: + +@example +to <SPEC> +until <SPEC> +@end example + +Where @var{SPEC} can be any of: + +@example +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week +@end example + +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: + +@example +<SPEC> +in <SPEC> +@end example + +Here are a few examples of period expressions: + +@example +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +last oct +weekly last august +@end example + +@node File format, Some typical queries, Period expressions, Running Ledger +@section 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: + +@table @code +@item NUMBER +A line beginning with a number denotes an entry. It may be followed +by any number of lines, each beginning with whitespace, to denote the +entry's account transactions. The format of the first line is: + +@example +DATE[=EDATE] [*|!] [(CODE)] DESC +@end example + +If @samp{*} appears after the date (with optional effective date), it +indicates the entry is ``cleared'', which can mean whatever the user +wants it t omean. If @samp{!} appears after the date, it indicates d +the entry is ``pending''; i.e., tentatively cleared from the user's +point of view, but not yet actually cleared. If a @samp{CODE} appears +in parentheses, it may be used to indicate a check number, or the type +of the transaction. Following these is the payee, or a description of +the transaction. + +The format of each following transaction is: + +@example + ACCOUNT AMOUNT [; NOTE] +@end example + +The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual +transactions, or square brackets if it is a virtual transactions that +must balance. The @samp{AMOUNT} can be followed by a per-unit +transaction cost, by specifying @samp{@ AMOUNT}, or a complete +transaction cost with @samp{@@ AMOUNT}. Lastly, the @samp{NOTE} may +specify an actual and/or effective date for the transaction by using +the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. + +@item = +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. + +@item ~ +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. + +@item ! +A line beginning with an exclamation mark denotes a command directive. +It must be immediately followed by the command word. The supported +commands are: + +@table @samp +@item !include +Include the stated ledger file. + +@item !account +The account name is given is taken to be the parent of all +transactions that follow, until @samp{!end} is seen. + +@item !end +Ends an account block. +@end table + +@item ; +A line beginning with a colon indicates a comment, and is ignored. + +@item Y +If a line begins with a capital Y, it denotes the year used for all +subsequent entries that give a date without a year. The year should +appear immediately after the Y, for example: @samp{Y2004}. This is +useful at the beginning of a file, to specify the year for that file. +If all entries specify a year, however, this command has no effect. + +@item P +Specifies a historical price for a commodity. These are usually found +in a pricing history file (see the @option{-Q} option). The syntax +is: +@example +P DATE SYMBOL PRICE +@end example + +@item N SYMBOL +Indicates that pricing information is to be ignored for a given +symbol, nor will quotes ever be downloaded for that symbol. Useful +with a home currency, such as the dollar ($). It is recommended that +these pricing options be set in the price database file, which +defaults to @file{~/.pricedb}. The syntax for this command is: +@example +N SYMBOL +@end example + +@item D AMOUNT +Specifies the default commodity to use, by specifying an amount in the +expected format. The @command{entry} command will use this commodity +as the default when none other can be determined. This command may be +used multiple times, to set the default flags for different +commodities; whichever is seen last is used as the default commodity. +For example, to set US dollars as the default commodity, while also +setting the thousands flag and decimal flag for that commodity, use: +@example +D $1,000.00 +@end example + +@item C AMOUNT1 = AMOUNT2 +Specifies a commodity conversion, where the first amount is given to +be equivalent to the second amount. The first amount should use the +decimal precision desired during reporting: +@example +C 1.00 Kb = 1024 bytes +@end example + +@item i, o, b, h +These four relate to timeclock support, which permits ledger to read +timelog files. See the timeclock's documentation for more info on the +syntax of its timelog files. +@end table + +@node Some typical queries, Budgeting and forecasting, File format, Running Ledger +@section Some typical queries + +A query such as the following shows all expenses since last +October, sorted by total: + +@example +ledger -b "last oct" -s -S T bal ^expenses +@end example + +From left to right the options mean: Show entries since October, 2003; +show all sub-accounts; sort by the absolute value of the total; and +report the balance for all expenses. + +@subsection Reporting monthly expenses + +The following query makes it easy to see monthly expenses, with each +month's expenses sorted by the amount: + +@example +ledger -M --period-sort t reg ^expenses +@end example + +Now, you might wonder where the money came from to pay for these +things. To see that report, add @option{-r}, which shows the +``related account'' transactions: + +@example +ledger -M --period-sort t -r reg ^expenses +@end example + +But maybe this prints too much information. You might just want to +see how much you're spending with your MasterCard. That kind of query +requires the use of a display predicate, since the transactions +calculated must match @samp{^expenses}, while the transactions +displayed must match @samp{mastercard}. The command would be: + +@example +ledger -M -r -d /mastercard/ reg ^expenses +@end example + +This query says: Report monthly subtotals; report the ``related +account'' transactions; display only related transactions whose +account matches @samp{mastercard}, and base the calculation on +transactions matching @samp{^expenses}. + +This works just as well for report the overall total, too: + +@example +ledger -s -r -d /mastercard/ reg ^expenses +@end example + +The @option{-s} option subtotals all transactions, just as @option{-M} +subtotaled by the month. The running total in both cases is off, +however, since a display expression is being used. + +@subsection Visualizing with Gnuplot + +If you have @command{Gnuplot} installed, you can graph any of the +above register reports. The script to do this is included in the +ledger distribution, and is named @file{scripts/report}. Install +@file{report} anywhere along your @env{PATH}, and then use +@command{report} instead of @command{ledger} when doing a register +report. The only thing to keep in mind is that you must specify +@option{-j} or @option{-J} to indicate whether Gnuplot should plot the +amount, or the running total. For example, this command plots total +monthly expenses made on your MasterCard. + +@example +report -j -M -r -d /mastercard/ reg ^expenses +@end example + +The @command{report} script is a very simple Bourne shell script, that +passes a set of scripted commands to Gnuplot. Feel free to modify the +script to your liking, since you may prefer histograms to line plots, +for example. + +@subsubsection Typical plots + +Here are some useful plots: + +@smallexample +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 +@end smallexample + +The last report uses both a calculation predicate (@option{-l}) and a +display predicate (@option{-d}). The calculation predicates limits +the report to transactions whose amount is greater than $1 (which can +only happen if the transaction amount is in dollars). The display +predicate limits the entries @emph{displayed} to just those since last +February, even those entries from before then will be computed as part +of the balance. + +@node Budgeting and forecasting, , Some typical queries, Running Ledger +@section Budgeting and forecasting + +@subsection 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: + +@smallexample +~ Monthly + Expenses:Rent $500.00 + Expenses:Food $450.00 + Expenses:Auto:Gas $120.00 + Expenses:Insurance $150.00 + Expenses:Phone $125.00 + Expenses:Utilities $100.00 + Expenses:Movies $50.00 + Expenses $200.00 ; all other expenses + Assets + +~ Yearly + Expenses:Auto:Repair $500.00 + Assets +@end smallexample + +These two period entries give the usual monthly expenses, as well as +one typical yearly expense. For help on finding out what your average +monthly expense is for any category, use a command like: + +@example +ledger -p "this year" -MAs bal ^expenses +@end example + +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 @option{--budget} to the command-line. For example, a +typical monthly expense report would be: + +@example +ledger -M reg ^exp +@end example + +To see the same report balanced against your budget, use: + +@example +ledger --budget -M reg ^exp +@end example + +A budget report includes only those accounts that appear in the +budget. To see all expenses balanced against the budget, use +@option{--add-budget}. You can even see only the unbudgeted expenses +using @option{--unbudgeted}: + +@example +ledger --unbudgeted -M reg ^exp +@end example + +You can also use these flags with the @command{balance} command. + +@subsection Forecasting + +Sometimes it's useful to know what your finances will look like in the +future, such as determining when an account will reach zero. Ledger +makes this easy to do, using the same period entries as are used for +budgeting. An example forecast report can be generated with: + +@example +ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities +@end example + +This report continues outputting transactions until the running total +is greater than $-500.00. A final transaction is always output, to +show you what the total afterwards would be. + +Forecasting can also be used with the balance report, but by date +only, and not against the running total: + +@example +ledger --forecast "d<[2010]" bal ^assets ^liabilities +@end example + +@node Keeping a ledger, Using XML, Running Ledger, Top +@chapter Keeping a ledger + +The most important part of accounting is keeping a good ledger. If +you have a good ledger, tools can be written to work whatever +mathematically tricks you need to better understand your spending +patterns. Without a good ledger, no tool, however smart, can help +you. + +The Ledger program aims at making ledger entry as simple as possible. +Since it is a command-line tool, it does not provide a user interface +for keeping a ledger. If you like, you may use GnuCash to maintain +your ledger, in which case the Ledger program will read GnuCash's data +files directly. In that case, read the GnuCash manual now, and skip +to the next chapter. + +If you are not using GnuCash, but a text editor to maintain your +ledger, read on. Ledger has been designed to make data entry as +simple as possible, by keeping the ledger format easy, and also by +automagically determining as much information as possible based on the +nature of your entries. + +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: + +@smallexample +9/29 (100) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking $-23.00 +@end smallexample + +As you can see, it is very similar to what would be written on paper, +minus the computed balance totals, and adding in account names that +work better with Ledger's scheme of things. In fact, since Ledger is +smart about many things, you don't need to specify the balanced +amount, if it is the same as the first line: + +@smallexample +9/29 (100) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking +@end smallexample + +For this entry, Ledger will figure out that $-23.00 must come from +@samp{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:: +@end menu + +@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger +@section Stating where money goes + +Accountants will talk of ``credits'' and ``debits'', but 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 @emph{subtracted} +from the source accounts, and @emph{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: + +@smallexample +9/29 My Employer + Assets:Checking $500.00 + Income:Salary $-500.00 +@end smallexample + +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? + +@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger +@section Assets and Liabilities + +Assets are money that you have, and Liabilities are money that you +owe. ``Liabilities'' is just a more inclusive name for Debts. + +An Asset is typically increased by transferring money from an Income +account, such as when you get paid. Here is a typical entry: + +@smallexample +2004/09/29 My Employer + Assets:Checking $500.00 + Income:Salary +@end smallexample + +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: + +@smallexample +2004/09/30 Restaurant + Expenses:Dining $25.00 + Liabilities:MasterCard +@end smallexample + +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: + +@example +ledger balance ^assets ^liabilities +@end example + +Relatedly, your Income accounts show up negative, because they +transfer money @emph{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: + +@example +ledger balance ^income ^expenses +@end example + +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: + +@example +ledger -M register expenses:auto +@end example + +This assumes, of course, that you use account names like +@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}. + +@subsection Tracking reimbursable expenses + +Sometimes you will want to spend money on behalf of someone else, +which will eventually get repaid. Since the money is still ``yours'', +it is really an asset. And since the expenditure was for someone +else, you don't want it contaminating your Expenses reports. You will +need to keep an account for tracking reimbursements. + +This is fairly easy to do in ledger. When spending the money, spend +it @emph{to} your Assets:Reimbursements, using a different account for +each person or business that you spend money for. For example: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard +@end smallexample + +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: + +@smallexample +2004/09/29 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ +@end smallexample + +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: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard +@end smallexample + +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: + +@smallexample +2004/09/29 Circuit City + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name +@end smallexample + +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: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard $-100.00 + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name $-100.00 +@end smallexample + +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: + +@smallexample +2004/10/15 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ $-100.00 + Company XYZ:Accounts Payable:Your Name $100.00 + Company XYZ:Assets:Checking $-100.00 +@end smallexample + +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 @samp{Assets:Reimbursements:Company +XYZ}, and @samp{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: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard $-100.00 + +2004/10/15 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ $-100.00 +@end smallexample + +And two in your company ledger file: + +@smallexample +!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 +@end smallexample + +(Note: The @samp{!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. + +@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger +@section Commodities and Currencies + +Ledger makes no assumptions about the commodities you use; it only +requires that you specify a commodity. The commodity may be any +non-numeric string that does not contain a period, comma, forward +slash or at-sign. It may appear before or after the amount, although +it is assumed that symbols appearing before the amount refer to +currencies, while non-joined symbols appearing after the amount refer +to commodities. Here are some valid currency and commodity +specifiers: + +@example +$20.00 ; currency: twenty US dollars +40 AAPL ; commodity: 40 shares of Apple stock +60 DM ; currency: 60 Deutsch Mark +£50 ; currency: 50 British pounds +50 EUR ; currency: 50 Euros (or use appropriate symbol) +@end example + +Ledger will examine the first use of any commodity to determine how +that commodity should be printed on reports. It pays attention to +whether the name of commodity was separated from the amount, whether +it came before or after, the precision used in specifying the amount, +whether thousand marks were used, etc. This is done so that printing +the commodity looks the same as the way you use it. + +An account may contain multiple commodities, in which case it will +have separate totals for each. For example, if your brokerage account +contains both cash, gold, and several stock quantities, the balance +might look like: + +@smallexample + $200.00 +100.00 AU + AAPL 40 + BORL 100 + FEQTX 50 Assets:Brokerage +@end smallexample + +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: + +@smallexample +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 +@end smallexample + +Specify the price history to use with the @option{--price-db} option, +with the @option{-V} option to report in terms of current market +value: + +@example +ledger --price-db prices.db -V balance brokerage +@end example + +The balance for your brokerage account will be reported in US dollars, +since the prices database uses that currency. + +@smallexample +$40880.00 Assets:Brokerage +@end smallexample + +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: + +@example +ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking +@end example + +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: + +@smallexample +14.01 AU Assets:Checking +@end smallexample + +@subsection Commodity price histories + +Whenever a commodity is purchased using a different commodity (such as +a share of common stock using dollars), it establishes a price for +that commodity on that day. It is also possible, by recording price +details in a ledger file, to specify other prices for commodities at +any given time. Such price entries might look like those below: + +@smallexample +P 2004/06/21 02:17:58 TWCUX $27.76 +P 2004/06/21 02:17:59 AGTHX $25.41 +P 2004/06/21 02:18:00 OPTFX $39.31 +P 2004/06/21 02:18:01 FEQTX $22.49 +P 2004/06/21 02:18:02 AAPL $32.91 +@end smallexample + +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. + +@subsection 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 @samp{Billable} account, and another +which decreases the same account by ten minutes. The resulting report +will indicate that fifty minutes remain: + +@smallexample +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 +@end smallexample + +Reporting the balance for this ledger file produces: + +@smallexample + 50.0m Billable:Client + -50.0m Project:XYZ +@end smallexample + +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: + +@smallexample +C 1.00 Kb = 1024 b +C 1.00 Mb = 1024 Kb +C 1.00 Gb = 1024 Mb +C 1.00 Tb = 1024 Gb +@end smallexample + +Each of these definitions correlates a commodity (such as @samp{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 @samp{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. + +@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger +@section Accounts and Inventories + +Since Ledger's accounts and commodity system is so flexible, you can +have accounts that don't really exist, and use commodities that no one +else recognizes. For example, let's say you are buying and selling +various items in EverQuest, and want to keep track of them using a +ledger. Just add items of whatever quantity you wish into your +EverQuest account: + +@smallexample +9/29 Get some stuff at the Inn + Places:Black's Tavern -3 Apples + Places:Black's Tavern -5 Steaks + EverQuest:Inventory +@end smallexample + +Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The +amounts are negative, because you are taking @emph{from} Black's +Tavern in order to add to your Inventory account. Note that you don't +have to use @samp{Places:Black's Tavern} as the source account. You +could use @samp{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: + +@smallexample +10/2 Sturm Brightblade + EverQuest:Inventory -2 Steaks + EverQuest:Inventory 15 Gold +@end smallexample + +Now you've turned 2 steaks into 15 gold, courtesy of your customer, +Sturm Brightblade. + +@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Keeping a ledger +@section Understanding Equity + +The most confusing entry in any ledger will be your equity account--- +because starting balances can't come out of nowhere. + +When you first start your ledger, you will likely already have money +in some of your accounts. Let's say there's $100 in your checking +account; then add an entry to your ledger to reflect this amount. +Where will money come from? The answer: your equity. + +@smallexample +10/2 Opening Balance + Assets:Checking $100.00 + Equity:Opening Balances +@end smallexample + +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 +@samp{-Equity} at the end of your balance command, to remove the +confusing figure from the total. + +@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Keeping a ledger +@section Dealing with Petty Cash + +Something that stops many people from keeping a ledger at all is the +insanity of tracking small cash expenses. They rarely generate a +receipt, and there are often a lot of small transactions, rather than +a few large ones, as with checks. + +One solution is: don't bother. Move your spending to a debit card, +but in general ignore cash. Once you withdraw it from the ATM, mark +it as already spent to an @samp{Expenses:Cash} category: + +@smallexample +2004/03/15 ATM + Expenses:Cash $100.00 + Assets:Checking +@end smallexample + +If at some point you make a large cash expense that you want to track, +just ``move'' the amount of the expense from @samp{Expenses:Cash} into +the target account: + +@smallexample +2004/03/20 Somebody + Expenses:Food $65.00 + Expenses:Cash +@end smallexample + +This way, you can still track large cash expenses, while ignoring all +of the smaller ones. + +@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Keeping a ledger +@section 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: + +@itemize +@item Checking +@item Savings +@item Credit Card +@end itemize + +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: + +@itemize +@item School fund +@item Building fund +@item Community fund +@end itemize + +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 @samp{$500.00}, but +@samp{$400.00} of that comes from Checking, and @samp{$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: + +@smallexample +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 +@end smallexample + +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: + +@smallexample +2004/03/25 Payment for books (paid from Checking) + Expenses:Books $100.00 + Assets:Checking $-100.00 + (Funds:School) $-100.00 +@end smallexample + +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 +@samp{Assets} account, because otherwise the balance won't make much +sense: + +@example +ledger bal -^Assets +@end example + +If the @option{--real} option is used, the report will be in terms of +the real accounts: + +@example +ledger --real bal +@end example + +If more asset accounts are needed as the source of a transaction, just +list them as you would normally, for example: + +@smallexample +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 +@end smallexample + +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 @samp{Funds:School} fund: + +@smallexample +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 +@end smallexample + +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 +@option{--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 +@option{--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: + +@smallexample +ledger --code-as-payee -P reg ^Assets +@end smallexample + +Or to see a particular funds expenses, the @samp{School} fund in this +case: + +@smallexample +ledger --code-as-payee -P reg ^Expenses -- School +@end smallexample + +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. + +@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Keeping a ledger +@section Archiving previous years + +After a while, your ledger can get to be pretty large. While this +will not slow down the ledger program much---it's designed to process +ledger files very quickly---things can start to feel ``messy''; and +it's a universal complaint that when finances feel messy, people avoid +them. + +Thus, archiving the data from previous years into their own files can +offer a sense of completion, and freedom from the past. But how to +best accomplish this with the ledger program? There are two commands +that make it very simple: @command{print}, and @command{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 +@command{print} to output all the earlier entries to a file called +@file{ledger-old.dat}: + +@smallexample +ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat +@end smallexample + +To delete older data from the current ledger file, use @command{print} +again, this time specifying year 2002 as the starting date: + +@example +ledger -f ledger.dat -b 2002 print > x +mv x ledger.dat +@end example + +However, now the current file contains @emph{only} transactions from +2002 onward, which will not yield accurate present-day balances, +because the net income from previous years is no longer being tallied. +To compensate for this, we must append an equity report for the old +ledger at the beginning of the new one: + +@example +ledger -f ledger-old.dat equity > equity.dat +cat equity.dat ledger.dat > x +mv x ledger.dat +rm equity.dat +@end example + +Now the balances reported from @file{ledger.dat} are identical to what +they were before the data was split. + +How often should you split your ledger? You never need to, if you +don't want to. Even eighty years of data will not slow down ledger +much---and that's just using present day hardware! Or, you can keep +the previous and current year in one file, and each year before that +in its own file. It's really up to you, and how you want to organize +your finances. For those who also keep an accurate paper trail, it +might be useful to archive the older years to their own files, then +burn those files to a CD to keep with the paper records---along with +any electronic statements received during the year. In the arena of +organization, just keep in mind this maxim: Do whatever keeps you +doing it. + +@node Virtual transactions, Automated transactions, Archiving previous years, Keeping a ledger +@section Virtual transactions + +A virtual transaction is when you, in your mind, see money as moving +to a certain place, when in reality that money has not moved at all. +There are several scenarios in which this type of tracking comes in +handy, and each of them will be discussed in detail. + +To enter a virtual transaction, surround the account name in +parentheses. This form of usage does not need to balance. However, +if you want to ensure the virtual transaction balances with other +virtual transactions in the same entry, use square brackets. For +example: + +@smallexample +10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + (Debt:Alimony) $200.00 +@end smallexample + +In this example, after receiving a paycheck an alimony debt is +increased---even though no money has moved around yet. + +@smallexample +10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + [Savings:Trip] $200.00 + [Assets:Checking] $-200.00 +@end smallexample + +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 @samp{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 +@option{-R} flag, for ``reality''. + +@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Keeping a ledger +@section 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: + +@smallexample +; 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 +@end smallexample + +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 @samp{Liabilities:Huququ'llah} +account. So, if $1000 is earned from @samp{Income:Salary}, $190 is +added to @samp{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 +@samp{Liabilities:Huququ'llah}. That entry would look like: + +@smallexample +2003/01/01 (101) Baha'i Huqúqu'lláh Trust + Liabilities:Huququ'llah $1,000.00 + Assets:Checking +@end smallexample + +That's it. To see how much Huqúq is currently owed based on your +ledger entries, use: + +@example +ledger balance Liabilities:Huquq +@end example + +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: + +@smallexample +ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab +@end smallexample + +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: + +@smallexample +ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab +@end smallexample + +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 @samp{$account}: + +@smallexample += /^Some:Long:Account:Name/ + [$account] -0.10 + [Savings] 0.10 +@end smallexample + +This example causes 10% of the matching account's total to be deferred +to the @samp{Savings} account---as a balanced virtual transaction, +which may be excluded from reports by using @option{--real}. + +@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Keeping a ledger +@section Using Emacs to Keep Your Ledger + +In the Ledger tarball is an Emacs module, @file{ledger.el}. This +module makes the process of keeping a text ledger much easier for +Emacs users. I recommend putting this at the top of your ledger file: + +@example +; -*-ledger-*- +@end example + +And this in your @file{.emacs} file, after copying @file{ledger.el} to +your @file{site-lisp} directory: + +@example +(load "ledger") +@end example + +Now when you edit your ledger file, it will be in +@command{ledger-mode}. @command{ledger-mode} adds these commands: + +@table @strong +@item C-c C-a +For quickly adding new entries based on the form of older ones (see +previous section). + +@item C-c C-c +Toggles the ``cleared'' flag of the transaction under point. + +@item C-c C-d +Delete the entry under point. + +@item C-c C-r +Reconciles an account by displaying the transactions in another +buffer, where simply hitting the spacebar will toggle the 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. + +@item 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. + +@item 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. +@end table + +Once you enter the reconcile buffer, there are several key commands +available: + +@table @strong +@item RET +Visit the ledger file entry corresponding to the reconcile entry. + +@item 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. + +@item C-l +Refresh the reconcile buffer by re-reading transactions from the +ledger data file. + +@item SPC +Toggle the transaction under point as cleared. + +@item 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). + +@item d +Delete the entry related to the transaction under point. Note: This +may result in multiple transactions being deleted. + +@item n +Move to the next line. + +@item p +Move to the previous line. + +@item C-c C-r +@item 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. + +@item C-x C-s +@item s +Save the ledger data file, and show the current cleared balance for +the account being reconciled. + +@item q +Quit the reconcile buffer. +@end table + +There is also an @command{emacs} command which can be used to output +reports in a format directly @code{read}-able from Emacs Lisp. + +@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Keeping a ledger +@section Using GnuCash to Keep Your Ledger + +The Ledger tool is fast and simple, but it offers no custom method for +actually editing the ledger. It assumes you know how to use a text +editor, and like doing so. Perhaps an Emacs mode will appear someday +soon to make editing Ledger's data files much easier. + +Until then, you are free to use GnuCash to maintain your ledger, and +the Ledger program for querying and reporting on the contents of that +ledger. It takes a little longer to parse the XML data format that +GnuCash uses, but the end result is identical. + +Then again, why would anyone use a Gnome-centric, 35 megabyte behemoth +to edit their data, and a one megabyte binary to query it? + +@node Using timeclock to record billable time, , Using GnuCash to Keep Your Ledger, Keeping a ledger +@section Using timeclock to record billable time + +The timeclock tool makes it easy to track time events, like clocking +into and out of a particular job. These events accumulate in a +timelog file. + +Each in/out event may have an optional description. If the ``in'' +description is a ledger account name, these in/out pairs may be viewed +as virtual transactions, adding time commodities (hours) to that +account. + +For example, the command-line version of the timeclock tool could be +used to begin a timelog file like: + +@example +export TIMELOG=$HOME/.timelog +ti ClientOne category +sleep 10 +to waited for ten seconds +@end example + +The @file{.timelog} file now contains: + +@smallexample +i 2004/10/06 15:21:00 ClientOne category +o 2004/10/06 15:21:10 waited for ten seconds +@end smallexample + +Ledger parses this directly, as if it had seen the following entry: + +@smallexample +2004/10/06 category + (ClientOne) 10s +@end smallexample + +In other words, the timelog event pair is seen as adding 0.00277h (ten +seconds) worth of time to the @samp{ClientOne} account. This would be +considered billable time, which later could be invoiced and credited +to accounts receivable: + +@smallexample +2004/11/01 (INV#1) ClientOne, Inc. + Receivable:ClientOne $0.10 + ClientOne -0.00277h @@ $35.00 +@end smallexample + +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: + +@smallexample +2004/12/01 ClientOne, Inc. + Assets:Checking $0.10 + Receivable:ClientOne +@end smallexample + +And now the time spent has been turned into hard cash in the checking +account. + +The advantage to using timeclock and invoicing to bill time is that +you will always know, by looking at the balance report, exactly how +much unbilled and unpaid time you've spent working for any particular +client. + +I like to @samp{!include} my timelog at the top of my company's +accounting ledger, with the attached prefix @samp{Billable}: + +@smallexample +; -*-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 +@end smallexample + +@node Using XML, , Keeping a ledger, Top +@chapter 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: + +@smallexample +<?xml version="1.0"?> +<ledger> + <entry>...</entry> + <entry>...</entry> + <entry>...</entry>... +</ledger> +@end smallexample + +The data stream is enclosed in a @samp{ledger} tag, which contains a +series of one or more entries. Each @samp{entry} describes the entry +and contains a series of one or more transactions: + +@smallexample +<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> +@end smallexample + +The date format for @samp{en:date} is always @samp{YYYY/MM/DD}. The +@samp{en:cleared} tag is optional, and indicates whether the +transaction has been cleared or not. There is also an +@samp{en:pending} tag, for marking pending transactions. The +@samp{en:code} and @samp{en:payee} tags both contain whatever text the +user wishes. + +After the initial entry data, there must follow a set of transactions +marked with @samp{en:transactions}. Typically these transactions will +all balance each other, but if not they will be automatically balanced +into an account named @samp{<Unknown>}. + +Within the @samp{en:transactions} tag is a series of one or more +@samp{transaction}'s, which have the following form: + +@smallexample +<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> +@end smallexample + +This is a basic transaction. It may also be begin with +@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual +and auto-generated transactions. Then follows the @samp{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 +@samp{tr:amount}. Within this tag is a @samp{value} tag, of which +there are four different kinds, each with its own format: + +@enumerate +@item boolean +@item integer +@item amount +@item balance +@end enumerate + +The format of a boolean value is @samp{true} or @samp{false} +surrounded by a @samp{boolean} tag, for example: + +@smallexample +<boolean>true</boolean> +@end smallexample + +The format of an integer value is the numerical value surrounded by an +@samp{integer} tag, for example: + +@smallexample +<integer>12036</integer> +@end smallexample + +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: + +@table @strong +@item P +The commodity is prefixed to the value. +@item S +The commodity is separated from the value by a space. +@item T +Thousands markers are used to display the amount. +@item E +The format of the amount is European, with period used as a thousands +marker, and comma used as the decimal point. +@end table + +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: + +@smallexample +<value type="amount"> + <amount> + <commodity flags="PT">$</commodity> + <quantity>90.00</quantity> + </amount> +</value> +@end smallexample + +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: + +@smallexample +<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> +@end smallexample + +That is the extent of the XML data format used by Ledger. It will +output such data if the @command{xml} command is used, and can read +the same data as long as the @file{expat} library was available +when Ledger was built. + +@bye |