hledger - a ledger-compatible text-based accounting tool ======================================================== Welcome to hledger! hledger is a partial haskell clone of John Wiegley's text-based accounting tool, ledger (http://wiki.github.com/jwiegley/ledger). hledger generates ledger-compatible register & balance reports from a plain text journal, and demonstrates a functional implementation of ledger. For more information, see http://hledger.org . Copyright (c) 2007-2009 Simon Michael Released under GPL version 3 or later. Installation ------------ Building hledger requires GHC (http://haskell.org/ghc); it is known to build with GHC 6.8 and up. hledger should work on any platform which GHC supports. Also, installing hledger easily requires the "cabal" command-line tool, version 0.6.0 and up (http://www.haskell.org/cabal/download.html). (You can also manually download and install each dependency mentioned in hledger.cabal from hackage.org, but installing cabal is much quicker.) Here's how to download and install the latest hledger release:: cabal update cabal install hledger Or, to build with all optional features enabled (downloads additional dependencies):: cabal install --flags="happs vty" hledger The available flags are:: happs - enable the built-in webserver vty - enable the curses text ui ansi - enable the ansi text ui (use instead of vty on MS windows) And for developers, here's how to get the latest development code:: 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 (~/.timelog, or the file specified by $TIMELOG or -f), and parses arguments slightly differently for convenient querying:: hours [OPTIONS] [PERIOD [COMMAND [PATTERNS]]] PERIOD and COMMAND default to "today" and "balance --subtotal" respectively. 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 'from 1/15' # from jan 15 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 a simple curses-based text ui (unix platforms only) ansi an even more rudimentary ansi-based text ui web a simple web interface on port 5000 --depth=N balance report: maximum account depth to show 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 accepts options anywhere on the command line. Instead of - and -- for pattern negation and separation, use ^ and ^^. * hledger always keeps differently-priced amounts of the same commodity separate * hledger calls ledger's "note" field "description" * hledger doesn't require a space before command-line option values, eg: -f- * hledger provides "--cost" as a synonym for "--basis" * hledger's weekly reporting intervals always start on mondays * hledger shows start and end dates of the intervals requested, 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