215 lines
9.1 KiB
Plaintext
215 lines
9.1 KiB
Plaintext
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.
|
|
|
|
You can configure with optional flags to build additional hledger
|
|
features. These are::
|
|
|
|
-f vty - Build vty-based text ui (requires vty, not available on windows)
|
|
-f ansi - Build ansi-based text ui (requires ansi-terminal)
|
|
-f happs - Build happs-based web ui (requires HApps-Server)
|
|
|
|
Eg::
|
|
|
|
cabal install -f "vty ansi happs" hledger (or runhaskell Setup.hs configure -f "vty ansi happs")
|
|
|
|
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 (~/.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,ansi interactive curses and ansi-based text uis
|
|
web rudimentary 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
|
|
* hledger doesn't count an unfinished timelog session
|