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

doc: merge latest manual changes from wiki

Browse Source
This commit is contained in:
Simon Michael 2014-08-08 18:39:37 -07:00
parent aa85e786b9
commit 0ad24be353
1 changed files with 426 additions and 333 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

757
doc/MANUAL.md
View File

@ -1,14 +1,21 @@
<!-- hledger.org and hledger repo versions last synced: 2014/5/1 --> <!-- hledger.org and hledger repo versions last synced: 2014/5/1 -->
# User Manual # hledger User Manual
This manual is for This reference manual is for
<!-- hledger 0.23.98 (the latest pre-0.23 HEAD). --> hledger 0.23.98 (the latest pre-0.24 HEAD).
[hledger 0.23](http://hackage.haskell.org/package/hledger-0.23). <!-- [hledger 0.23](http://hackage.haskell.org/package/hledger-0.23) -->
and [hledger-web 0.23](http://hackage.haskell.org/package/hledger-web-0.23).
<!-- Other versions: [[0.22/manual|0.22 Manual]]. --> <!-- Other versions: [[0.22/manual|0.22 Manual]]. -->
It is partly an introduction, but mainly a reference manual for hledger. - [[#Introduction]]
For a more gradual introduction, see [[step-by-step]] and [[more docs]]. - [[#Usage]]
- [[#Data format]]
- [[#Options]]
- [[#Query arguments]]
- [[#Commands]]
- [[#Known limitations]]
- [[#Troubleshooting]]
## Introduction ## Introduction
@ -42,7 +49,7 @@ latest release with cabal-install, like so:
For more help with this, and other install options, see the [[installing|Installation Guide]]. For more help with this, and other install options, see the [[installing|Installation Guide]].
## Basic Usage ## Usage
Basic usage is: Basic usage is:
@ -57,7 +64,7 @@ Options are similar across most commands, with some variations; use
`hledger COMMAND --help` for details. Most options must appear `hledger COMMAND --help` for details. Most options must appear
somewhere after COMMAND, not before it. These input and help-related somewhere after COMMAND, not before it. These input and help-related
options can appear anywhere: `-f`, `--rules-file`, `--alias`, options can appear anywhere: `-f`, `--rules-file`, `--alias`,
`--help`, `--debug`, `--version`. `--ignore-assertions`, `--help`, `--debug`, `--version`.
Arguments are also command-specific, but usually they form a Arguments are also command-specific, but usually they form a
[query](#queries) which selects a subset of the journal, eg transactions [query](#queries) which selects a subset of the journal, eg transactions
@ -68,16 +75,16 @@ enter some transactions. Or, save this
[sample file](https://raw.github.com/simonmichael/hledger/master/data/sample.journal) as [sample file](https://raw.github.com/simonmichael/hledger/master/data/sample.journal) as
`.hledger.journal` in your home directory. Now try commands like these: `.hledger.journal` in your home directory. Now try commands like these:
$ hledger # show available commands $ hledger # show available commands
$ hledger add # add more transactions to the journal file $ hledger add # add more transactions to the journal file
$ hledger balance # all accounts with aggregated balances $ hledger balance # all accounts with aggregated balances
$ hledger balance --help # show help for balance command $ hledger balance --help # show help for balance command
$ hledger balance --depth 1 # only top-level accounts $ hledger balance --depth 1 # only top-level accounts
$ hledger register # show a register of postings from all transactions $ hledger register # show a register of postings from all transactions
$ hledger reg income # show postings to/from income accounts $ hledger reg income # show postings to/from income accounts
$ hledger reg checking # show postings to/from checking account $ hledger reg checking # show postings to/from checking account
$ hledger reg desc:shop # show postings with shop in the description $ hledger reg desc:shop # show postings with shop in the description
$ hledger activity # show transactions per day as a bar chart $ hledger activity # show transactions per day as a bar chart
## Data format ## Data format
@ -90,7 +97,7 @@ The journal file contains a number of transaction entries,
each describing a transfer of money (or any commodity) between two or more named accounts, each describing a transfer of money (or any commodity) between two or more named accounts,
in a simple format readable by both hledger and humans. in a simple format readable by both hledger and humans.
hledger's journal format is a compatible subset, mostly, hledger's journal format is a compatible subset, [mostly](http://hledger.org/faq#file-format-differences),
of [ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), of [ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format),
so hledger can work with [compatible](FAQ.html#what-are-the-file-format-differences) ledger journal files as well. so hledger can work with [compatible](FAQ.html#what-are-the-file-format-differences) ledger journal files as well.
It's safe, and encouraged, to run both hledger and ledger on the same journal file, It's safe, and encouraged, to run both hledger and ledger on the same journal file,
@ -231,7 +238,7 @@ digit group separators, you must also include a decimal point in at least
one number in the same commodity, so that hledger knows which character is one number in the same commodity, so that hledger knows which character is
which. Eg, write `$1,000.00` or `$1.000,00`. which. Eg, write `$1,000.00` or `$1.000,00`.
##### Canonical amount styles ##### Amount display styles
Based on how you format amounts, hledger will infer canonical display Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that styles for each commodity, and use these when displaying amounts in that
@ -242,9 +249,8 @@ commodity. Amount styles include:
- the decimal point character (period or comma) - the decimal point character (period or comma)
- the display precision (number of decimal places displayed) - the display precision (number of decimal places displayed)
The canonical style is generally the style of the first amount seen in a commodity The canonical style is generally the style of the first posting amount seen in a commodity
(which may be in a [default commodity directive](#default-commodity). The precision is the highest precision seen among all posting amounts in the commmodity.
The precision is the highest precision seen among all amounts in the commmodity.
##### Balance Assertions ##### Balance Assertions
@ -252,7 +258,7 @@ hledger supports ledger-style
[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions) [balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions)
in journal files. in journal files.
These look like `=EXPECTEDBALANCE` following a posting's amount. Eg in These look like `=EXPECTEDBALANCE` following a posting's amount. Eg in
this example we assert the expected balance in accounts a and b after this example we assert the expected dollar balance in accounts a and b after
each posting: each posting:
2013/1/1 2013/1/1
@ -266,25 +272,48 @@ each posting:
After reading a journal file, hledger will check all balance After reading a journal file, hledger will check all balance
assertions and report an error if any of them fail. Balance assertions assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. while cleaning up old entries. You can disable them temporarily with
the `--ignore-assertions` flag, which can be useful for
troubleshooting or for reading Ledger files.
Note, when checking balance assertions hledger sorts the account's ###### Assertions and ordering
postings first by date and then (for postings with the same date) by
parse order. This is different from ledger, which currently goes
strictly by parse order. Sorting by date means balance assertions will
still work if you reorder your entries.
With included files, things are a little more complicated. Including hledger sorts an account's postings and assertions first by date and
preserves the ordering of postings and assertions. If you have multiple then (for postings on the same day) by parse order. Note this is
postings to an account on the same day, split across different files, different from Ledger, which sorts assertions only by parse
and you also want to assert the account's balance on the same day, order. (Also, Ledger assertions do not see the accumulated effect of
you can run into trouble depending on where the assertion is located. repeated postings to the same account within a transaction.)
Also note the asserted balance must be a simple amount - it's not So, hledger balance assertions keep working if you reorder
currently possible to assert a balance containing multiple commodities. differently-dated transactions within the journal. But if you reorder
same-dated transactions or postings, assertions might break and require
updating. This order dependence does bring an advantage: precise
control over the order of postings and assertions within a day, so you
can assert intra-day balances.
With [[#including-other-files|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'll have to put the assertion
in the right file.
###### Assertions and commodities
The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. We could call this a
partial balance assertion. This is compatible with Ledger, and makes
it possible to make assertions about accounts containing multiple
commodities.
To assert each commodity's balance in such a multi-commodity account,
you can add multiple postings (with amount 0 if necessary). But note
that no matter how many assertions you add, you can't be sure the
account does not contain some unexpected commodity. (We'll add support
for this kind of total balance assertion if there's demand.)
The impact of many balance assertions on parsing time for large files is
unknown.
#### Prices #### Prices
@ -413,21 +442,35 @@ 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 amounts without one.
which have no commodity symbol (including [[#add|added]] amounts), with the D directive: Use the D directive with a sample amount.
The commodity (and the sample amount's display style) will be applied to all subsequent commodity-less amounts, up to the next D directive.
(Note this is different from Ledger's default commodity directive.)
; set british pound as default commodity Also note the directive itself does not influence the commodity's default
; also sets canonical style for pound amounts, since it's the first one [[#amount-display-styles|display style]], but the amount it is
applied to might. Here's an example:
; set £ as the default commodity
D £1,000.00 D £1,000.00
2010/1/1 2010/1/1
a 2340 ; no symbol, so will use the default commodity above, and its style a 2340
; (pound symbol on left, comma thousands separator, at least two decimal places)
b b
A default commodity directive can also influence the 2014/1/1
[[#canonical-amount-styles|canonical amount style]] for the commodity, c £1000
as in the example above. d
$ hledger print
2010/01/01
a £2,340.00
b £-2,340.00
2014/01/01
c £1,000.00
d £-1,000.00
##### Default parent account ##### Default parent account
@ -529,26 +572,26 @@ a single field assignment. Here, any CSV record containing the
pattern `groceries` will have its account2 field set to pattern `groceries` will have its account2 field set to
`expenses:groceries`. `expenses:groceries`.
if groceries if groceries
account2 expenses:groceries account2 expenses:groceries
Example 2. Here, CSV records containing any of these patterns will Example 2. Here, CSV records containing any of these patterns will
have their account2 and comment fields set as shown. The have their account2 and comment fields set as shown. The
capitalisation is not required, that's just how I copied them from capitalisation is not required, that's just how I copied them from
my bank's CSV. my bank's CSV.
if if
MONTHLY SERVICE FEE MONTHLY SERVICE FEE
ATM TRANSACTION FEE ATM TRANSACTION FEE
FOREIGN CURR CONV FOREIGN CURR CONV
OVERDRAFT TRANSFER FEE OVERDRAFT TRANSFER FEE
BANKING THRU SOFTWARE:FEE BANKING THRU SOFTWARE:FEE
INTERNATIONAL PURCHASE TRANSACTION FEE INTERNATIONAL PURCHASE TRANSACTION FEE
WIRE TRANS SVC CHARGE WIRE TRANS SVC CHARGE
FEE FOR TRANSFER FEE FOR TRANSFER
VISA ISA FEE VISA ISA FEE
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).
@ -562,17 +605,17 @@ This is required if the values for `date` or `date2` fields are not in YYYY/MM/D
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:
# "6/11/2013" # "6/11/2013"
date-format %-d/%-m/%Y date-format %-d/%-m/%Y
# "11/06/2013" # "11/06/2013"
date-format %m/%d/%Y date-format %m/%d/%Y
# "2013-Nov-06" # "2013-Nov-06"
date-format %Y-%h-%d date-format %Y-%h-%d
# "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.
@ -631,6 +674,194 @@ To generate time logs, ie to clock in and clock out, you could:
- 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.
## Options
Use `hledger COMMAND --help` to list the options available for that
command. The following general options are common to most commands,
though not every one is applicable in all cases:
```
General flags:
-f --file=FILE use a different input file. For stdin, use -
--rules-file=RFILE CSV conversion rules file (default: FILE.rules)
--alias=OLD=NEW display accounts named OLD as NEW
--ignore-assertions ignore any balance assertions in the journal
-b --begin=DATE include postings/txns on or after this date
-e --end=DATE include postings/txns before this date
-D --daily multiperiod/multicolumn report by day
-W --weekly multiperiod/multicolumn report by week
-M --monthly multiperiod/multicolumn report by month
-Q --quarterly multiperiod/multicolumn report by quarter
-Y --yearly multiperiod/multicolumn report by year
-p --period=PERIODEXP set start date, end date, and/or reporting interval
all at once (overrides the flags above)
--date2 --aux-date use postings/txns' secondary dates instead
-C --cleared include only cleared postings/txns
-U --uncleared include only uncleared postings/txns
-R --real include only non-virtual postings
--depth=N hide accounts/postings deeper than N
-E --empty show empty/zero things which are normally omitted
-B --cost show amounts in their cost price's commodity
-h --help show general help or (after command) command help
--debug[=N] show debug output (increase N for more)
--version show version information
```
Read on for some additional notes.
### Smart dates
Unlike dates in the journal file, hledger's user interfaces accept a
more flexible date syntax. These "smart" dates allow some english
words, can be relative to today's date, and assume 1 when less-significant date parts are omitted.
Examples:
| `2009/1/1`, `2009/01/01`, `2009-1-1`, `2009.1.1` | simple dates, several separators allowed |
| `2009/1`, `2009` | same as above - a missing day or month defaults to 1 |
| `1/1`, `january`, `jan`, `this year` | relative dates, meaning january 1 of the current year|
| `next year` | january 1 of next year |
| `this month` | the 1st of the current month |
| `this week` | the most recent monday |
| `last week` | the monday of the week before this one |
| `today`, `yesterday`, `tomorrow` | |
| `-pmonthlyfrom2/1tonextmonth` | the spaces are optional |
### Reporting interval
A reporting interval can be specified so that commands like
[[#register]], [[#balance]] and [[#activity]] will divide their
reports into multiple report periods. The basic intervals can be
selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`,
`-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be
specified with a period expression.
### Period expressions
The `-p/--period` option accepts period expressions, a shorthand way
of expressing a start date, end date, and or reporting interval all at
once. Note a period expression on the command line will cause any other date
flags (`-b`/`-e`/`-D`/`-W`/`-M`/`-Q`/`-Y`) to be ignored.
hledger's period expressions are similar to Ledger's, though not identical.
Here's a basic period expression specifying the first quarter of 2009. Note
hledger always treats start dates as inclusive and end dates as exclusive:
-p "from 2009/1/1 to 2009/4/1"
Keywords like "from" and "to" are optional, and so are the spaces. Just
don't run two dates together:
-p2009/1/1to2009/4/1
-p"2009/1/1 2009/4/1"
Dates are [smart dates](#smart-dates), so if the current year is 2009, the
above can also be written as:
-p "1/1 to 4/1"
-p "january to apr"
-p "this year to 4/1"
If you specify only one date, the missing start or end date will be the
earliest or latest transaction in your journal:
-p "from 2009/1/1" (everything after january 1, 2009)
-p "from 2009/1" (the same)
-p "from 2009" (the same)
-p "to 2009" (everything before january 1, 2009)
A single date with no "from" or "to" defines both the start and end date
like so:
-p "2009" (the year 2009; equivalent to "2009/1/1 to 2010/1/1")
-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")
Period expressions can also start with (or be) a reporting interval:
`daily`, `weekly`, `monthly`, `quarterly`, `yearly`, or one of the
`every ...` expressions below. Optionally the word `in` may appear
between the reporting interval and the start/end dates.
Examples:
-p "weekly from 2009/1/1 to 2009/4/1"
-p "monthly in 2008"
-p "bimonthly from 2008"
-p "quarterly"
-p "every 2 weeks"
-p "every 5 days from 1/3"
-p "every 15th day of month"
-p "every 4th day of week"
### Depth limiting
With the `--depth N` option, commands like [[#account]], [[#balance]]
and [[#register]] will show only the uppermost accounts in the account
tree, down to level N. Use this when you want a summary with less detail.
## Query arguments
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,
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
more space-separated search terms, optional prefixes to match specific
fields, quotes to enclose whitespace, etc.
A query term can be any of the following:
- `REGEX` - match account names by this regular expression
- `acct:REGEX` - same as above
- `code:REGEX` - match by transaction code (eg check number)
- `desc:REGEX` - match transaction descriptions
- `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
- `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-limiting|depth]]
- `status:1` or `status:0` - match cleared/uncleared transactions
- `real:1` or `real:0` - match real/virtual-ness
- `empty:1` or `empty:0` - match if amount is/is not zero
- `amt:N`, `amt:<N`, `amt:<=N`, `amt:>N`, `amt:>=N` - match postings with a single-commodity
amount that is equal to, less than, or greater than N.
(Multi-commodity amounts are not tested, and will always match.)
The comparison has two modes: if N is preceded by a `+` or `-` sign
(or is 0), the two signed numbers are compared. Otherwise, the
absolute magnitudes are compared, ignoring sign.
- `cur:REGEX` - match postings or transactions including any amounts
whose currency/commodity symbol is fully matched by REGEX. (For a
partial match, use `.*REGEX.*`). Note, to match characters which are
regex-significant, like the dollar sign (`$`), you need to prepend `\`.
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 cur:'\$'`
or `hledger print cur:\\$`.
- `not:` before any of the above negates the match
### Combining query arguments
hledger query expressions don't support full boolean logic. Instead, multiple query terms
are combined as follows:
- The [[#print]] command selects transactions which:
- 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.
<!-- -->
- 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 arguments vs options
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.
Remember that a `-p` [[#period-expressions|period]] flag will cause any other `-b`, `-e` or `-p` flags on the command line to be ignored.
## Commands ## Commands
hledger provides a number of subcommands out of the box; run `hledger` with no arguments to see a list. hledger provides a number of subcommands out of the box; run `hledger` with no arguments to see a list.
@ -862,6 +1093,79 @@ be "enlarged" if necessary so that they encompass the displayed report
periods. This is so that the first and last periods will be "full" and periods. This is so that the first and last periods will be "full" and
comparable to the others. comparable to the others.
The `-E/--empty` flag does two things here: first, the report will
show all columns within the specified report period (without -E,
leading and trailing columns with all zeroes are not shown). Second,
all accounts which existed at the report start date will be
considered, not just the ones with activity during the report period
(use -E to include low-activity accounts which would otherwise would
be omitted).
##### Custom output formats
In simple balance reports (only), the `--format FMT` option will customize
the format of output lines. `FMT` is like a C printf/strftime-style
format string, except that field names are enclosed in parentheses:
%[-][MIN][.MAX]([FIELD])
If the minus sign is given, the text is left justified. The `MIN` field
specified a minimum number of characters in width. After the value is
injected into the string, spaces is added to make sure the string is at
least as long as `MIN`. Similary, the `MAX` field specifies the maximum
number of characters. The string will be cut if the injected string is too
long.
- `%-(total) ` the total of an account, left justified
- `%20(total) ` The same, right justified, at least 20 chars wide
- `%.20(total) ` The same, no more than 20 chars wide
- `%-.20(total)` Left justified, maximum twenty chars wide
The following `FIELD` types are currently supported:
- `account` inserts the account name
- `depth_spacer` inserts a space for each level of an account's
depth. That is, if an account has two parents, this construct will
insert two spaces. If a minimum width is specified, that much space is
inserted for each level of depth. Thus `%5_`, for an account with four
parents, will insert twenty spaces.
- `total` inserts the total for the account
Examples:
If you want the account before the total you can use this format:
$ hledger balance --format "%20(account) %-(total)"
assets $-1
bank:saving $1
cash $-2
expenses $2
food $1
supplies $1
income $-2
gifts $-1
salary $-1
liabilities:debts $1
--------------------
0
Or, if you'd like to export the balance sheet:
$ hledger balance --format "%(total);%(account)" --no-total
$-1;assets
$1;bank:saving
$-2;cash
$2;expenses
$1;food
$1;supplies
$-2;income
$-1;gifts
$-1;salary
$1;liabilities:debts
The default output format is `%20(total) %2(depth_spacer)%-(account)`.
#### incomestatement #### incomestatement
This command displays a simple This command displays a simple
@ -905,7 +1209,7 @@ Examples:
$ hledger stats $ hledger stats
$ hledger stats -p 'monthly in 2009' $ hledger stats -p 'monthly in 2009'
### Utility ### Misc.
#### test #### test
@ -919,7 +1223,7 @@ Examples:
$ hledger test $ hledger test
$ hledger test -v balance $ hledger test -v balance
### Add-ons ### Add-on
Add-on commands are executables in your PATH whose name starts with Add-on commands are executables in your PATH whose name starts with
`hledger-` and ends with no file extension or one of these common `hledger-` and ends with no file extension or one of these common
@ -975,8 +1279,9 @@ See the package page for more.
#### web #### web
[hledger-web](http://hackage.haskell.org/package/hledger-web) [hledger-web](http://hackage.haskell.org/package/hledger-web)
provides a web-based user interface for viewing and modifying your ledger ([demo](http://demo.hledger.org)). provides a web-based user interface for viewing and modifying your ledger.
It includes an account register view that is more useful than the command-line register, and basic data entry and editing. It includes an account register view that is more useful than the command-line register, and basic data entry and editing.
Try it out at http://demo.hledger.org.
web-specific options: web-specific options:
@ -1030,11 +1335,11 @@ make them available. The scripts are designed to run interpreted on
unix systems (for tweaking), or you can compile them (for speed and unix systems (for tweaking), or you can compile them (for speed and
robustness). robustness).
#### balance-csv.hs #### balance-csv
Like the balance command, but with CSV output. Like the balance command, but with CSV output.
#### equity.hs #### equity
Like ledger's equity command, this prints a single journal entry with Like ledger's equity command, this prints a single journal entry with
postings matching the current balance in each account (or the postings matching the current balance in each account (or the
@ -1047,15 +1352,15 @@ old file, resetting balances to 0. This means you'll see the correct
asset/liability balances whether you use one file or a whole sequence asset/liability balances whether you use one file or a whole sequence
of files as input to hledger. of files as input to hledger.
#### print-unique.hs #### print-unique
Prints only journal entries which are unique (by description). Prints only journal entries which are unique (by description).
#### register-csv.hs #### register-csv
Like the register command, but with CSV output. Like the register command, but with CSV output.
#### rewrite.hs #### rewrite
Prints all journal entries, adding specified custom postings to matched entries. Prints all journal entries, adding specified custom postings to matched entries.
@ -1116,256 +1421,46 @@ Examples:
--> -->
## Common options ## Known limitations
The following common features and options work with most subcommands. Here are some things to be aware of.
### Queries ### Add-on-specific options must follow --
Part of hledger's usefulness is being able to report on just a precise subset of your data. When invoking an add-on via hledger, add-on flags which are not also
Most commands accept an optional query expression, written as arguments after the command name, understood by the main hledger executable must have a `--` argument
to filter the data by date, account name or other criteria. Query expressions are also used preceding them. Eg hledger-web's `--server` flag must be used like so:
in the [[#web|web ui]]'s search form. `hledger web -- --server`.
The query syntax is similar to a Google search expression: one or ### -w/--width and --debug options must be written without whitespace
more space-separated search terms, optional prefixes to match specific
fields, quotes to enclose whitespace, etc.
A query term can be any of the following:
- `REGEX` - match account names by this regular expression Up to hledger 0.23, these optional-value flags [[https://github.com/simonmichael/hledger/issues/149|did not work]] with whitespace between the flag and value.
- `acct:REGEX` - same as above Good: `--debug=2`, `-w100`. Bad: `--debug 2`, `-w 100`.
- `code:REGEX` - match by transaction code (eg check number) (From 0.24, the value is required.)
- `desc:REGEX` - match transaction descriptions
- `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
- `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-limiting|depth]]
- `status:1` or `status:0` - match cleared/uncleared transactions
- `real:1` or `real:0` - match real/virtual-ness
- `empty:1` or `empty:0` - match if amount is/is not zero
- `amt:N`, `amt:<N`, `amt:>N` - match postings with a single-commodity
amount that is equal to, less than, or greater than N.
(Multi-commodity amounts are not tested, and will always match.)
The comparison has two modes: if N is preceded by a `+` or `-` sign
(or is 0), the two signed numbers are compared. Otherwise, the
absolute magnitudes are compared, ignoring sign.
- `cur:REGEX` - match postings or transactions including any amounts
whose currency/commodity symbol is fully matched by REGEX. (For a
partial match, use `.*REGEX.*`). Note, to match characters which are
regex-significant, like the dollar sign (`$`), you need to prepend `\`.
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 cur:'\$'`
or `hledger print cur:\\$`.
- `not:` before any of the above negates the match
#### How query terms combine ### Not all of Ledger's journal file syntax is supported
hledger query expressions don't support full boolean logic. Instead, multiple query terms See [[faq#file-format-differences|file format differences]].
are combined as follows:
- The [[#print]] command selects transactions which: ### balance is less speedy than Ledger's on large data files
- 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.
<!-- --> hledger's balance command (in particular) takes more time, and uses more memory, than Ledger's.
This becomes more noticeable with large data files.
- Other reporting commands (eg [[#register]] and [[#balance]]) select transactions/postings/accounts which match (or negatively match): ### Windows CMD.EXE
- any of the description terms AND
- any of the account terms AND
- all the other terms.
Non-ascii characters and colours are not supported.
#### Query options vs query arguments ### Windows cygwin/msys/mintty
On the command line, some of the query terms above can also be expressed as command-line flags. The tab key is not supported in hledger add.
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.
### Smart dates
Unlike the journal file format, hledger's user interface accepts flexible
"smart dates", for example in the `-b` and `-e` options, period
expressions, display expressions, the add command and the web add form.
Smart dates allow some natural english words, will assume 1 where
less-significant date parts are unspecified, and can be relative to
today's date. Examples:
- `2009/1/1`, `2009/01/01`, `2009-1-1`, `2009.1.1` (simple dates)
- `2009/1`, `2009` (these also mean january 1, 2009)
- `1/1`, `january`, `jan`, `this year` (relative dates, meaning january 1 of this year)
- `next year` (january 1, next year)
- `this month` (the 1st of the current month)
- `this week` (the most recent monday)
- `last week` (the monday of the week before this one)
- `today`, `yesterday`, `tomorrow`
Spaces in smart dates are optional, so eg `-b lastmonth` or `date:fromlastmonth` are valid.
### Period expressions
hledger supports flexible "period expressions" with the `-p/--period`
option to select transactions within a period of time (eg in 2009) and/or
with a reporting interval (eg weekly). hledger period expressions are
similar but not identical to ledger's.
Here is a basic period expression specifying the first quarter of 2009.
Note the start date is always included and the end date is always excluded:
-p "from 2009/1/1 to 2009/4/1"
Keywords like "from" and "to" are optional, and so are the spaces. Just
don't run two dates together:
-p2009/1/1to2009/4/1
-p"2009/1/1 2009/4/1"
Dates are [smart dates](#smart-dates), so if the current year is 2009, the
above can also be written as:
-p "1/1 to 4/1"
-p "january to apr"
-p "this year to 4/1"
If you specify only one date, the missing start or end date will be the
earliest or latest transaction in your journal:
-p "from 2009/1/1" (everything after january 1, 2009)
-p "from 2009/1" (the same)
-p "from 2009" (the same)
-p "to 2009" (everything before january 1, 2009)
A single date with no "from" or "to" defines both the start and end date
like so:
-p "2009" (the year 2009; equivalent to "2009/1/1 to 2010/1/1")
-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")
The `-b/--begin` and `-e/--end` options may be used as a shorthand for `-p
'from ...'` and `-p 'to ...'` respectively.
Note, however: a `-p/--period` option in the command line will cause any
`-b`/`-e`/`-D`/`-W`/`-M`/`-Q`/`-Y` flags to be ignored.
### Reporting interval
Period expressions can also begin with (or be) a reporting interval, which
affects commands like [register](#register) and [activity](#activity).
The reporting interval can be `daily`, `weekly`, `monthly`, `quarterly`, `yearly`,
or one of the `every ...` expressions below, optionally followed by `in`.
Examples:
-p "weekly from 2009/1/1 to 2009/4/1"
-p "monthly in 2008"
-p "bimonthly from 2008"
-p "quarterly"
-p "every 2 weeks"
-p "every 5 days from 1/3"
-p "every 15th day of month"
-p "every 4th day of week"
A reporting interval may also be specified with the `-D/--daily`,
`-W/--weekly`, `-M/--monthly`, `-Q/--quarterly`, and `-Y/--yearly`
options. But as noted above, a `-p/--period` option will override these.
### Display expressions
A [period expression](#period-expressions) or other [query](#queries)
selects the transactions to be used for calculation. A display
expression, specified with `-d/--display`, selects a more limited
subset of transactions to be displayed in the report output.
This useful, say, if you want to see your checking register just for
this month, but with an accurate running balance based on all
transactions. Eg:
$ hledger register checking --display "d>=[1]"
meaning "make a register report of all checking transactions, but
display only the ones with date on or after the 1st of this month."
Any [smart date](#smart-dates) can appear inside the brackets.
The above the only kind of display expression we currently support:
transactions before or after a given date.
### Depth limiting
With the `--depth N` option, reports will show only the uppermost accounts
in the account tree, down to level N. See the [balance](#balance),
[register](#register) and [chart](#chart) examples.
### Custom output formats
The `--format FMT` option will customize the line format of the balance
command's output (only, for now). `FMT` is a C printf/strftime-style
format string, with the exception that field names are enclosed in
parentheses:
%[-][MIN][.MAX]([FIELD])
If the minus sign is given, the text is left justified. The `MIN` field
specified a minimum number of characters in width. After the value is
injected into the string, spaces is added to make sure the string is at
least as long as `MIN`. Similary, the `MAX` field specifies the maximum
number of characters. The string will be cut if the injected string is too
long.
- `%-(total) ` the total of an account, left justified
- `%20(total) ` The same, right justified, at least 20 chars wide
- `%.20(total) ` The same, no more than 20 chars wide
- `%-.20(total)` Left justified, maximum twenty chars wide
The following `FIELD` types are currently supported:
- `account` inserts the account name
- `depth_spacer` inserts a space for each level of an account's
depth. That is, if an account has two parents, this construct will
insert two spaces. If a minimum width is specified, that much space is
inserted for each level of depth. Thus `%5_`, for an account with four
parents, will insert twenty spaces.
- `total` inserts the total for the account
Examples:
If you want the account before the total you can use this format:
$ hledger balance --format "%20(account) %-(total)"
assets $-1
bank:saving $1
cash $-2
expenses $2
food $1
supplies $1
income $-2
gifts $-1
salary $-1
liabilities:debts $1
--------------------
0
Or, if you'd like to export the balance sheet:
$ hledger balance --format "%(total);%(account)" --no-total
$-1;assets
$1;bank:saving
$-2;cash
$2;expenses
$1;food
$1;supplies
$-2;income
$-1;gifts
$-1;salary
$1;liabilities:debts
The default output format is `%20(total) %2(depth_spacer)%-(account)`
## Troubleshooting ## Troubleshooting
Here are some issues you might encounter when you run hledger Here are some issues you might encounter when you run hledger
(and remember you can also seek help from the (and remember you can also seek help from the
[IRC channel](irc://irc.freenode.net/#ledger), [IRC channel](https://github.com/ledger/ledger/wiki/%23ledger-IRC-channel),
[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)):
@ -1374,9 +1469,6 @@ 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.
### Fails to parse some valid Ledger files
See [[faq#file-format-differences|file format differences]].
### "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
@ -1386,34 +1478,35 @@ I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu gnu/linux: Here's an example of setting the locale temporarily, on ubuntu gnu/linux:
$ file my.journal $ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
$ locale -a $ locale -a
C C
en_US.utf8 # <- a UTF8-aware locale is available en_US.utf8 # <- a UTF8-aware locale is available
POSIX POSIX
$ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
Here's one way to set it permanently, there are probably better ways: Here's one way to set it permanently, there are probably better ways:
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login $ bash --login
If we preferred to use eg `fr_FR.utf8`, we might have to install that first: If we preferred to use eg `fr_FR.utf8`, we might have to install that first:
$ apt-get install language-pack-fr $ apt-get install language-pack-fr
$ locale -a $ locale -a
C C
en_US.utf8 en_US.utf8
fr_BE.utf8 fr_BE.utf8
fr_CA.utf8 fr_CA.utf8
fr_CH.utf8 fr_CH.utf8
fr_FR.utf8 fr_FR.utf8
fr_LU.utf8 fr_LU.utf8
POSIX POSIX
$ LANG=fr_FR.utf8 hledger -f my.journal print $ LANG=fr_FR.utf8 hledger -f my.journal print
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`).