docs: reorganise commands
This commit is contained in:
Simon Michael
parent
8ead2de29c
commit
b57915cd54
368
MANUAL.markdown
368
MANUAL.markdown
@ -61,22 +61,6 @@ If you have any trouble, please proceed to
|
|||||||
[Troubleshooting](#troubleshooting) for help and/or seek
|
[Troubleshooting](#troubleshooting) for help and/or seek
|
||||||
[Support](DEVELOPMENT.html#support).
|
[Support](DEVELOPMENT.html#support).
|
||||||
|
|
||||||
<!--
|
|
||||||
|
|
||||||
- `-fweb` builds the [web](#web) command, enabling a web-based user
|
|
||||||
interface. This requires GHC 6.12 or greater.
|
|
||||||
|
|
||||||
- `-fvty` builds the [vty](#vty) command, enabling a basic
|
|
||||||
curses-style user interface. This does not work on microsoft
|
|
||||||
windows, unless possibly with cygwin.
|
|
||||||
|
|
||||||
- `-fchart` builds the [chart](#chart) command, enabling rudimentary
|
|
||||||
pie chart generation. This requires additional GTK-related libraries
|
|
||||||
(on ubuntu: `apt-get install libghc6-gtk-dev`) and possibly [other
|
|
||||||
things](http://code.haskell.org/gtk2hs/INSTALL).
|
|
||||||
|
|
||||||
-->
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
hledger looks for data in a [journal file](#journal-file) named `.journal`
|
hledger looks for data in a [journal file](#journal-file) named `.journal`
|
||||||
@ -274,44 +258,50 @@ compatibility](#file-format-compatibility).
|
|||||||
|
|
||||||
### Commands
|
### Commands
|
||||||
|
|
||||||
#### Reporting commands
|
Here are the commands hledger supports. Note,
|
||||||
|
|
||||||
##### print
|
- the most frequently used commands are [print](#print),
|
||||||
|
[register](#register) and [balance](#balance).
|
||||||
|
|
||||||
The print command displays full transactions from the journal file, tidily
|
- except where noted, all commands are read-only, that is they never
|
||||||
formatted and showing all amounts explicitly. The output of print is
|
modify your data. The exceptions are [add](#add) and [web](#web).
|
||||||
always a valid hledger journal.
|
|
||||||
|
|
||||||
hledger's print command also shows all unit prices in effect, or (with
|
#### add
|
||||||
-B/--cost) shows cost amounts.
|
|
||||||
|
Note: this command can append to your journal file.
|
||||||
|
|
||||||
|
The add command prompts interactively for new transactions, and appends
|
||||||
|
them to the journal file. Each transaction is appended when you complete
|
||||||
|
it by entering `.` (period) at the account prompt. Enter control-D or
|
||||||
|
control-C when you are done.
|
||||||
|
|
||||||
|
The add command tries to be helpful, providing:
|
||||||
|
|
||||||
|
- Sensible defaults
|
||||||
|
|
||||||
|
- History awareness: if there are existing transactions approximately
|
||||||
|
matching the description you enter, they will be displayed and the best
|
||||||
|
match will provide defaults for the other fields. If you specify
|
||||||
|
[filter pattern(s)](#filter-patterns) on the command line, only matching
|
||||||
|
transactions will be considered as history.
|
||||||
|
|
||||||
|
- Readline-style input: during data entry, the usual editing keys should
|
||||||
|
work.
|
||||||
|
|
||||||
|
- Auto-completion for account names: while entering account names, the tab
|
||||||
|
key will auto-complete as far as possible, or list the available
|
||||||
|
options.
|
||||||
|
|
||||||
|
- Default commodity awareness: if the journal specifies a
|
||||||
|
[default commodity directive](#default-commodity), that will be applied
|
||||||
|
to any bare numbers entered.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
||||||
$ hledger print
|
$ hledger add
|
||||||
$ hledger print employees:bob | hledger -f- register expenses
|
$ hledger -f home.journal add equity:bob
|
||||||
|
|
||||||
##### register
|
#### balance
|
||||||
|
|
||||||
The register command displays postings, one per line, and their running total.
|
|
||||||
With no [filter patterns](#filter-patterns), this is not all that different from [print](#print):
|
|
||||||
|
|
||||||
$ hledger register
|
|
||||||
|
|
||||||
More typically, use it to see a specific account's activity:
|
|
||||||
|
|
||||||
$ hledger register assets:bank:checking
|
|
||||||
|
|
||||||
The `--depth` option limits the amount of sub-account detail displayed:
|
|
||||||
|
|
||||||
$ hledger register assets:bank:checking --depth 2
|
|
||||||
|
|
||||||
With a [reporting interval](#reporting-interval) it shows aggregated
|
|
||||||
summary postings within each interval:
|
|
||||||
|
|
||||||
$ hledger register --monthly rent
|
|
||||||
$ hledger register --monthly -E food --depth 4
|
|
||||||
|
|
||||||
##### balance
|
|
||||||
|
|
||||||
The balance command displays accounts and their balances, indented to show the account hierarchy.
|
The balance command displays accounts and their balances, indented to show the account hierarchy.
|
||||||
Examples:
|
Examples:
|
||||||
@ -332,141 +322,7 @@ 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;
|
name components. Note `--depth` doesn't work too well with `--flat` currently;
|
||||||
it hides deeper accounts rather than aggregating them.
|
it hides deeper accounts rather than aggregating them.
|
||||||
|
|
||||||
##### chart
|
#### convert
|
||||||
|
|
||||||
*This is an add-on; see [installing](#installing). Next release, it will be provided by the hledger-chart package.*
|
|
||||||
|
|
||||||
The chart command saves a pie chart of your top account balances to an
|
|
||||||
image file (usually "hledger.png", or use -o/--output FILE). You can
|
|
||||||
adjust the image resolution with --size=WIDTHxHEIGHT, and the number of
|
|
||||||
accounts with --items=N.
|
|
||||||
|
|
||||||
Note that positive and negative balances will not be displayed together in
|
|
||||||
the same chart; any balances not matching the sign of the first one will
|
|
||||||
be omitted.
|
|
||||||
|
|
||||||
To show only accounts above a certain depth, use the --depth
|
|
||||||
option. Otherwise, the chart can include accounts at any depth. If a
|
|
||||||
parent and child account are both displayed, the parent's balance excludes
|
|
||||||
the child's.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
$ hledger chart assets --depth 2
|
|
||||||
$ hledger chart liabilities --depth 2
|
|
||||||
$ hledger chart ^expenses -o balance.png --size 1000x600 --items 20
|
|
||||||
$ for m in 01 02 03 04 05 06 07 08 09 10 11 12; do hledger -p 2009/$m chart ^expenses --depth 2 -o expenses-2009$m.png --size 400x300; done
|
|
||||||
|
|
||||||
##### histogram
|
|
||||||
|
|
||||||
The histogram command displays a quick bar chart showing transaction
|
|
||||||
counts, per day, week, month or other reporting interval. It is
|
|
||||||
experimental.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
$ hledger histogram -p weekly dining
|
|
||||||
|
|
||||||
##### stats
|
|
||||||
|
|
||||||
The stats command displays quick summary information for the whole journal,
|
|
||||||
or by period.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
$ hledger stats
|
|
||||||
$ hledger stats -p 'monthly in 2009'
|
|
||||||
|
|
||||||
##### vty
|
|
||||||
|
|
||||||
*This is an add-on; see [installing](#installing). Next release, it will be provided by the hledger-vty package.*
|
|
||||||
|
|
||||||
The vty command starts hledger's curses (full-screen, text) user interface,
|
|
||||||
which allows interactive navigation of the print/register/balance
|
|
||||||
reports. This lets you browse around your numbers and get quick insights
|
|
||||||
with less typing.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
$ hledger vty
|
|
||||||
$ hledger vty -BE food
|
|
||||||
|
|
||||||
#### Modifying commands
|
|
||||||
|
|
||||||
The following commands can alter your journal file.
|
|
||||||
|
|
||||||
##### add
|
|
||||||
|
|
||||||
The add command prompts interactively for new transactions, and appends
|
|
||||||
them to the journal file. Each transaction is appended when you complete
|
|
||||||
it by entering `.` (period) at the account prompt. Enter control-D or
|
|
||||||
control-C when you are done.
|
|
||||||
|
|
||||||
add tries to be helpful, providing:
|
|
||||||
|
|
||||||
- Sensible defaults
|
|
||||||
|
|
||||||
- (Selective) history awareness: if there are earlier transactions
|
|
||||||
approximately matching the description you enter, the best match will
|
|
||||||
provide defaults for the other fields. If you specify
|
|
||||||
[filter pattern(s)](#filter-patterns) on the command line, only matching
|
|
||||||
transactions will be considered for defaults.
|
|
||||||
|
|
||||||
- Readline-style input: during data entry, the usual editing keys should
|
|
||||||
work.
|
|
||||||
|
|
||||||
- Auto-completion for account names: while entering account names, the tab
|
|
||||||
key will auto-complete as far as possible, or list the available
|
|
||||||
options.
|
|
||||||
|
|
||||||
- Default commodity awareness: if the journal specifies a
|
|
||||||
[default commodity directive](#default-commodity), that will be applied
|
|
||||||
to any bare numbers entered.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
$ hledger add
|
|
||||||
$ hledger -f home.journal add equity:bob
|
|
||||||
|
|
||||||
##### web
|
|
||||||
|
|
||||||
*This is an add-on; see [installing](#installing). Next release, it will be provided by the hledger-web package.*
|
|
||||||
|
|
||||||
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 manually visit the url
|
|
||||||
shown on the console.) The web interface combines the features of the print,
|
|
||||||
register, balance and add commands, and adds a general edit command.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
$ hledger web
|
|
||||||
$ hledger web -E -B --depth 2
|
|
||||||
$ hledger web --port 5010 --base-url http://some.vhost.com --debug -f my.journal
|
|
||||||
|
|
||||||
Warning: unlike all other hledger features, the edit form can alter your
|
|
||||||
existing journal data. You can edit, or erase, the journal file through
|
|
||||||
the web ui. There is currently no access control. A numbered backup of the
|
|
||||||
file will be saved at each edit, in normal circumstances (eg if file
|
|
||||||
permissions allow, disk is not full, etc.)
|
|
||||||
|
|
||||||
There are some options specific to the web server:
|
|
||||||
|
|
||||||
--port=N web: serve on tcp port N (default 5000)
|
|
||||||
|
|
||||||
hledger will serve pages on port 5000 by default.
|
|
||||||
|
|
||||||
--base-url=URL web: use this base url (default http://localhost:PORT)
|
|
||||||
|
|
||||||
Hyperlinks in the web interface all point to "localhost" by default, so if
|
|
||||||
you want to visit the hledger web server from other machines, you'll need
|
|
||||||
to use this option. Just give your machine's host name or ip address
|
|
||||||
instead of localhost. This option may also be useful when running hledger
|
|
||||||
behind a reverse proxy, to conform to your url scheme. Note that the PORT
|
|
||||||
in the base url need not be the same as the `--port` argument.
|
|
||||||
|
|
||||||
#### Other commands
|
|
||||||
|
|
||||||
##### convert
|
|
||||||
|
|
||||||
The convert command reads a
|
The convert command reads a
|
||||||
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file you have
|
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file you have
|
||||||
@ -487,7 +343,7 @@ review FILE.journal for problems; update the rules and convert again if
|
|||||||
needed; and finally copy/paste transactions which are new into your main
|
needed; and finally copy/paste transactions which are new into your main
|
||||||
journal.
|
journal.
|
||||||
|
|
||||||
###### .rules file
|
<!-- ###### .rules file -->
|
||||||
|
|
||||||
convert requires a \*.rules file containing data definitions and rules for
|
convert requires a \*.rules file containing data definitions and rules for
|
||||||
assigning destination accounts to transactions; it will be auto-created if
|
assigning destination accounts to transactions; it will be auto-created if
|
||||||
@ -552,19 +408,161 @@ Notes:
|
|||||||
matched text with `\0` and any regex groups with `\1`, `\2` in the
|
matched text with `\0` and any regex groups with `\1`, `\2` in the
|
||||||
usual way.
|
usual way.
|
||||||
|
|
||||||
|
#### histogram
|
||||||
|
|
||||||
##### test
|
The histogram command displays a quick bar chart showing transaction
|
||||||
|
counts, per day, week, month or other reporting interval. It is
|
||||||
|
experimental.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
$ hledger histogram -p weekly dining
|
||||||
|
|
||||||
|
#### print
|
||||||
|
|
||||||
|
The print command displays full transactions from the journal file, tidily
|
||||||
|
formatted and showing all amounts explicitly. The output of print is
|
||||||
|
always a valid hledger journal.
|
||||||
|
|
||||||
|
hledger's print command also shows all unit prices in effect, or (with
|
||||||
|
-B/--cost) shows cost amounts.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
$ hledger print
|
||||||
|
$ hledger print employees:bob | hledger -f- register expenses
|
||||||
|
|
||||||
|
#### register
|
||||||
|
|
||||||
|
The register command displays postings, one per line, and their running total.
|
||||||
|
With no [filter patterns](#filter-patterns), this is not all that different from [print](#print):
|
||||||
|
|
||||||
|
$ hledger register
|
||||||
|
|
||||||
|
More typically, use it to see a specific account's activity:
|
||||||
|
|
||||||
|
$ hledger register assets:bank:checking
|
||||||
|
|
||||||
|
The `--depth` option limits the amount of sub-account detail displayed:
|
||||||
|
|
||||||
|
$ hledger register assets:bank:checking --depth 2
|
||||||
|
|
||||||
|
With a [reporting interval](#reporting-interval) it shows aggregated
|
||||||
|
summary postings within each interval:
|
||||||
|
|
||||||
|
$ hledger register --monthly rent
|
||||||
|
$ hledger register --monthly -E food --depth 4
|
||||||
|
|
||||||
|
#### stats
|
||||||
|
|
||||||
|
The stats command displays quick summary information for the whole journal,
|
||||||
|
or by period.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
$ hledger stats
|
||||||
|
$ hledger stats -p 'monthly in 2009'
|
||||||
|
|
||||||
|
#### test
|
||||||
|
|
||||||
This command runs hledger's internal self-tests and displays a quick
|
This command runs hledger's internal self-tests and displays a quick
|
||||||
report. The -v option shows more detail, and a pattern can be provided to
|
report. The -v option shows more detail, and a pattern can be provided to
|
||||||
filter tests by name. It's mainly used in development, but it's also nice
|
filter tests by name. It's mainly used in development, but it's also nice
|
||||||
to be able to run a sanity check at any time..
|
to be able to test for smoke at any time.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
||||||
$ hledger test
|
$ hledger test
|
||||||
$ hledger test -v balance
|
$ hledger test -v balance
|
||||||
|
|
||||||
|
#### Add-on commands
|
||||||
|
|
||||||
|
The following commands are optional add-ons. Here is their availability:
|
||||||
|
|
||||||
|
- in the binaries on the download page, they are included where possible
|
||||||
|
*(currently web on all platforms, vty on all but windows, chart on none)*
|
||||||
|
- when cabal installing the current release, they are enabled by flags
|
||||||
|
(see [installing](#installing)).
|
||||||
|
- in the next release, they will be provided by separate packages (eg
|
||||||
|
hledger-web) and invoked by running a similarly-named executable.
|
||||||
|
|
||||||
|
##### chart
|
||||||
|
|
||||||
|
*Requires additional GTK-related libraries and possibly [other things](http://code.haskell.org/gtk2hs/INSTALL). On ubuntu: `apt-get install libghc6-gtk-dev`*
|
||||||
|
|
||||||
|
The chart command saves a pie chart of your top account balances to an
|
||||||
|
image file (usually "hledger.png", or use -o/--output FILE). You can
|
||||||
|
adjust the image resolution with --size=WIDTHxHEIGHT, and the number of
|
||||||
|
accounts with --items=N.
|
||||||
|
|
||||||
|
Note that positive and negative balances will not be displayed together in
|
||||||
|
the same chart; any balances not matching the sign of the first one will
|
||||||
|
be omitted.
|
||||||
|
|
||||||
|
To show only accounts above a certain depth, use the --depth
|
||||||
|
option. Otherwise, the chart can include accounts at any depth. If a
|
||||||
|
parent and child account are both displayed, the parent's balance excludes
|
||||||
|
the child's.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
$ hledger chart assets --depth 2
|
||||||
|
$ hledger chart liabilities --depth 2
|
||||||
|
$ hledger chart ^expenses -o balance.png --size 1000x600 --items 20
|
||||||
|
$ for m in 01 02 03 04 05 06 07 08 09 10 11 12; do hledger -p 2009/$m chart ^expenses --depth 2 -o expenses-2009$m.png --size 400x300; done
|
||||||
|
|
||||||
|
##### vty
|
||||||
|
|
||||||
|
*Not available on microsoft windows, except possibly via cygwin.*
|
||||||
|
|
||||||
|
The vty command starts hledger's curses (full-screen, text) user interface,
|
||||||
|
which allows interactive navigation of the print/register/balance
|
||||||
|
reports. This lets you browse around your numbers and get quick insights
|
||||||
|
with less typing.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
$ hledger vty
|
||||||
|
$ hledger vty -BE food
|
||||||
|
|
||||||
|
##### web
|
||||||
|
|
||||||
|
*Requires GHC 6.12 or greater.*
|
||||||
|
|
||||||
|
Note: this command can edit or overwrite your journal file.
|
||||||
|
|
||||||
|
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 manually visit the url
|
||||||
|
shown on the console.) The web interface combines the features of the print,
|
||||||
|
register, balance and add commands, and adds a general edit command.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
$ hledger web
|
||||||
|
$ hledger web -E -B --depth 2
|
||||||
|
$ hledger web --port 5010 --base-url http://some.vhost.com --debug -f my.journal
|
||||||
|
|
||||||
|
Warning: unlike all other hledger features, the edit form can alter your
|
||||||
|
existing journal data. You can edit, or erase, the journal file through
|
||||||
|
the web ui. There is currently no access control. A numbered backup of the
|
||||||
|
file will be saved at each edit, in normal circumstances (eg if file
|
||||||
|
permissions allow, disk is not full, etc.)
|
||||||
|
|
||||||
|
There are some options specific to the web server:
|
||||||
|
|
||||||
|
--port=N web: serve on tcp port N (default 5000)
|
||||||
|
|
||||||
|
hledger will serve pages on port 5000 by default.
|
||||||
|
|
||||||
|
--base-url=URL web: use this base url (default http://localhost:PORT)
|
||||||
|
|
||||||
|
Hyperlinks in the web interface all point to "localhost" by default, so if
|
||||||
|
you want to visit the hledger web server from other machines, you'll need
|
||||||
|
to use this option. Just give your machine's host name or ip address
|
||||||
|
instead of localhost. This option may also be useful when running hledger
|
||||||
|
behind a reverse proxy, to conform to your url scheme. Note that the PORT
|
||||||
|
in the base url need not be the same as the `--port` argument.
|
||||||
|
|
||||||
### Other features
|
### Other features
|
||||||
|
|
||||||
Here are some additional hledger features and concepts that affect most
|
Here are some additional hledger features and concepts that affect most
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user