;doc: consolidate hledger manual a bit
This commit is contained in:
Simon Michael
parent
4dc82fc2b3
commit
743a63c319
@ -7,7 +7,6 @@ m4_dnl
|
||||
m4_dnl hledger.1.m4.md
|
||||
m4_dnl hledger_examples.m4.md
|
||||
m4_dnl hledger_options.m4.md
|
||||
m4_dnl hledger_queries.m4.md
|
||||
m4_dnl hledger_commands.m4.md
|
||||
m4_dnl hledger_troubleshooting.m4.md
|
||||
|
||||
@ -66,8 +65,9 @@ try some commands like `hledger print` or `hledger balance`.
|
||||
Run `hledger` with no arguments for a list of commands.
|
||||
|
||||
_include_(hledger_examples.m4.md)
|
||||
|
||||
_include_(hledger_options.m4.md)
|
||||
_include_(hledger_queries.m4.md)
|
||||
|
||||
_include_(hledger_commands.m4.md)
|
||||
|
||||
# ENVIRONMENT
|
||||
|
||||
@ -1,68 +0,0 @@
|
||||
# ADD-ON COMMANDS
|
||||
|
||||
hledger also searches for external add-on commands, and will include these in the commands list.
|
||||
These are programs or scripts in your PATH whose name starts with `hledger-`
|
||||
and ends with a recognised file extension
|
||||
(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`).
|
||||
|
||||
Add-ons can be invoked like any hledger command, but there are a few things to be aware of.
|
||||
Eg if the `hledger-web` add-on is installed,
|
||||
|
||||
- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help.
|
||||
|
||||
- Flags specific to the add-on must have a preceding `--` to hide them from hledger.
|
||||
So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`.
|
||||
|
||||
- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`.
|
||||
|
||||
Add-ons are a relatively easy way to add local features or experiment with new ideas.
|
||||
They can be written in any language, but haskell scripts have a big advantage:
|
||||
they can use the same hledger (and haskell) library functions that built-in commands do,
|
||||
for command-line options, journal parsing, reporting, etc.
|
||||
|
||||
Here are some hledger add-ons available:
|
||||
|
||||
## Official add-ons
|
||||
|
||||
These are maintained and released along with hledger.
|
||||
|
||||
### ui
|
||||
[hledger-ui](hledger-ui.html) provides an efficient terminal interface.
|
||||
|
||||
### web
|
||||
[hledger-web](hledger-web.html) provides a simple web interface.
|
||||
|
||||
## Third party add-ons
|
||||
|
||||
These are maintained separately, and usually updated shortly after a hledger release.
|
||||
|
||||
### iadd
|
||||
|
||||
[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd)
|
||||
is a more interactive, terminal UI replacement for the [add command](hledger.html#add).
|
||||
|
||||
### interest
|
||||
|
||||
[hledger-interest](http://hackage.haskell.org/package/hledger-interest)
|
||||
generates interest transactions for an account according to various schemes.
|
||||
|
||||
## Experimental add-ons
|
||||
|
||||
These are available in source form in the hledger repo's bin/ directory.
|
||||
They may be less mature and documented than built-in commands.
|
||||
Reading and tweaking these is a good way to start making your own!
|
||||
|
||||
### autosync
|
||||
|
||||
[hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync)
|
||||
is a symbolic link for easily running
|
||||
[ledger-autosync](https://pypi.python.org/pypi/ledger-autosync), if installed.
|
||||
ledger-autosync does deduplicating conversion of OFX data and some CSV formats,
|
||||
and can also download the data
|
||||
[if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings).
|
||||
|
||||
### chart
|
||||
|
||||
[hledger-chart.hs](https://github.com/simonmichael/hledger/blob/master/bin/_hledger-chart.hs#L47)
|
||||
is an old very basic pie chart generator.
|
||||
|
||||
@ -132,4 +132,59 @@ _include_({{Hledger/Cli/Commands/Tags.md}})
|
||||
|
||||
_include_({{Hledger/Cli/Commands/Test.md}})
|
||||
|
||||
_include_(hledger_addons.m4.md)
|
||||
|
||||
## Add-on Commands
|
||||
|
||||
hledger also searches for external add-on commands, and will include these in the commands list.
|
||||
These are programs or scripts in your PATH whose name starts with `hledger-`
|
||||
and ends with a recognised file extension
|
||||
(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`).
|
||||
|
||||
Add-ons can be invoked like any hledger command, but there are a few things to be aware of.
|
||||
Eg if the `hledger-web` add-on is installed,
|
||||
|
||||
- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help.
|
||||
|
||||
- Flags specific to the add-on must have a preceding `--` to hide them from hledger.
|
||||
So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`.
|
||||
|
||||
- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`.
|
||||
|
||||
Add-ons are a relatively easy way to add local features or experiment with new ideas.
|
||||
They can be written in any language, but haskell scripts have a big advantage:
|
||||
they can use the same hledger (and haskell) library functions that built-in commands do,
|
||||
for command-line options, journal parsing, reporting, etc.
|
||||
|
||||
Two important add-ons are the hledger-ui and hledger-web user interfaces.
|
||||
These are maintained and released along with hledger:
|
||||
|
||||
### ui
|
||||
[hledger-ui](hledger-ui.html) provides an efficient terminal interface.
|
||||
|
||||
### web
|
||||
[hledger-web](hledger-web.html) provides a simple web interface.
|
||||
|
||||
Third party add-ons, maintained separately from hledger, include:
|
||||
|
||||
### iadd
|
||||
|
||||
[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd)
|
||||
is a more interactive, terminal UI replacement for the [add command](hledger.html#add).
|
||||
|
||||
### interest
|
||||
|
||||
[hledger-interest](http://hackage.haskell.org/package/hledger-interest)
|
||||
generates interest transactions for an account according to various schemes.
|
||||
|
||||
<!-- ### autosync -->
|
||||
|
||||
<!-- [hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync) -->
|
||||
<!-- is a symbolic link for easily running -->
|
||||
<!-- [ledger-autosync](https://pypi.python.org/pypi/ledger-autosync) if you make a symbolic -->
|
||||
<!-- ledger-autosync does deduplicating conversion of OFX data and some CSV formats, -->
|
||||
<!-- and can also download the data -->
|
||||
<!-- [if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings). -->
|
||||
|
||||
A few more experimental or old add-ons can be found in hledger's bin/
|
||||
directory. These are typically prototypes and not guaranteed to work.
|
||||
|
||||
|
||||
@ -2,7 +2,17 @@ m4_dnl Quick examples included early in the manual
|
||||
m4_dnl TODO make these and all the command examples pasteable/doctestable ?
|
||||
m4_dnl eg include -f FILE or $LEDGER_FILE details
|
||||
|
||||
# EXAMPLES
|
||||
# COMMON TASKS
|
||||
|
||||
Here are some quick examples of how to do some basic tasks with hledger.
|
||||
For more background, see the reference section below, and the journal format manual.
|
||||
For a more gentle introduction and additional how-tos, see the hledger.org website.
|
||||
|
||||
## Starting a Journal
|
||||
|
||||
## Setting Opening Balances
|
||||
|
||||
## Recording Transactions
|
||||
|
||||
Two simple transactions in hledger journal format:
|
||||
|
||||
@ -16,7 +26,9 @@ Two simple transactions in hledger journal format:
|
||||
assets:cash
|
||||
```
|
||||
|
||||
Some basic reports:
|
||||
## Reconciling
|
||||
|
||||
## Some basic reports
|
||||
|
||||
```shell
|
||||
$ hledger print
|
||||
@ -54,7 +66,7 @@ $ hledger register cash
|
||||
2015-10-16 farmers market assets:cash $-10 $10
|
||||
```
|
||||
|
||||
More commands:
|
||||
## More commands
|
||||
|
||||
```shell
|
||||
$ hledger # show available commands
|
||||
|
||||
@ -32,8 +32,6 @@ Or, you can run the addon executable directly: `hledger-ui --watch`.
|
||||
Most hledger commands accept arguments after the command name,
|
||||
which are often a [query](#queries), filtering the data in some way.
|
||||
|
||||
## Argument files
|
||||
|
||||
You can save a set of command line options/arguments in a file,
|
||||
and then reuse them by writing `@FILENAME` as a command line argument.
|
||||
Eg: `hledger bal @foo.args`.
|
||||
@ -66,6 +64,105 @@ Good:
|
||||
|
||||
See also: [Save frequently used options](save-frequently-used-options.html).
|
||||
|
||||
## Queries
|
||||
|
||||
One of hledger's strengths is being able to quickly report on precise subsets 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.
|
||||
The syntax is similar to a web search:
|
||||
one or more space-separated search terms,
|
||||
quotes to enclose whitespace,
|
||||
prefixes to match specific fields,
|
||||
a not: prefix to negate the match.
|
||||
|
||||
We do not yet support arbitrary boolean combinations of search terms;
|
||||
instead most commands show transactions/postings/accounts which match (or negatively match):
|
||||
|
||||
- any of the description terms AND
|
||||
- any of the account terms AND
|
||||
- any of the status terms AND
|
||||
- all the other terms.
|
||||
|
||||
The [print](hledger.html#print) command instead shows 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.
|
||||
|
||||
The following kinds of search terms can be used.
|
||||
Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount.
|
||||
|
||||
**`REGEX`, `acct:REGEX`**
|
||||
: match account names by this regular expression. (With no prefix, `acct:` is assumed.)
|
||||
|
||||
: same as above
|
||||
|
||||
**`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.
|
||||
|
||||
**`code:REGEX`**
|
||||
: match by transaction code (eg check number)
|
||||
|
||||
**`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:\\$`.
|
||||
|
||||
**`desc:REGEX`**
|
||||
: match transaction descriptions.
|
||||
|
||||
**`date:PERIODEXPR`**
|
||||
: match dates within the specified period.
|
||||
PERIODEXPR is a [period expression](hledger.html#period-expressions) (with no report interval).
|
||||
Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`.
|
||||
If the `--date2` command line flag is present, this matches [secondary dates](journal.html#secondary-dates) instead.
|
||||
|
||||
**`date2:PERIODEXPR`**
|
||||
: match secondary dates within the specified period.
|
||||
|
||||
**`depth:N`**
|
||||
: match (or display, depending on command) accounts at or above this depth
|
||||
|
||||
**`note:REGEX`**
|
||||
: match transaction [notes](journal.html#payee-and-note)
|
||||
(part of description right of `|`, or whole description when there's no `|`)
|
||||
|
||||
**`payee:REGEX`**
|
||||
: match transaction [payee/payer names](journal.html#payee-and-note)
|
||||
(part of description left of `|`, or whole description when there's no `|`)
|
||||
|
||||
**`real:, real:0`**
|
||||
: match real or virtual postings respectively
|
||||
|
||||
**`status:, status:!, status:*`**
|
||||
: match unmarked, pending, or cleared transactions respectively
|
||||
|
||||
**`tag:REGEX[=REGEX]`**
|
||||
: match by tag name, and optionally also by tag value. Note a
|
||||
tag: query is considered to match a transaction if it matches any of
|
||||
the postings. Also remember that postings inherit the tags of their
|
||||
parent transaction.
|
||||
|
||||
The following special search term is used automatically in hledger-web, only:
|
||||
|
||||
**`inacct:ACCTNAME`**
|
||||
: tells hledger-web to show the transaction register for this account.
|
||||
Can be filtered further with `acct` etc.
|
||||
|
||||
Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
|
||||
Generally you can mix options and query arguments, and the resulting query will be their intersection
|
||||
(perhaps excluding the `-p/--period` option).
|
||||
|
||||
## Special characters in arguments and queries
|
||||
|
||||
In shell command lines, option and argument values which contain "problematic" characters,
|
||||
@ -823,3 +920,4 @@ meaning to the shell and so must be escaped at least once more.
|
||||
See [Special characters](#special-characters).
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,98 +0,0 @@
|
||||
# QUERIES
|
||||
|
||||
One of hledger's strengths is being able to quickly report on precise subsets 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.
|
||||
The syntax is similar to a web search:
|
||||
one or more space-separated search terms,
|
||||
quotes to enclose whitespace,
|
||||
prefixes to match specific fields,
|
||||
a not: prefix to negate the match.
|
||||
|
||||
We do not yet support arbitrary boolean combinations of search terms;
|
||||
instead most commands show transactions/postings/accounts which match (or negatively match):
|
||||
|
||||
- any of the description terms AND
|
||||
- any of the account terms AND
|
||||
- any of the status terms AND
|
||||
- all the other terms.
|
||||
|
||||
The [print](hledger.html#print) command instead shows 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.
|
||||
|
||||
The following kinds of search terms can be used.
|
||||
Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount.
|
||||
|
||||
**`REGEX`, `acct:REGEX`**
|
||||
: match account names by this regular expression. (With no prefix, `acct:` is assumed.)
|
||||
|
||||
: same as above
|
||||
|
||||
**`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.
|
||||
|
||||
**`code:REGEX`**
|
||||
: match by transaction code (eg check number)
|
||||
|
||||
**`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:\\$`.
|
||||
|
||||
**`desc:REGEX`**
|
||||
: match transaction descriptions.
|
||||
|
||||
**`date:PERIODEXPR`**
|
||||
: match dates within the specified period.
|
||||
PERIODEXPR is a [period expression](hledger.html#period-expressions) (with no report interval).
|
||||
Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`.
|
||||
If the `--date2` command line flag is present, this matches [secondary dates](journal.html#secondary-dates) instead.
|
||||
|
||||
**`date2:PERIODEXPR`**
|
||||
: match secondary dates within the specified period.
|
||||
|
||||
**`depth:N`**
|
||||
: match (or display, depending on command) accounts at or above this depth
|
||||
|
||||
**`note:REGEX`**
|
||||
: match transaction [notes](journal.html#payee-and-note)
|
||||
(part of description right of `|`, or whole description when there's no `|`)
|
||||
|
||||
**`payee:REGEX`**
|
||||
: match transaction [payee/payer names](journal.html#payee-and-note)
|
||||
(part of description left of `|`, or whole description when there's no `|`)
|
||||
|
||||
**`real:, real:0`**
|
||||
: match real or virtual postings respectively
|
||||
|
||||
**`status:, status:!, status:*`**
|
||||
: match unmarked, pending, or cleared transactions respectively
|
||||
|
||||
**`tag:REGEX[=REGEX]`**
|
||||
: match by tag name, and optionally also by tag value. Note a
|
||||
tag: query is considered to match a transaction if it matches any of
|
||||
the postings. Also remember that postings inherit the tags of their
|
||||
parent transaction.
|
||||
|
||||
The following special search term is used automatically in hledger-web, only:
|
||||
|
||||
**`inacct:ACCTNAME`**
|
||||
: tells hledger-web to show the transaction register for this account.
|
||||
Can be filtered further with `acct` etc.
|
||||
|
||||
Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`).
|
||||
Generally you can mix options and query arguments, and the resulting query will be their intersection
|
||||
(perhaps excluding the `-p/--period` option).
|
||||
Loading…
Reference in New Issue
Block a user