slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: update MANUAL.md from latest wiki version

Browse Source
This commit is contained in:
Simon Michael 2014-04-28 14:05:59 -07:00
parent 7d579adb0e
commit 7f2d2e27e8
1 changed files with 211 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
doc/MANUAL.md
View File

@ -1,12 +1,18 @@
<!-- hledger repo and http://hledger.org versions of this document are periodically bidirectionally synced --> <!-- hledger repo and http://hledger.org versions of this document are periodically bidirectionally synced -->
# User manual # User Manual
For: hledger 0.22.1 This manual is for
<!-- [hledger 0.22.1](http://hackage.haskell.org/package/hledger-0.22.1) -->
<!-- (and [hledger-web 0.22.4](http://hackage.haskell.org/package/hledger-web-0.22.4)). -->
hledger 0.22.98 (the latest pre-0.23 HEAD).
<!-- See also: [[0.22/manual|0.22 Manual]]. -->
It is partly an introduction, but mainly a reference manual for hledger.
For a more gradual introduction, see [[step-by-step]] and [[more docs]].
## Introduction ## Introduction
[hledger](http://hledger.org) is a program for tracking money, time, [[home|hledger]] is a program for tracking money, time,
or any other commodity, using a simple, editable file format and or any other commodity, using a simple, editable file format and
double-entry accounting, inspired by and largely compatible with double-entry accounting, inspired by and largely compatible with
[ledger](http://ledger-cli.org). hledger is Free Software released [ledger](http://ledger-cli.org). hledger is Free Software released
@ -32,9 +38,9 @@ latest release with cabal-install, like so:
$ cabal install hledger [hledger-web] $ cabal install hledger [hledger-web]
... ...
$ hledger --version $ hledger --version
hledger 0.19.3 hledger 0.22.1
For more help with this, and other install options, see the [Installation Guide](INSTALL.html). For more help with this, and other install options, see the [[installing|Installation Guide]].
## Basic Usage ## Basic Usage
@ -138,9 +144,7 @@ The posting amounts within a transaction must always balance, ie add up to
Within a journal file, transaction dates always follow a year/month/day Within a journal file, transaction dates always follow a year/month/day
format, although several different separator characters are accepted. Some format, although several different separator characters are accepted. Some
examples: examples: `2010/01/31`, `2010/1/31`, `2010-1-31`, `2010.1.31`.
> `2010/01/31`, `2010/1/31`, `2010-1-31`, `2010.1.31`
Writing the year is optional if you set a default year with a Y directive. Writing the year is optional if you set a default year with a Y directive.
This is a line containing `Y` and the year; it affects subsequent This is a line containing `Y` and the year; it affects subsequent
@ -270,11 +274,17 @@ parse order. This is different from ledger, which currently goes
strictly by parse order. Sorting by date means balance assertions will strictly by parse order. Sorting by date means balance assertions will
still work if you reorder your entries. still work if you reorder your entries.
With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multiple
postings to an account on the same day, split across different files,
and you also want to assert the account's balance on the same day,
you can run into trouble depending on where the assertion is located.
Also note the asserted balance must be a simple amount - it's not Also note the asserted balance must be a simple amount - it's not
currently possible to assert a balance containing multiple commodities. currently possible to assert a balance containing multiple commodities.
The impact of balance assertions on parsing time for large files is The impact of many balance assertions on parsing time for large files is
not yet known. unknown.
#### Prices #### Prices
@ -335,28 +345,28 @@ hledger will parse and ignore ledger-style historical price directives:
#### Comments #### Comments
A semicolon in the journal file marks the start of a comment. You can - A semicolon (`;`) or hash (`#`) in column 0 starts a journal comment line, which hledger will ignore.
write comments on their own line between transactions, like so:
; Also known as a "journal comment". Whitespace before the ; is allowed. - A semicolon after a transaction's description and/or indented on the following lines
starts a transaction comment.
You can also write transaction- or posting-specific comments following the - A semicolon after a posting's amount and/or indented on the following lines starts a posting comment.
transaction's first line or the posting, on the same line and/or indented
on following lines. Some examples:
; a journal comment Transaction and posting comments are displayed by [[#print]], can contain [[#tags]] and can be [[#queries|queried]].
2012/5/14 something ; and now a transaction comment
; another comment for this transaction Some examples:
# a journal comment
; also a journal comment
2012/5/14 something ; a transaction comment
; the transaction comment, continued
posting1 1 ; a comment for posting 1 posting1 1 ; a comment for posting 1
posting2 posting2
; a comment for posting 2 ; a comment for posting 2
; another comment for posting 2 ; another comment line for posting 2
; another journal comment (because not indented) ; a journal comment (because not indented)
Currently `print` preserves transaction and posting comments but not
journal comments.
Comments may contain [tags](#tags).
#### Tags #### Tags
@ -392,24 +402,32 @@ To forget all aliases defined to this point, use:
end aliases end aliases
See also [How to use account aliases](ALIASES.html). You can also specify aliases on the command line:
$ hledger --alias 'my earning=income:business' ...
Journal directive aliases are applied first, then command-line aliases,
and at most one of each will be applied to each account name.
See also [[How to use account aliases]].
##### Default commodity ##### Default commodity
You can set a default commodity, to be used for any subsequent amounts You can set a default commodity, to be used for any subsequent amounts
which have no commodity symbol, with the D directive: which have no commodity symbol (including [[#add|added]] amounts), with the D directive:
; set british pound as default commodity ; set british pound as default commodity
; also sets canonical style for pound amounts, since it's the first one ; also sets canonical style for pound amounts, since it's the first one
; (pound symbol on left, comma thousands separator, two decimal places)
D £1,000.00 D £1,000.00
2010/1/1 2010/1/1
a 2340 ; no symbol, will use pound a 2340 ; no symbol, will use default commodity and style
; (pound symbol on left, comma thousands separator, two decimal places)
b b
A default commodity directive may also influence the canonical A default commodity directive can also influence the
[amount style](#commodity-display-settings) for the commodity. [[#canonical-amount-styles|canonical amount style]] for the commodity,
as in the example above.
##### Default parent account ##### Default parent account
@ -467,8 +485,8 @@ are the journal entry's date and amount:
Lines beginning with `#` or `;` and blank lines are ignored. Lines beginning with `#` or `;` and blank lines are ignored.
The following kinds of rule can appear in any order: The following kinds of rule can appear in any order:
**fields** *CSVFIELDNAME1*, *CSVFIELDNAME1*, ... **fields** *CSVFIELDNAME1*, *CSVFIELDNAME1*, ...\\
: (Field list) This names the CSV fields (names may not contain whitespace or `;` or `#`), (Field list) This names the CSV fields (names may not contain whitespace or `;` or `#`),
and also assigns them to journal entry fields when you use any of these names: and also assigns them to journal entry fields when you use any of these names:
date date
@ -484,16 +502,16 @@ The following kinds of rule can appear in any order:
amount-in amount-in
amount-out amount-out
*JOURNALFIELDNAME* *FIELDVALUE* *JOURNALFIELDNAME* *FIELDVALUE*\\
: (Field assignment) This assigns the given text value (Field assignment) This assigns the given text value
to a journal entry field (one of the field names above). to a journal entry field (one of the field names above).
CSV fields can be referenced with `%CSVFIELDNAME` or `%N` (N starts at 1) and will be interpolated. CSV fields can be referenced with `%CSVFIELDNAME` or `%N` (N starts at 1) and will be interpolated.
You can use a field list, field assignments, or both. You can use a field list, field assignments, or both.
At least the `date` and `amount` fields must be assigned. At least the `date` and `amount` fields must be assigned.
**if** *PATTERNS*<br>&nbsp;&nbsp;*FIELDASSIGNMENTS* **if** *PATTERNS*\\ (*INDENT*)*FIELDASSIGNMENTS*\\
: (Conditional block) This applies the field assignments only to CSV records matched by one of the PATTERNS. (Conditional block) This applies the field assignments only to CSV records matched by one of the PATTERNS.
PATTERNS is one or more regular expressions, each on its own line. PATTERNS is one or more regular expressions, each on its own line.
The first pattern can optionally be written on the same line as The first pattern can optionally be written on the same line as
@ -532,15 +550,15 @@ The following kinds of rule can appear in any order:
account2 expenses:business:banking account2 expenses:business:banking
comment XXX probably deductible, check comment XXX probably deductible, check
**skip** [*N*] **skip** [*N*]\\
: Skip this number of CSV records (1 by default). Skip this number of CSV records (1 by default).
Use this to skip CSV header lines. Use this to skip CSV header lines.
<!-- hledger tries to skip initial CSV header lines automatically. --> <!-- hledger tries to skip initial CSV header lines automatically. -->
<!-- If it guesses wrong, use this directive to skip exactly N lines. --> <!-- If it guesses wrong, use this directive to skip exactly N lines. -->
<!-- This can also be used in a conditional block to ignore certain CSV records. --> <!-- This can also be used in a conditional block to ignore certain CSV records. -->
**date-format** *DATEFMT* **date-format** *DATEFMT*\\
: This is required if the values for `date` or `date2` fields are not in YYYY/MM/DD format (or close to it). This is required if the values for `date` or `date2` fields are not in YYYY/MM/DD format (or close to it).
DATEFMT specifies a strptime-style date parsing pattern containing [year/month/date format codes](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime). DATEFMT specifies a strptime-style date parsing pattern containing [year/month/date format codes](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime).
Note the pattern must parse the CSV date value completely. Some examples: Note the pattern must parse the CSV date value completely. Some examples:
@ -556,8 +574,8 @@ The following kinds of rule can appear in any order:
# "11/6/2013 11:32 PM" # "11/6/2013 11:32 PM"
date-format %-m/%-d/%Y %l:%M %p date-format %-m/%-d/%Y %l:%M %p
**include** *RULESFILE* **include** *RULESFILE*\\
: Include another rules file at this point. Useful for common rules shared across multiple CSV files. Include another rules file at this point. Useful for common rules shared across multiple CSV files.
Typically you'll keep one rules file for each account which you Typically you'll keep one rules file for each account which you
download as CSV. For an example, see [How to read CSV download as CSV. For an example, see [How to read CSV
@ -606,10 +624,10 @@ To generate time logs, ie to clock in and clock out, you could:
and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el) and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el)
- at the command line, use these bash aliases: - at the command line, use these bash aliases:
```
alias ti="echo i \`date '+%Y-%m-%d %H:%M:%S'\` \$* >>$TIMELOG" alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG"
alias to="echo o \`date '+%Y-%m-%d %H:%M:%S'\` >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
```
- or use the old `ti` and `to` scripts in the [ledger 2.x repository](https://github.com/ledger/ledger/tree/maint/scripts). - or use the old `ti` and `to` scripts in the [ledger 2.x repository](https://github.com/ledger/ledger/tree/maint/scripts).
These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed.
@ -759,12 +777,9 @@ an overview:
$ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done $ for y in 2006 2007 2008 2009 2010; do echo; echo $y; hledger -f $y.journal balance ^expenses --depth 2; done
With `--flat`, a non-hierarchical list of full account names is displayed With `--flat`, a simple list of full account names is displayed instead, each with it's inclusive balance (including any subaccount balances).
instead. This mode shows just the accounts actually contributing to the In this mode you can use `--drop N` to elide the first few account name components.
balance, making the arithmetic a little more obvious to non-hledger users. The `--depth` flag also works.
In this mode you can also use `--drop N` to elide the first few account
name components. Note `--depth` doesn't work too well with `--flat` currently;
it hides deeper accounts rather than aggregating them.
With a [reporting interval](#reporting-interval), multiple columns With a [reporting interval](#reporting-interval), multiple columns
will be shown, one for each period. There are three modes available: will be shown, one for each period. There are three modes available:
@ -933,9 +948,9 @@ Examples:
$ hledger-web -E -B --depth 2 -f some.journal $ hledger-web -E -B --depth 2 -f some.journal
$ hledger-web --server --port 5010 --base-url http://some.vhost.com --debug $ hledger-web --server --port 5010 --base-url http://some.vhost.com --debug
\ \\
\ \\
\ \\
The following add-ons are examples and experiments provided in the The following add-ons are examples and experiments provided in the
[extra](https://github.com/simonmichael/hledger/tree/master/extra) [extra](https://github.com/simonmichael/hledger/tree/master/extra)
directory in the hledger source. Add this directory to your PATH to directory in the hledger source. Add this directory to your PATH to
@ -1038,7 +1053,8 @@ The following common features and options work with most subcommands.
Part of hledger's usefulness is being able to report on just a precise subset of your data. Part of hledger's usefulness is being able to report on just a precise subset of your data.
Most commands accept an optional query expression, written as arguments after the command name, Most commands accept an optional query expression, written as arguments after the command name,
to filter the data by date, account name or other criteria. to filter the data by date, account name or other criteria. Query expressions are also used
in the [[#web|web ui]]'s search form.
The query syntax is similar to a Google search expression: one or The query syntax is similar to a Google search expression: one or
more space-separated search terms, optional prefixes to match specific more space-separated search terms, optional prefixes to match specific
@ -1049,61 +1065,50 @@ A query term can be any of the following:
- `acct:REGEX` - same as above - `acct:REGEX` - same as above
- `code:REGEX` - match by transaction code (eg check number) - `code:REGEX` - match by transaction code (eg check number)
- `desc:REGEX` - match transaction descriptions - `desc:REGEX` - match transaction descriptions
- `date:PERIODEXPR` - match dates within the specified [period](#period-expressions) - `date:PERIODEXPR` - match dates within the specified [[#period-expressions|period]]. *Actually, full period syntax is [[https://github.com/simonmichael/hledger/issues/141|not yet supported]].*
- `date2:PERIODEXPR` - as above, but match secondary dates - `date2:PERIODEXPR` - as above, but match secondary dates
- `tag:NAME[=REGEX]` - match by (exact, case sensitive) [tag](#tags) name, and optionally match the tag value by regular expression - `tag:NAME[=REGEX]` - match by (exact, case sensitive) [[#tags|tag]] name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match posting if it or its parent transaction has the tag.
- `depth:N` - match (or display, depending on command) accounts at or above this [depth](#depth-limiting) - `depth:N` - match (or display, depending on command) accounts at or above this [[#depth-limiting|depth]]
- `status:1` or `status:0` - match cleared/uncleared transactions - `status:1` or `status:0` - match cleared/uncleared transactions
- `real:1` or `real:0` - match real/virtual-ness - `real:1` or `real:0` - match real/virtual-ness
- `empty:1` or `empty:0` - match if amount is/is not zero - `empty:1` or `empty:0` - match if amount is/is not zero
- `amt:N` or `amt:=N`, `amt:<N`, `amt:>N` - match postings with a - `amt:N` or `amt:=N`, `amt:<N`, `amt:>N` - match postings with a
single-commodity amount equal to, less than, or greater than single-commodity amount equal to, less than, or greater than N.
N. (Multi-commodity amounts are always matched.) Be warned, the (Multi-commodity amounts are not tested, and always match.)
match is sensitive to the sign of N - this can be used to search for This has two modes of operation: if N is preceded by a `+` or `-` sign, the
inflows or outflows. actual signed numbers are compared; otherwise the unsigned absolute values are compared.
- `sym:REGEX` - match postings or transactions including any amounts - `cur:REGEX` - match postings or transactions including any amounts
whose commodity symbol is fully matched by REGEX. (For a partial whose currency/commodity symbol is fully matched by REGEX. (For a
match, use `.*REGEX.*`). To match the dollar sign (`$`): you partial match, use `.*REGEX.*`). Note, to match characters which are
need to prepend `\` so it's not interpreted as a regular regex-significant, like the dollar sign (`$`), you need to prepend `\`.
expression metacharacter, at the command line you need one more level And when using the command line you need to add one more level
of quoting to hide it from the shell, so eg do: `hledger print sym:'\$'`. of quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
To strictly limit reports to a single commodity, it may work better or `hledger print cur:\\$`.
to exclude the others, eg: `hledger bal not:sym:'(EUR|¥|£)'.
- `not:` before any of the above negates the match - `not:` before any of the above negates the match
<!-- #### How query terms combine
- `TAGNAME:[TAGVALUEREGEX]` - match a tag name exactly, and optionally
the value by regular expression.
- `code:CODEREGEX`
- `type:regular|virtual|balancedvirtual`
- `comment:COMMENTREGEX`
- `amount:AMOUNTEXPR`
- `commodity:COMMODITYSYMBOLREGEX`
Any of these can be prefixed with `not:` or `!` to negate the match.
-->
Multiple query terms will select transactions/postings/accounts which match hledger query expressions don't support full boolean logic. Instead, multiple query terms
(or negatively match) are combined as follows:
> *any of the description terms AND* - The [[#print]] command selects transactions which:
> *any of the account terms AND* - match any of the description terms AND
> *all the other terms* - have any postings matching any of the positive account terms AND
- have no postings matching any of the negative account terms AND
- match all the other terms.
<!-- -->
- Other reporting commands (eg [[#register]] and [[#balance]]) select transactions/postings/accounts which match (or negatively match):
- any of the description terms AND
- any of the account terms AND
- all the other terms.
#### Query options vs query arguments
With the [print](#print) command, they select transactions which On the command line, some of the query terms above can also be expressed as command-line flags.
Generally you can mix and match query arguments and flags, and the resulting query will be their intersection. Note within the command-line flags, a `-p` [[#period-expressions|period]] flag causes any `-b` or `-e` flags, and any preceding `-p` flags, to be ignored.
> *match any of the description terms AND*
> *have any postings matching any of the positive account terms AND*
> *have no postings matching any of the negative account terms AND*
> *match all the other terms*
Many of the query terms above have equivalent command-line flags which predate them.
You can mix and match query arguments and flags, just note that a
[period expression](#period-expressions) overrides any other date terms.
The same query syntax should work in both the command line and [web](#web) interfaces.
### Smart dates ### Smart dates
@ -1292,15 +1297,15 @@ Here are some issues you might encounter when you run hledger
[mail list](http://hledger.org/list) or [mail list](http://hledger.org/list) or
[bug tracker](http://hledger.org/bugs)): [bug tracker](http://hledger.org/bugs)):
#. **hledger installed, but running hledger says something like No command 'hledger' found** ### Successfully installed, but "No command 'hledger' found"
cabal installs binaries into a special directory, which should be added cabal installs binaries into a special directory, which should be added
to your PATH environment variable. On unix-like systems, it is to your PATH environment variable. On unix-like systems, it is
~/.cabal/bin. ~/.cabal/bin.
#. **hledger fails to parse some valid ledger files** ### Fails to parse some valid Ledger files
See [file format differences](FAQ.html#what-are-the-file-format-differences). See [[faq#file-format-differences|file format differences]].
#. **hledger gives "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors** ### "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors
In order to handle non-ascii letters and symbols (like £), hledger needs In order to handle non-ascii letters and symbols (like £), hledger needs
an appropriate locale. This is usually configured system-wide; you can an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that also configure it temporarily. The locale may need to be one that
@ -1339,3 +1344,4 @@ Here are some issues you might encounter when you run hledger
Note some platforms allow variant locale spellings, but not all (ubuntu Note some platforms allow variant locale spellings, but not all (ubuntu
accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`). accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).