hledger/README

hledger - a ledger-compatible text-based accounting tool
========================================================

Welcome to hledger! 

hledger is a haskell clone of John Wiegley's "ledger" text-based
accounting tool (http://newartisans.com/software/ledger.html).  
It generates ledger-compatible register & balance reports from a plain
text ledger file, and demonstrates a functional implementation of ledger.
For more information, see hledger's home page: http://joyful.com/hledger

Copyright (c) 2007-2009 Simon Michael <simon@joyful.com>
Released under GPL version 3 or later.


Installation
------------
hledger requires GHC. It is known to build with 6.8 and 6.10.
If you have cabal-install, do::

 cabal update
 cabal install hledger

Otherwise, unpack the latest tarball from
http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hledger and do::

 runhaskell Setup.hs configure
 runhaskell Setup.hs build
 sudo runhaskell Setup.hs install 

This will complain about any missing libraries, which you can download and
install manually from hackage.haskell.org. (The Build-Depends: in
hledger.cabal has the full package list.)

To get the latest development code do::

 darcs get http://joyful.com/repos/hledger


Usage
-----
hledger looks for your ledger file at ~/.ledger by default. To use a
different file, specify it with the LEDGER environment variable or -f
option (which may be - for standard input). Here are some commands to
try::

 hledger --help
 hledger -f sample.ledger balance
 export LEDGER=sample.ledger
 hledger -s balance
 hledger register
 hledger reg cash
 hledger reg -- shop
 hledger ui


Time reporting
--------------
hledger can parse a timelog file in timeclock.el's format, treating time
categories as accounts. If hledger is invoked by the "hours" alias it
looks for your timelog, and parses arguments slightly differently for
convenient querying:

 hours [OPTIONS] [PERIOD [COMMAND]]

PERIOD and COMMAND default to "today" and "balance --subtotal"
respectively, and --options-anywhere is assumed.  The timelog is found in
the same way as your ledger: ~/.timelog or the file specified by $TIMELOG
or an -f option.  Examples:

 hours                                 # today's balances
 hours today                           # the same
 hours 'this week'                     # so far this week
 hours week                            # the same
 hours lastmonth                       # last month, the space is optional
 hours 'monthly in 2008' reg --depth 1 # monthly register, top-level only

Features
--------

This version of hledger mimics a subset of ledger 2.6.1, and adds some
features of its own. We currently support: the balance, print, and
register commands, regular ledger entries, multiple commodities, virtual
transactions, account and description patterns, the LEDGER environment
variable, and these options::

   Basic options:
   -h, --help             display summarized help text
   -v, --version          show version information
   -f, --file FILE        read ledger data from FILE
 
   Report filtering:
   -b, --begin DATE       set report begin date
   -e, --end DATE         set report end date
   -p, --period EXPR      report using the given period
   -C, --cleared          consider only cleared transactions
   -R, --real             consider only real (non-virtual) transactions
 
   Output customization:
   -n, --collapse         balance report: no grand total
   -d, --display EXPR     display only transactions matching EXPR (limited support)
   -E, --empty            balance report: show accounts with zero balance
   -s, --subtotal         balance report: show sub-accounts
 
   Commodity reporting:
   -B, --basis, --cost    report cost basis of commodities

   Commands:
   balance  [REGEXP]...   show balance totals for matching accounts
   register [REGEXP]...   show register of matching transactions
   print    [REGEXP]...   print all matching entries

We handle (almost) the full period expression syntax, and simple display
expressions consisting of a date predicate.  Also the following
hledger-specific features are supported::

   ui                     interactive text ui
   --depth=N              balance report: maximum account depth to show
   --options-anywhere     allow options anywhere, use ^ for negative patterns

ledger features not supported
.............................

ledger features not yet supported include: modifier and periodic entries,
!include and other special directives, price history entries, parsing
gnucash files, and the following options::

   Basic options:
   -o, --output FILE      write output to FILE
   -i, --init-file FILE   initialize ledger using FILE (default: ~/.ledgerrc)
       --cache FILE       use FILE as a binary cache when --file is not used
       --no-cache         don't use a cache, even if it would be appropriate
   -a, --account NAME     use NAME for the default account (useful with QIF)
 
   Report filtering:
   -c, --current          show only current and past entries (not future)
       --period-sort EXPR sort each report period's entries by EXPR
   -U, --uncleared        consider only uncleared transactions
   -L, --actual           consider only actual (non-automated) transactions
   -r, --related          calculate report using related transactions
       --budget           generate budget entries based on periodic entries
       --add-budget       show all transactions plus the budget
       --unbudgeted       show only unbudgeted transactions
       --forecast EXPR    generate forecast entries while EXPR is true
   -l, --limit EXPR       calculate only transactions matching EXPR
   -t, --amount EXPR      use EXPR to calculate the displayed amount
   -T, --total EXPR       use EXPR to calculate the displayed total
 
   Output customization:
   -n, --collapse         register: collapse entries
   -s, --subtotal         other: show subtotals
   -P, --by-payee         show summarized totals by payee
   -x, --comm-as-payee    set commodity name as the payee, for reporting
   -W, --weekly           show weekly sub-totals
   -M, --monthly          show monthly sub-totals
   -Y, --yearly           show yearly sub-totals
       --dow              show a days-of-the-week report
   -S, --sort EXPR        sort report according to the value expression EXPR
   -w, --wide             for the default register report, use 132 columns
       --head COUNT       show only the first COUNT entries (negative inverts)
       --tail COUNT       show only the last COUNT entries (negative inverts)
       --pager PAGER      send all output through the given PAGER program
   -A, --average          report average transaction amount
   -D, --deviation        report deviation from the average
   -%, --percentage       report balance totals as a percentile of the parent
       --totals           in the "xml" report, include running total
   -j, --amount-data      print only raw amount data (useful for scripting)
   -J, --total-data       print only raw total data
   -y, --date-format STR  use STR as the date format (default: %Y/%m/%d)
   -F, --format STR       use STR as the format; for each report type, use:
       --balance-format      --register-format       --print-format
       --plot-amount-format  --plot-total-format     --equity-format
       --prices-format       --wide-register-format
 
   Commodity reporting:
       --price-db FILE    sets the price database to FILE (def: ~/.pricedb)
   -L, --price-exp MINS   download quotes only if newer than MINS (def: 1440)
   -Q, --download         download price information when needed
   -O, --quantity         report commodity totals (this is the default)
   -V, --market           report last known market value
   -g, --performance      report gain/loss for each displayed transaction
   -G, --gain             report net gain/loss
 
   Commands:
   xml      [REGEXP]...   print matching entries in XML format
   equity   [REGEXP]...   output equity entries for matching accounts
   prices   [REGEXP]...   display price history for matching commodities
   entry DATE PAYEE AMT   output a derived entry, based on the arguments

Other differences
.................

* hledger keeps differently-priced amounts of the same commodity separate at the moment
* hledger refers to the entry's and transaction's "description", ledger calls it "note"
* hledger doesn't require a space before command-line option values
* hledger provides "--cost" as a synonym for "--basis"
* hledger's "weekly" reporting intervals always start on mondays
* hledger shows start and end dates of full intervals, not just the span containing data
* hledger period expressions don't support "biweekly", "bimonthly", or "every N days/weeks/..." 
* hledger always shows timelog balances in hours
* hledger doesn't count an unfinished timelog session