mirror of
https://github.com/simonmichael/hledger.git
synced 2024-11-07 21:15:19 +03:00
214 lines
9.1 KiB
Plaintext
214 lines
9.1 KiB
Plaintext
hledger - a ledger-compatible text-based accounting tool
|
|
========================================================
|
|
|
|
Welcome to hledger!
|
|
|
|
hledger is a limited 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,
|
|
provides simple interactive querying, and demonstrates a 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
|
|
------------
|
|
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 webserver ui
|
|
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 balance --depth 1
|
|
hledger register
|
|
hledger reg income
|
|
hledger reg desc:shop
|
|
hledger ui
|
|
|
|
|
|
Time reporting
|
|
--------------
|
|
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 timelog querying::
|
|
|
|
hours [OPTIONS] [PERIOD [COMMAND [PATTERNS]]]
|
|
|
|
where PERIOD and COMMAND are "today" and "balance" by default.
|
|
The timelog file is in timeclock.el's format, where an entry looks like::
|
|
|
|
i 2009/03/31 22:21:45 work:hledger
|
|
o 2009/04/01 02:00:34
|
|
|
|
Time categories are treated as accounts. Here are some time queries to try::
|
|
|
|
export TIMELOG=/my/timelog # if not ~/.timelog
|
|
hours # today's balances
|
|
hours today # the same
|
|
hours 'this week' # so far this week
|
|
hours lastmonth # the space is optional
|
|
hours 'from 1/15' register # sessions since last january 15
|
|
hours 'monthly in 2009' reg --depth 1 # monthly time summary, top level only
|
|
|
|
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::
|
|
|
|
ui a simple curses-based text ui (on windows, ansi-based)
|
|
web a simple web-based ui
|
|
test run self-tests
|
|
|
|
ledger features not supported
|
|
.............................
|
|
|
|
ledger features not currently supported include: modifier and periodic
|
|
entries, and options such as these::
|
|
|
|
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
|