mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-20 02:37:12 +03:00
docs: flesh out the manual
This commit is contained in:
parent
a24c8533ac
commit
03bb71a055
362
MANUAL
362
MANUAL
@ -4,20 +4,27 @@ hledger manual
|
||||
This is the official hledger manual. You may also want to visit
|
||||
the http://hledger.org home page,
|
||||
the `hledger for techies`_ page,
|
||||
and perhaps `c++ ledger's manual`_.
|
||||
(Tip: on hledger.org, docs are also available with .pdf suffix.)
|
||||
and perhaps `c++ ledger's manual`_ (but don't worry, we'll link to that below.)
|
||||
|
||||
A tip: on hledger.org, these docs are also available with .pdf suffix.
|
||||
|
||||
User Guide
|
||||
----------
|
||||
|
||||
Introduction
|
||||
------------
|
||||
............
|
||||
|
||||
hledger is a program for tracking money, time, or other commodities using standard accounting principles.
|
||||
It was inspired by John Wiegley's "ledger" project, which I used and admired.
|
||||
I wrote hledger because I wanted to build financial tools in the Haskell
|
||||
programming language rather than C++.
|
||||
hledger is a program for tracking money, time, or any other commodity,
|
||||
using a plain text file format and the simple but powerful principles of
|
||||
double-entry accounting.
|
||||
|
||||
hledger's basic function is to generate register and balance reports
|
||||
from a plain text ledger file, at the command line or via the web or
|
||||
curses interface. You can use it to, eg,
|
||||
It is modelled closely on `John Wiegley's ledger`_ (aka "c++ ledger"),
|
||||
with some new features added. I wrote hledger because I wanted to build
|
||||
financial tools in the Haskell programming language rather than in C++.
|
||||
|
||||
hledger's basic function is to generate register and balance reports from
|
||||
a plain text ledger file, at the command line or via the web or curses
|
||||
interface. You can use it to, eg,
|
||||
|
||||
- track spending and income
|
||||
- see time reports by day/week/month/project
|
||||
@ -30,9 +37,6 @@ For now though, it is most useful to technically-minded folks who are comfortabl
|
||||
hledger is copyright (c) 2007-2009 Simon Michael <simon@joyful.com> and
|
||||
contributors and released as Free Software under GPL version 3 or later.
|
||||
|
||||
User Guide
|
||||
----------
|
||||
|
||||
Installing
|
||||
..........
|
||||
|
||||
@ -44,7 +48,7 @@ If not, please report the problem, then install the `Haskell Platform`_ and type
|
||||
cabal install hledger [-fvty] [-fhapps]
|
||||
|
||||
The optional -f flags will download more stuff and include the "ui" and
|
||||
"web" commands respectively. -fvty will not work on microsoft windows.
|
||||
"web" commands respectively. Note -fvty may not work on microsoft windows.
|
||||
|
||||
Basic usage
|
||||
...........
|
||||
@ -57,7 +61,8 @@ option (which may be - for standard input). Basic usage is::
|
||||
|
||||
COMMAND is one of balance, print, register, ui, web, test (defaulting to
|
||||
balance). PATTERNS are zero or more regular expressions used to filter by
|
||||
account name or transaction description. Here are some commands to try::
|
||||
account name or transaction description. Here are some commands to try
|
||||
(after downloading sample.ledger_)::
|
||||
|
||||
export LEDGER=sample.ledger
|
||||
hledger --help # show usage & options
|
||||
@ -72,31 +77,6 @@ account name or transaction description. Here are some commands to try::
|
||||
hledger web # web ui, if installed with -fhapps
|
||||
hledger -f new.ledger add # record transactions from the command line
|
||||
|
||||
Time reporting
|
||||
..............
|
||||
|
||||
hledger will also read timelog files in timeclock.el format. If you
|
||||
invoke hledger via a symlink or copy named "hours", it looks for 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 # set up "hours" in your path
|
||||
export TIMELOG=sample.timelog
|
||||
hours # show all time balances
|
||||
hours -p 'last week' # last week
|
||||
hours -p thismonth # the space is optional
|
||||
hours -p 'from 1/15' register project # project sessions since jan 15
|
||||
hours -p 'weekly' reg --depth 1 -E # weekly time summary
|
||||
|
||||
Reference
|
||||
---------
|
||||
|
||||
@ -105,60 +85,185 @@ Feature overview
|
||||
|
||||
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, price history for fixed-rate transactions,
|
||||
virtual postings, filtering by account and description, and these commands
|
||||
and options::
|
||||
entries, multiple commodities, price history (for fixed-rate
|
||||
transactions), virtual postings, filtering by account and description, the
|
||||
familiar print, register & balance commands and several new commands. We
|
||||
handle (almost) the full period expression syntax, and very limited
|
||||
display expressions consisting of a simple date predicate.
|
||||
|
||||
Commands:
|
||||
balance [REGEXP]... show balance totals for matching accounts
|
||||
register [REGEXP]... show register of matching transactions
|
||||
print [REGEXP]... print all matching entries
|
||||
Here is the command-line help::
|
||||
|
||||
Basic options:
|
||||
-h, --help show summarized help
|
||||
-f, --file FILE read ledger data from FILE
|
||||
$ hledger --help
|
||||
Usage: hledger [OPTIONS] [COMMAND [PATTERNS]]
|
||||
hours [OPTIONS] [COMMAND [PATTERNS]]
|
||||
hledger convert CSVFILE
|
||||
|
||||
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
|
||||
hledger uses your ~/.ledger or $LEDGER file (or another specified with -f),
|
||||
while hours uses your ~/.timelog or $TIMELOG file.
|
||||
|
||||
COMMAND is one of (may be abbreviated):
|
||||
add - prompt for new transactions and add them to the ledger
|
||||
balance - show accounts, with balances
|
||||
convert - read CSV bank data and display in ledger format
|
||||
histogram - show a barchart of transactions per day or other interval
|
||||
print - show transactions in ledger format
|
||||
register - show transactions as a register with running balance
|
||||
stats - show various statistics for a ledger
|
||||
ui - run a simple text-based UI
|
||||
web - run a simple web-based UI
|
||||
test - run self-tests
|
||||
|
||||
PATTERNS are regular expressions which filter by account name.
|
||||
Prefix with desc: to filter by transaction description instead.
|
||||
Prefix with not: to negate a pattern. When using both, not: comes last.
|
||||
|
||||
DATES can be y/m/d or ledger-style smart dates like "last month".
|
||||
|
||||
Options:
|
||||
-f FILE --file=FILE use a different ledger/timelog file; - means stdin
|
||||
-b DATE --begin=DATE report on transactions on or after this date
|
||||
-e DATE --end=DATE report on transactions before this date
|
||||
-p EXPR --period=EXPR report on transactions during the specified period
|
||||
and/or with the specified reporting interval
|
||||
-C, --cleared report only on cleared entries
|
||||
-U, --uncleared consider only uncleared transactions
|
||||
-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
|
||||
-C --cleared report only on cleared transactions
|
||||
-U --uncleared report only on uncleared transactions
|
||||
-B --cost, --basis report cost of commodities
|
||||
--depth=N hide accounts/transactions deeper than this
|
||||
-d EXPR --display=EXPR show only transactions matching EXPR (where
|
||||
EXPR is 'dOP[DATE]' and OP is <, <=, =, >=, >)
|
||||
--effective use transactions' effective dates, if any
|
||||
-E --empty show empty/zero things which are normally elided
|
||||
-R --real report only on real (non-virtual) transactions
|
||||
--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
|
||||
-W --weekly register report: show weekly summary
|
||||
-M --monthly register report: show monthly summary
|
||||
-Q --quarterly register report: show quarterly summary
|
||||
-Y --yearly register report: show yearly summary
|
||||
-h --help show this help
|
||||
-V --version show version information
|
||||
-v --verbose show verbose test output
|
||||
--binary-filename show the download filename for this hledger build
|
||||
--debug show extra debug output; implies verbose
|
||||
--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::
|
||||
File format
|
||||
...........
|
||||
|
||||
add prompt for new transactions and add them to the ledger
|
||||
convert read CSV bank data and display in ledger format
|
||||
histogram show a barchart of transactions per day or other interval
|
||||
ui run a simple text-based UI (only on unix platforms)
|
||||
web run a simple web-based UI
|
||||
stats show various statistics for a ledger
|
||||
test run self-tests
|
||||
hledger's data file (aka "the ledger") is a readable plain text
|
||||
representation of an accounting journal. The format is mostly identical
|
||||
with c++ ledger's. Here's an example::
|
||||
|
||||
; A sample ledger file.
|
||||
|
||||
2008/01/01 income
|
||||
assets:bank:checking $1
|
||||
income:salary
|
||||
|
||||
2008/06/01 gift
|
||||
assets:bank:checking $1
|
||||
income:gifts
|
||||
|
||||
2008/06/02 save
|
||||
assets:bank:saving $1
|
||||
assets:bank:checking
|
||||
|
||||
2008/06/03 * eat & shop
|
||||
expenses:food $1
|
||||
expenses:supplies $1
|
||||
assets:cash
|
||||
|
||||
2008/12/31 * pay off
|
||||
liabilities:debts $1
|
||||
assets:bank:checking
|
||||
|
||||
Each transaction has a date, description, and two or more postings (of
|
||||
some amount to some account) which must balance to 0. As a convenience,
|
||||
the last posting's amount may be left blank and will be inferred.
|
||||
|
||||
Other c++ ledger features like effective dates, comments, and prices
|
||||
are also supported. Some additional features like modifier and periodic
|
||||
entries are accepted, but ignored.
|
||||
|
||||
Compatibility
|
||||
"""""""""""""
|
||||
|
||||
Compared to c++ ledger, hledger's file format has some omissions (we do
|
||||
not support all the latest ledger 3 syntax like @@ and {}) and some subtle
|
||||
punctuation differences (eg comments may be permissible in different
|
||||
places.)
|
||||
|
||||
As long as you avoid the more esoteric syntax, your ledger files should
|
||||
work with both hledger and c++ ledger. You can inadvertently create a file
|
||||
that works for one but not the other; but it's easy to restore
|
||||
compatibility by making small adjustments.
|
||||
|
||||
Commands
|
||||
........
|
||||
|
||||
Convert
|
||||
,,,,,,,
|
||||
Reporting commands
|
||||
""""""""""""""""""
|
||||
|
||||
print
|
||||
'''''
|
||||
|
||||
The print command displays full transactions from the ledger file, tidily
|
||||
formatted and showing all amounts explicitly. The output of print is
|
||||
always valid ledger data.
|
||||
|
||||
hledger's print command also shows all unit prices in effect, or
|
||||
(with -B/--cost) shows cost amounts.
|
||||
|
||||
register
|
||||
''''''''
|
||||
|
||||
The register command displays postings, one per line, and their running total.
|
||||
|
||||
balance
|
||||
'''''''
|
||||
|
||||
The balance command displays accounts and their balances.
|
||||
|
||||
histogram
|
||||
'''''''''
|
||||
|
||||
The histogram command displays a quick bar chart showing transaction
|
||||
counts, per day, week, month or other reporting interval. It is
|
||||
experimental.
|
||||
|
||||
stats
|
||||
'''''
|
||||
|
||||
The stats command displays quick summary information for the ledger.
|
||||
|
||||
ui
|
||||
'''
|
||||
|
||||
The ui command starts hledger's text-based "curses" interface, which
|
||||
allows interactive navigation of the print/register/balance reports.
|
||||
|
||||
Modifying commands
|
||||
""""""""""""""""""
|
||||
|
||||
add
|
||||
'''
|
||||
|
||||
The add command prompts interactively for new transactions, and adds them
|
||||
to the ledger. It is experimental.
|
||||
|
||||
web
|
||||
'''
|
||||
|
||||
The web command starts hledger's web interface, and tries to open a web
|
||||
browser to view it (if this fails, you'll have to visit the indicated url
|
||||
yourself.) The web ui combines the features of the print, register,
|
||||
balance and add commands. It is experimental.
|
||||
Known issues: filtering does not work completely.
|
||||
|
||||
Other commands
|
||||
""""""""""""""
|
||||
|
||||
convert
|
||||
'''''''
|
||||
|
||||
The convert command reads a CSV_ file you have downloaded from your bank,
|
||||
and prints out the transactions in ledger format, suitable for adding to
|
||||
@ -170,19 +275,20 @@ Use it like this::
|
||||
|
||||
hledger convert FILE.csv >FILE.ledger
|
||||
|
||||
This will convert the csv data in FILE.csv, using conversion rules defined
|
||||
in FILE.rules, and save the output into a temporary ledger file. If
|
||||
FILE.rules does not exist it will be created. Then you should review
|
||||
FILE.ledger for problems; update the rules and convert again if needed;
|
||||
and finally copy/paste transactions which are new into your main ledger.
|
||||
where FILE.csv is your downloaded csv file. This will convert the csv data
|
||||
using conversion rules defined in FILE.rules (auto-creating this file if
|
||||
needed), and save the output into a temporary ledger file. Then you
|
||||
should review FILE.ledger for problems; update the rules and convert again
|
||||
if needed; and finally copy/paste transactions which are new into your
|
||||
main ledger.
|
||||
|
||||
rules file
|
||||
''''''''''
|
||||
Rules file
|
||||
,,,,,,,,,,
|
||||
|
||||
A .rules file contains some data definitions and some rules for assigning
|
||||
destination accounts to transactions. Typically you will have one csv file
|
||||
and corresponding rules file per bank account. Here's an example rules
|
||||
file for converting the csv download from a Wells Fargo checking account::
|
||||
and one rules file per bank account. Here's an example rules file for
|
||||
converting csv data from a Wells Fargo checking account::
|
||||
|
||||
base-account assets:bank:checking
|
||||
date-field 0
|
||||
@ -232,12 +338,18 @@ Notes:
|
||||
Otherwise the matched part of the csv description is used. (To preserve
|
||||
the full csv description, use .* before and after the match pattern.)
|
||||
|
||||
test
|
||||
''''
|
||||
|
||||
This command runs hledger's internal self-tests and displays a quick report.
|
||||
|
||||
Smart dates
|
||||
...........
|
||||
|
||||
hledger accepts "smart dates" in most places a date can be used, such as:
|
||||
transaction dates, effective dates, -b and -e options, and `period
|
||||
expressions <#period-expressions>`_. Here are some valid hledger dates:
|
||||
-b and -e options, and `period expressions <#period-expressions>`_
|
||||
(but actually, not in the ledger file, which has more limited date parsing.)
|
||||
Here are some examples:
|
||||
|
||||
- 2009/1/1, 2009/01/01, 2009-1-1, 2009.1.1, 2009/1, 2009 (january 1, 2009)
|
||||
- 1/1, january, jan, this year (january 1, this year)
|
||||
@ -287,6 +399,9 @@ A single date with no "from" or "to" defines both the start and end date like so
|
||||
-p "2009/1" (the month of jan; equivalent to "2009/1/1 to 2009/2/1")
|
||||
-p "2009/1/1" (just that day; equivalent to "2009/1/1 to 2009/1/2")
|
||||
|
||||
Reporting interval
|
||||
''''''''''''''''''
|
||||
|
||||
You can also specify a reporting interval, which causes the "register"
|
||||
command to summarise the transactions in each interval. It goes before the
|
||||
dates, and can be: "daily", "weekly", "monthly", "quarterly", or
|
||||
@ -297,6 +412,14 @@ dates, and can be: "daily", "weekly", "monthly", "quarterly", or
|
||||
-p "monthly from 2008"
|
||||
-p "quarterly"
|
||||
|
||||
A reporting interval may also be specified with the -W/--weekly,
|
||||
-M/--monthly, -Q/--quarterly, and -Y/--yearly options. However..
|
||||
|
||||
-p overrides other flags
|
||||
''''''''''''''''''''''''
|
||||
|
||||
A period option on the command line will override any -b/-e/-W/-Q/-Y flags.
|
||||
|
||||
Display expressions
|
||||
...................
|
||||
|
||||
@ -339,17 +462,38 @@ The print command shows all conversion rates in effect. Otherwise, rates
|
||||
are not shown, but you can use the ``--cost`` or ``-B`` flag with any
|
||||
report to convert all amounts to their total cost price.
|
||||
|
||||
Tips
|
||||
----
|
||||
Timelog reporting
|
||||
.................
|
||||
|
||||
- when writing a negative amount with a left-side currency symbol, the
|
||||
minus goes after the symbol. Eg ``$-1`` not ``-$1``
|
||||
hledger will also read timelog files in timeclock.el format. As a
|
||||
convenience, if you invoke hledger via an "hours" symlink or copy, it uses
|
||||
your timelog file (~/.timelog or $TIMELOG) by default, rather than your ledger.
|
||||
|
||||
- when combining desc: and not: in a filter pattern, not: goes last. Eg
|
||||
``desc:not:...`` not ``not:desc:...``.
|
||||
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 (after downloading sample.timelog_)::
|
||||
|
||||
ln -s `which hledger` ~/bin/hours # set up "hours" in your path
|
||||
export TIMELOG=sample.timelog
|
||||
hours # show all time balances
|
||||
hours -p 'last week' # last week
|
||||
hours -p thismonth # the space is optional
|
||||
hours -p 'from 1/15' register project # project sessions since jan 15
|
||||
hours -p 'weekly' reg --depth 1 -E # weekly time summary
|
||||
|
||||
This is a useful feature, if you can find a way to efficiently record
|
||||
timelog entries. The "ti" and "to" scripts may be available from the c++
|
||||
ledger 2.x repository. I use
|
||||
`timeclock-x.el <http://www.emacswiki.org/emacs/timeclock-x.el>`_ and
|
||||
`ledgerutils.el <http://joyful.com/repos/ledgertools/ledgerutils.el>`_
|
||||
in emacs.
|
||||
|
||||
Differences from c++ ledger
|
||||
---------------------------
|
||||
...........................
|
||||
|
||||
hledger is written in the Haskell programming language. Haskell enables a
|
||||
coding style known as pure lazy functional programming, which holds the
|
||||
@ -357,7 +501,7 @@ promise of more robust and maintainable software built with fewer lines of
|
||||
code.
|
||||
|
||||
Features not supported
|
||||
......................
|
||||
''''''''''''''''''''''
|
||||
|
||||
ledger features not currently supported include: modifier and periodic
|
||||
entries, and the following options and commands::
|
||||
@ -419,7 +563,7 @@ entries, and the following options and commands::
|
||||
entry DATE PAYEE AMT output a derived entry, based on the arguments
|
||||
|
||||
Other differences
|
||||
.................
|
||||
'''''''''''''''''
|
||||
|
||||
* hledger recognises description and negative patterns by "desc:" and "not:" prefixes,
|
||||
unlike ledger 3's free-form parser
|
||||
@ -432,10 +576,22 @@ Other differences
|
||||
* hledger doesn't track the value of commodities with varying price;
|
||||
prices are fixed as of the transaction date
|
||||
|
||||
Tips
|
||||
....
|
||||
|
||||
- when writing a negative amount with a left-side currency symbol, the
|
||||
minus goes after the symbol. Eg ``$-1`` not ``-$1``
|
||||
|
||||
- when combining desc: and not: in a filter pattern, not: goes last. Eg
|
||||
``desc:not:...`` not ``not:desc:...``.
|
||||
|
||||
|
||||
|
||||
.. _hledger for techies: README2.html
|
||||
.. _c++ ledger's manual: http://joyful.com/repos/ledger/doc/ledger.html
|
||||
.. _John Wiegley's ledger: http://wiki.github.com/jwiegley/ledger
|
||||
.. _sample.ledger: http://joyful.com/repos/hledger/sample.ledger
|
||||
.. _sample.timelog: http://joyful.com/repos/hledger/sample.timelog
|
||||
.. _binaries: http://hledger.org/binaries/
|
||||
.. _Haskell Platform: http://hackage.haskell.org/platform/
|
||||
.. _CSV: http://en.wikipedia.org/wiki/Comma-separated_values
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user