216 lines
9.9 KiB
Plaintext
216 lines
9.9 KiB
Plaintext
hledger User's Guide
|
|
====================
|
|
|
|
Welcome to hledger!
|
|
|
|
hledger is a partial haskell clone of John Wiegley's "ledger" command-line
|
|
accounting tool. hledger generates ledger-compatible register & balance
|
|
reports from a plain text ledger file, allows precise batch-mode or
|
|
interactive querying, and demonstrates a pure functional implementation of
|
|
ledger. For more information, see http://hledger.org .
|
|
|
|
Copyright (c) 2007-2009 Simon Michael <simon@joyful.com>
|
|
Released under GPL version 3 or later.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Platform binaries are not yet being published; you could try asking for
|
|
one on the #ledger channel.
|
|
|
|
Building hledger requires GHC 6.8 or later (http://haskell.org/ghc).
|
|
hledger should work on any platform which GHC supports.
|
|
Also, installing hledger's dependencies easily requires cabal-install
|
|
version 0.6 or later (http://www.haskell.org/cabal/download.html).
|
|
Once these tools are installed on your system, do::
|
|
|
|
cabal update
|
|
cabal install hledger [-fvty] [-fhapps]
|
|
|
|
The vty and happs flags are optional; they enable hledger's "ui" and "web"
|
|
commands respectively. vty is not available on the windows platform.
|
|
|
|
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). Basic usage is::
|
|
|
|
hledger [OPTIONS] [COMMAND [PATTERNS]]
|
|
|
|
COMMAND is one of balance, print, register, ui, web, test (defaulting to
|
|
balance). PATTERNS are zero or more regular expressions used to narrow the
|
|
results. Here are some commands to try::
|
|
|
|
export LEDGER=sample.ledger
|
|
hledger --help # show usage & options
|
|
hledger balance # all accounts with aggregated balances
|
|
hledger bal --depth 1 # only top-level accounts
|
|
hledger register # transaction register
|
|
hledger reg income # transactions to/from an income account
|
|
hledger reg checking # checking transactions
|
|
hledger reg desc:shop # transactions with shop in the description
|
|
hledger histogram # transactions per day, or other interval
|
|
hledger ui # interactive ui, if installed with -fvty
|
|
hledger web # web ui, installed with -fhapps
|
|
echo >new; hledger -f new add # input transactions from the command line
|
|
|
|
Time reporting
|
|
--------------
|
|
|
|
hledger will also read timeclock.el-format timelog entries. As a
|
|
convenience, if you invoke hledger via a link or copy named "hours", it
|
|
uses your timelog file (~/.timelog or $TIMELOG) by default.::
|
|
|
|
hours [OPTIONS] [COMMAND [PATTERNS]]
|
|
|
|
Timelog entries look like this::
|
|
|
|
i 2009/03/31 22:21:45 some:project
|
|
o 2009/04/01 02:00:34
|
|
|
|
The clockin description is treated as an account name. Here are some
|
|
queries to try::
|
|
|
|
ln -s `which hledger` ~/bin/hours # add the "hours" symlink in your path
|
|
export TIMELOG=sample.timelog
|
|
hours # time logged today, if any
|
|
hours -p 'last month' # last month
|
|
hours -p thisyear # the space is optional
|
|
hours -p 'from 1/15' register proj # project sessions since last jan 15
|
|
hours -p 'weekly this year' reg --depth 1 # weekly time summary
|
|
|
|
Features
|
|
--------
|
|
|
|
This version of hledger mimics a subset of ledger 3.x, and adds some
|
|
features of its own. We currently support regular ledger entries, timelog
|
|
entries, multiple commodities, virtual transactions, account and
|
|
description patterns, the LEDGER environment variable, and these commands
|
|
and options::
|
|
|
|
Commands:
|
|
balance [REGEXP]... show balance totals for matching accounts
|
|
register [REGEXP]... show register of matching transactions
|
|
print [REGEXP]... print all matching entries
|
|
|
|
Basic options:
|
|
-h, --help show summarized help
|
|
-f, --file FILE read ledger data from FILE
|
|
|
|
Report filtering:
|
|
-b, --begin DATE report on entries on or after this date
|
|
-e, --end DATE report on entries prior to this date
|
|
-p, --period EXPR report on entries during the specified period
|
|
and/or with the specified reporting interval
|
|
-C, --cleared report only on cleared entries
|
|
-R, --real report only on real (non-virtual) transactions
|
|
|
|
Output customization:
|
|
-B, --basis, --cost report cost of commodities
|
|
-d, --display EXPR display only transactions matching EXPR (limited support)
|
|
-E, --empty show empty/zero things which are normally elided
|
|
--no-total balance report: hide the final total
|
|
-W, --weekly register report: show weekly summary
|
|
-M, --monthly register report: show monthly summary
|
|
-Y, --yearly register report: show yearly summary
|
|
|
|
Misc:
|
|
-V, --version show version information
|
|
-v, --verbose show verbose test output
|
|
--debug show some debug output
|
|
--debug-no-ui run ui commands with no output
|
|
|
|
We handle (almost) the full period expression syntax, and very limited
|
|
display expressions consisting of a simple date predicate. Also the
|
|
following new commands are supported::
|
|
|
|
histogram show a (textual) barchart of transaction counts
|
|
add input transactions from the command line
|
|
convert convert CSV bank data to ledger journal format
|
|
ui a simple interactive text ui (only on unix platforms)
|
|
web a simple web ui
|
|
test run self-tests
|
|
|
|
ledger features not supported
|
|
.............................
|
|
|
|
ledger features not currently supported include: modifier and periodic
|
|
entries, and the following options and commands::
|
|
|
|
Basic options:
|
|
-o, --output FILE write output to FILE
|
|
-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc)
|
|
-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 Only show totals in the top-most accounts.
|
|
-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
|
|
--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 calls the "note" field "description"
|
|
* hledger recognises description and negative patterns by "desc:" and "not:" prefixes,
|
|
unlike ledger 3's free-form parser
|
|
* hledger keeps differently-priced amounts of the same commodity separate
|
|
* hledger doesn't require a space before command-line option values, eg: -f-
|
|
* 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 splits multi-day timelog sessions at midnight
|
|
* hledger register report always sorts transactions by date
|
|
* hledger doesn't show description comments as part of the description
|
|
* hledger print puts a blank line after the entry, not before it
|
|
* hledger doesn't print trailing spaces after amount-elided postings
|