;doc: update manuals
This commit is contained in:
Simon Michael
parent
f88501314e
commit
19cc3743a8
@ -45,11 +45,10 @@ transactions, by pressing the F key (or starting with --forecast) to
|
|||||||
enable \[dq]forecast mode\[dq].
|
enable \[dq]forecast mode\[dq].
|
||||||
.SH OPTIONS
|
.SH OPTIONS
|
||||||
.PP
|
.PP
|
||||||
Note: if invoking hledger-ui as a hledger subcommand, write \f[V]--\f[R]
|
|
||||||
before options as shown above.
|
|
||||||
.PP
|
|
||||||
Any QUERYARGS are interpreted as a hledger search query which filters
|
Any QUERYARGS are interpreted as a hledger search query which filters
|
||||||
the data.
|
the data.
|
||||||
|
.PP
|
||||||
|
hledger-ui provides the following options:
|
||||||
.TP
|
.TP
|
||||||
\f[V]-w --watch\f[R]
|
\f[V]-w --watch\f[R]
|
||||||
watch for data and date changes and reload automatically
|
watch for data and date changes and reload automatically
|
||||||
@ -84,7 +83,25 @@ show accounts as a flat list (default)
|
|||||||
\f[V]-t --tree\f[R]
|
\f[V]-t --tree\f[R]
|
||||||
show accounts as a tree
|
show accounts as a tree
|
||||||
.PP
|
.PP
|
||||||
hledger input options:
|
hledger-ui also supports many of hledger\[aq]s general options (and the
|
||||||
|
hledger manual\[aq]s command line tips also apply here):
|
||||||
|
.SS General help options
|
||||||
|
.TP
|
||||||
|
\f[V]-h --help\f[R]
|
||||||
|
show general or COMMAND help
|
||||||
|
.TP
|
||||||
|
\f[V]--man\f[R]
|
||||||
|
show general or COMMAND user manual with man
|
||||||
|
.TP
|
||||||
|
\f[V]--info\f[R]
|
||||||
|
show general or COMMAND user manual with info
|
||||||
|
.TP
|
||||||
|
\f[V]--version\f[R]
|
||||||
|
show general or ADDONCMD version
|
||||||
|
.TP
|
||||||
|
\f[V]--debug[=N]\f[R]
|
||||||
|
show debug output (levels 1-9, default: 1)
|
||||||
|
.SS General input options
|
||||||
.TP
|
.TP
|
||||||
\f[V]-f FILE --file=FILE\f[R]
|
\f[V]-f FILE --file=FILE\f[R]
|
||||||
use a different input file.
|
use a different input file.
|
||||||
@ -112,8 +129,7 @@ assignments)
|
|||||||
.TP
|
.TP
|
||||||
\f[V]-s --strict\f[R]
|
\f[V]-s --strict\f[R]
|
||||||
do extra error checking (check that all posted accounts are declared)
|
do extra error checking (check that all posted accounts are declared)
|
||||||
.PP
|
.SS General reporting options
|
||||||
hledger reporting options:
|
|
||||||
.TP
|
.TP
|
||||||
\f[V]-b --begin=DATE\f[R]
|
\f[V]-b --begin=DATE\f[R]
|
||||||
include postings/txns on or after this date (will be adjusted to
|
include postings/txns on or after this date (will be adjusted to
|
||||||
@ -229,27 +245,6 @@ When a reporting option appears more than once in the command line, the
|
|||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
.PP
|
.PP
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
.PP
|
|
||||||
hledger help options:
|
|
||||||
.TP
|
|
||||||
\f[V]-h --help\f[R]
|
|
||||||
show general or COMMAND help
|
|
||||||
.TP
|
|
||||||
\f[V]--man\f[R]
|
|
||||||
show general or COMMAND user manual with man
|
|
||||||
.TP
|
|
||||||
\f[V]--info\f[R]
|
|
||||||
show general or COMMAND user manual with info
|
|
||||||
.TP
|
|
||||||
\f[V]--version\f[R]
|
|
||||||
show general or ADDONCMD version
|
|
||||||
.TP
|
|
||||||
\f[V]--debug[=N]\f[R]
|
|
||||||
show debug output (levels 1-9, default: 1)
|
|
||||||
.PP
|
|
||||||
A \[at]FILE argument will be expanded to the contents of FILE, which
|
|
||||||
should contain one command line option/argument per line.
|
|
||||||
(To prevent this, insert a \f[V]--\f[R] argument before.)
|
|
||||||
.SH MOUSE
|
.SH MOUSE
|
||||||
.PP
|
.PP
|
||||||
In most modern terminals, you can navigate through the screens with a
|
In most modern terminals, you can navigate through the screens with a
|
||||||
|
|||||||
@ -58,12 +58,11 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top
|
|||||||
1 OPTIONS
|
1 OPTIONS
|
||||||
*********
|
*********
|
||||||
|
|
||||||
Note: if invoking hledger-ui as a hledger subcommand, write '--' before
|
Any QUERYARGS are interpreted as a hledger search query which filters
|
||||||
options as shown above.
|
|
||||||
|
|
||||||
Any QUERYARGS are interpreted as a hledger search query which filters
|
|
||||||
the data.
|
the data.
|
||||||
|
|
||||||
|
hledger-ui provides the following options:
|
||||||
|
|
||||||
'-w --watch'
|
'-w --watch'
|
||||||
|
|
||||||
watch for data and date changes and reload automatically
|
watch for data and date changes and reload automatically
|
||||||
@ -99,7 +98,42 @@ the data.
|
|||||||
|
|
||||||
show accounts as a tree
|
show accounts as a tree
|
||||||
|
|
||||||
hledger input options:
|
hledger-ui also supports many of hledger's general options (and the
|
||||||
|
hledger manual's command line tips also apply here):
|
||||||
|
|
||||||
|
* Menu:
|
||||||
|
|
||||||
|
* General help options::
|
||||||
|
* General input options::
|
||||||
|
* General reporting options::
|
||||||
|
|
||||||
|
|
||||||
|
File: hledger-ui.info, Node: General help options, Next: General input options, Up: OPTIONS
|
||||||
|
|
||||||
|
1.1 General help options
|
||||||
|
========================
|
||||||
|
|
||||||
|
'-h --help'
|
||||||
|
|
||||||
|
show general or COMMAND help
|
||||||
|
'--man'
|
||||||
|
|
||||||
|
show general or COMMAND user manual with man
|
||||||
|
'--info'
|
||||||
|
|
||||||
|
show general or COMMAND user manual with info
|
||||||
|
'--version'
|
||||||
|
|
||||||
|
show general or ADDONCMD version
|
||||||
|
'--debug[=N]'
|
||||||
|
|
||||||
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
|
|
||||||
|
File: hledger-ui.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: OPTIONS
|
||||||
|
|
||||||
|
1.2 General input options
|
||||||
|
=========================
|
||||||
|
|
||||||
'-f FILE --file=FILE'
|
'-f FILE --file=FILE'
|
||||||
|
|
||||||
@ -129,7 +163,11 @@ the data.
|
|||||||
do extra error checking (check that all posted accounts are
|
do extra error checking (check that all posted accounts are
|
||||||
declared)
|
declared)
|
||||||
|
|
||||||
hledger reporting options:
|
|
||||||
|
File: hledger-ui.info, Node: General reporting options, Prev: General input options, Up: OPTIONS
|
||||||
|
|
||||||
|
1.3 General reporting options
|
||||||
|
=============================
|
||||||
|
|
||||||
'-b --begin=DATE'
|
'-b --begin=DATE'
|
||||||
|
|
||||||
@ -246,28 +284,6 @@ the last one takes precedence.
|
|||||||
|
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
|
|
||||||
hledger help options:
|
|
||||||
|
|
||||||
'-h --help'
|
|
||||||
|
|
||||||
show general or COMMAND help
|
|
||||||
'--man'
|
|
||||||
|
|
||||||
show general or COMMAND user manual with man
|
|
||||||
'--info'
|
|
||||||
|
|
||||||
show general or COMMAND user manual with info
|
|
||||||
'--version'
|
|
||||||
|
|
||||||
show general or ADDONCMD version
|
|
||||||
'--debug[=N]'
|
|
||||||
|
|
||||||
show debug output (levels 1-9, default: 1)
|
|
||||||
|
|
||||||
A @FILE argument will be expanded to the contents of FILE, which
|
|
||||||
should contain one command line option/argument per line. (To prevent
|
|
||||||
this, insert a '--' argument before.)
|
|
||||||
|
|
||||||
|
|
||||||
File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top
|
||||||
|
|
||||||
@ -651,38 +667,44 @@ Tag Table:
|
|||||||
Node: Top223
|
Node: Top223
|
||||||
Node: OPTIONS1838
|
Node: OPTIONS1838
|
||||||
Ref: #options1936
|
Ref: #options1936
|
||||||
Node: MOUSE7432
|
Node: General help options2959
|
||||||
Ref: #mouse7527
|
Ref: #general-help-options3108
|
||||||
Node: KEYS7764
|
Node: General input options3390
|
||||||
Ref: #keys7857
|
Ref: #general-input-options3575
|
||||||
Node: SCREENS12370
|
Node: General reporting options4277
|
||||||
Ref: #screens12468
|
Ref: #general-reporting-options4441
|
||||||
Node: Menu13048
|
Node: MOUSE7831
|
||||||
Ref: #menu13141
|
Ref: #mouse7926
|
||||||
Node: Cash accounts13336
|
Node: KEYS8163
|
||||||
Ref: #cash-accounts13478
|
Ref: #keys8256
|
||||||
Node: Balance sheet accounts13662
|
Node: SCREENS12769
|
||||||
Ref: #balance-sheet-accounts13843
|
Ref: #screens12867
|
||||||
Node: Income statement accounts13963
|
Node: Menu13447
|
||||||
Ref: #income-statement-accounts14149
|
Ref: #menu13540
|
||||||
Node: All accounts14313
|
Node: Cash accounts13735
|
||||||
Ref: #all-accounts14459
|
Ref: #cash-accounts13877
|
||||||
Node: Register14641
|
Node: Balance sheet accounts14061
|
||||||
Ref: #register14765
|
Ref: #balance-sheet-accounts14242
|
||||||
Node: Transaction16727
|
Node: Income statement accounts14362
|
||||||
Ref: #transaction16850
|
Ref: #income-statement-accounts14548
|
||||||
Node: Error18267
|
Node: All accounts14712
|
||||||
Ref: #error18361
|
Ref: #all-accounts14858
|
||||||
Node: TIPS18605
|
Node: Register15040
|
||||||
Ref: #tips18704
|
Ref: #register15164
|
||||||
Node: Watch mode18746
|
Node: Transaction17126
|
||||||
Ref: #watch-mode18853
|
Ref: #transaction17249
|
||||||
Node: Debug output20312
|
Node: Error18666
|
||||||
Ref: #debug-output20423
|
Ref: #error18760
|
||||||
Node: ENVIRONMENT20635
|
Node: TIPS19004
|
||||||
Ref: #environment20745
|
Ref: #tips19103
|
||||||
Node: BUGS20936
|
Node: Watch mode19145
|
||||||
Ref: #bugs21019
|
Ref: #watch-mode19252
|
||||||
|
Node: Debug output20711
|
||||||
|
Ref: #debug-output20822
|
||||||
|
Node: ENVIRONMENT21034
|
||||||
|
Ref: #environment21144
|
||||||
|
Node: BUGS21335
|
||||||
|
Ref: #bugs21418
|
||||||
|
|
||||||
End Tag Table
|
End Tag Table
|
||||||
|
|
||||||
|
|||||||
@ -38,12 +38,11 @@ DESCRIPTION
|
|||||||
enable "forecast mode".
|
enable "forecast mode".
|
||||||
|
|
||||||
OPTIONS
|
OPTIONS
|
||||||
Note: if invoking hledger-ui as a hledger subcommand, write -- before
|
Any QUERYARGS are interpreted as a hledger search query which filters
|
||||||
options as shown above.
|
|
||||||
|
|
||||||
Any QUERYARGS are interpreted as a hledger search query which filters
|
|
||||||
the data.
|
the data.
|
||||||
|
|
||||||
|
hledger-ui provides the following options:
|
||||||
|
|
||||||
-w --watch
|
-w --watch
|
||||||
watch for data and date changes and reload automatically
|
watch for data and date changes and reload automatically
|
||||||
|
|
||||||
@ -64,7 +63,7 @@ OPTIONS
|
|||||||
start in the (first) matched account's register screen
|
start in the (first) matched account's register screen
|
||||||
|
|
||||||
--change
|
--change
|
||||||
show period balances (changes) at startup instead of historical
|
show period balances (changes) at startup instead of historical
|
||||||
balances
|
balances
|
||||||
|
|
||||||
-l --flat
|
-l --flat
|
||||||
@ -73,8 +72,24 @@ OPTIONS
|
|||||||
-t --tree
|
-t --tree
|
||||||
show accounts as a tree
|
show accounts as a tree
|
||||||
|
|
||||||
hledger input options:
|
hledger-ui also supports many of hledger's general options (and the
|
||||||
|
hledger manual's command line tips also apply here):
|
||||||
|
|
||||||
|
General help options
|
||||||
|
-h --help
|
||||||
|
show general or COMMAND help
|
||||||
|
|
||||||
|
--man show general or COMMAND user manual with man
|
||||||
|
|
||||||
|
--info show general or COMMAND user manual with info
|
||||||
|
|
||||||
|
--version
|
||||||
|
show general or ADDONCMD version
|
||||||
|
|
||||||
|
--debug[=N]
|
||||||
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
|
General input options
|
||||||
-f FILE --file=FILE
|
-f FILE --file=FILE
|
||||||
use a different input file. For stdin, use - (default:
|
use a different input file. For stdin, use - (default:
|
||||||
$LEDGER_FILE or $HOME/.hledger.journal)
|
$LEDGER_FILE or $HOME/.hledger.journal)
|
||||||
@ -102,8 +117,7 @@ OPTIONS
|
|||||||
do extra error checking (check that all posted accounts are de-
|
do extra error checking (check that all posted accounts are de-
|
||||||
clared)
|
clared)
|
||||||
|
|
||||||
hledger reporting options:
|
General reporting options
|
||||||
|
|
||||||
-b --begin=DATE
|
-b --begin=DATE
|
||||||
include postings/txns on or after this date (will be adjusted to
|
include postings/txns on or after this date (will be adjusted to
|
||||||
preceding subperiod start when using a report interval)
|
preceding subperiod start when using a report interval)
|
||||||
@ -218,25 +232,6 @@ OPTIONS
|
|||||||
|
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
|
|
||||||
hledger help options:
|
|
||||||
|
|
||||||
-h --help
|
|
||||||
show general or COMMAND help
|
|
||||||
|
|
||||||
--man show general or COMMAND user manual with man
|
|
||||||
|
|
||||||
--info show general or COMMAND user manual with info
|
|
||||||
|
|
||||||
--version
|
|
||||||
show general or ADDONCMD version
|
|
||||||
|
|
||||||
--debug[=N]
|
|
||||||
show debug output (levels 1-9, default: 1)
|
|
||||||
|
|
||||||
A @FILE argument will be expanded to the contents of FILE, which should
|
|
||||||
contain one command line option/argument per line. (To prevent this,
|
|
||||||
insert a -- argument before.)
|
|
||||||
|
|
||||||
MOUSE
|
MOUSE
|
||||||
In most modern terminals, you can navigate through the screens with a
|
In most modern terminals, you can navigate through the screens with a
|
||||||
mouse or touchpad:
|
mouse or touchpad:
|
||||||
|
|||||||
@ -76,8 +76,7 @@ on the data.
|
|||||||
These filter options are not shown in the web UI, but it will be applied
|
These filter options are not shown in the web UI, but it will be applied
|
||||||
in addition to any search query entered there.
|
in addition to any search query entered there.
|
||||||
.PP
|
.PP
|
||||||
Note: if invoking hledger-web as a hledger subcommand, write
|
hledger-web provides the following options:
|
||||||
\f[V]--\f[R] before options, as shown in the synopsis above.
|
|
||||||
.TP
|
.TP
|
||||||
\f[V]--serve\f[R]
|
\f[V]--serve\f[R]
|
||||||
serve and log requests, don\[aq]t browse or auto-exit after timeout
|
serve and log requests, don\[aq]t browse or auto-exit after timeout
|
||||||
@ -122,7 +121,64 @@ X-Sandstorm-Permissions (default: disabled)
|
|||||||
run hledger-web\[aq]s tests and exit.
|
run hledger-web\[aq]s tests and exit.
|
||||||
hspec test runner args may follow a --, eg: hledger-web --test -- --help
|
hspec test runner args may follow a --, eg: hledger-web --test -- --help
|
||||||
.PP
|
.PP
|
||||||
hledger input options:
|
By default the server listens on IP address 127.0.0.1, accessible only
|
||||||
|
to local requests.
|
||||||
|
You can use \f[V]--host\f[R] to change this, eg \f[V]--host 0.0.0.0\f[R]
|
||||||
|
to listen on all configured addresses.
|
||||||
|
.PP
|
||||||
|
Similarly, use \f[V]--port\f[R] to set a TCP port other than 5000, eg if
|
||||||
|
you are running multiple hledger-web instances.
|
||||||
|
.PP
|
||||||
|
Both of these options are ignored when \f[V]--socket\f[R] is used.
|
||||||
|
In this case, it creates an \f[V]AF_UNIX\f[R] socket file at the
|
||||||
|
supplied path and uses that for communication.
|
||||||
|
This is an alternative way of running multiple hledger-web instances
|
||||||
|
behind a reverse proxy that handles authentication for different users.
|
||||||
|
The path can be derived in a predictable way, eg by using the username
|
||||||
|
within the path.
|
||||||
|
As an example, \f[V]nginx\f[R] as reverse proxy can use the variable
|
||||||
|
\f[V]$remote_user\f[R] to derive a path from the username used in a HTTP
|
||||||
|
basic authentication.
|
||||||
|
The following \f[V]proxy_pass\f[R] directive allows access to all
|
||||||
|
\f[V]hledger-web\f[R] instances that created a socket in
|
||||||
|
\f[V]/tmp/hledger/\f[R]:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
You can use \f[V]--base-url\f[R] to change the protocol, hostname, port
|
||||||
|
and path that appear in hyperlinks, useful eg for integrating
|
||||||
|
hledger-web within a larger website.
|
||||||
|
The default is \f[V]http://HOST:PORT/\f[R] using the server\[aq]s
|
||||||
|
configured host address and TCP port (or \f[V]http://HOST\f[R] if PORT
|
||||||
|
is 80).
|
||||||
|
.PP
|
||||||
|
With \f[V]--file-url\f[R] you can set a different base url for static
|
||||||
|
files, eg for better caching or cookie-less serving on high performance
|
||||||
|
websites.
|
||||||
|
.PP
|
||||||
|
hledger-web also supports many of hledger\[aq]s general options (and the
|
||||||
|
hledger manual\[aq]s command line tips also apply here):
|
||||||
|
.SS General help options
|
||||||
|
.TP
|
||||||
|
\f[V]-h --help\f[R]
|
||||||
|
show general or COMMAND help
|
||||||
|
.TP
|
||||||
|
\f[V]--man\f[R]
|
||||||
|
show general or COMMAND user manual with man
|
||||||
|
.TP
|
||||||
|
\f[V]--info\f[R]
|
||||||
|
show general or COMMAND user manual with info
|
||||||
|
.TP
|
||||||
|
\f[V]--version\f[R]
|
||||||
|
show general or ADDONCMD version
|
||||||
|
.TP
|
||||||
|
\f[V]--debug[=N]\f[R]
|
||||||
|
show debug output (levels 1-9, default: 1)
|
||||||
|
.SS General input options
|
||||||
.TP
|
.TP
|
||||||
\f[V]-f FILE --file=FILE\f[R]
|
\f[V]-f FILE --file=FILE\f[R]
|
||||||
use a different input file.
|
use a different input file.
|
||||||
@ -150,8 +206,7 @@ assignments)
|
|||||||
.TP
|
.TP
|
||||||
\f[V]-s --strict\f[R]
|
\f[V]-s --strict\f[R]
|
||||||
do extra error checking (check that all posted accounts are declared)
|
do extra error checking (check that all posted accounts are declared)
|
||||||
.PP
|
.SS General reporting options
|
||||||
hledger reporting options:
|
|
||||||
.TP
|
.TP
|
||||||
\f[V]-b --begin=DATE\f[R]
|
\f[V]-b --begin=DATE\f[R]
|
||||||
include postings/txns on or after this date (will be adjusted to
|
include postings/txns on or after this date (will be adjusted to
|
||||||
@ -267,66 +322,6 @@ When a reporting option appears more than once in the command line, the
|
|||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
.PP
|
.PP
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
.PP
|
|
||||||
hledger help options:
|
|
||||||
.TP
|
|
||||||
\f[V]-h --help\f[R]
|
|
||||||
show general or COMMAND help
|
|
||||||
.TP
|
|
||||||
\f[V]--man\f[R]
|
|
||||||
show general or COMMAND user manual with man
|
|
||||||
.TP
|
|
||||||
\f[V]--info\f[R]
|
|
||||||
show general or COMMAND user manual with info
|
|
||||||
.TP
|
|
||||||
\f[V]--version\f[R]
|
|
||||||
show general or ADDONCMD version
|
|
||||||
.TP
|
|
||||||
\f[V]--debug[=N]\f[R]
|
|
||||||
show debug output (levels 1-9, default: 1)
|
|
||||||
.PP
|
|
||||||
A \[at]FILE argument will be expanded to the contents of FILE, which
|
|
||||||
should contain one command line option/argument per line.
|
|
||||||
(To prevent this, insert a \f[V]--\f[R] argument before.)
|
|
||||||
.PP
|
|
||||||
By default the server listens on IP address 127.0.0.1, accessible only
|
|
||||||
to local requests.
|
|
||||||
You can use \f[V]--host\f[R] to change this, eg \f[V]--host 0.0.0.0\f[R]
|
|
||||||
to listen on all configured addresses.
|
|
||||||
.PP
|
|
||||||
Similarly, use \f[V]--port\f[R] to set a TCP port other than 5000, eg if
|
|
||||||
you are running multiple hledger-web instances.
|
|
||||||
.PP
|
|
||||||
Both of these options are ignored when \f[V]--socket\f[R] is used.
|
|
||||||
In this case, it creates an \f[V]AF_UNIX\f[R] socket file at the
|
|
||||||
supplied path and uses that for communication.
|
|
||||||
This is an alternative way of running multiple hledger-web instances
|
|
||||||
behind a reverse proxy that handles authentication for different users.
|
|
||||||
The path can be derived in a predictable way, eg by using the username
|
|
||||||
within the path.
|
|
||||||
As an example, \f[V]nginx\f[R] as reverse proxy can use the variable
|
|
||||||
\f[V]$remote_user\f[R] to derive a path from the username used in a HTTP
|
|
||||||
basic authentication.
|
|
||||||
The following \f[V]proxy_pass\f[R] directive allows access to all
|
|
||||||
\f[V]hledger-web\f[R] instances that created a socket in
|
|
||||||
\f[V]/tmp/hledger/\f[R]:
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
You can use \f[V]--base-url\f[R] to change the protocol, hostname, port
|
|
||||||
and path that appear in hyperlinks, useful eg for integrating
|
|
||||||
hledger-web within a larger website.
|
|
||||||
The default is \f[V]http://HOST:PORT/\f[R] using the server\[aq]s
|
|
||||||
configured host address and TCP port (or \f[V]http://HOST\f[R] if PORT
|
|
||||||
is 80).
|
|
||||||
.PP
|
|
||||||
With \f[V]--file-url\f[R] you can set a different base url for static
|
|
||||||
files, eg for better caching or cookie-less serving on high performance
|
|
||||||
websites.
|
|
||||||
.SH PERMISSIONS
|
.SH PERMISSIONS
|
||||||
.PP
|
.PP
|
||||||
By default, hledger-web allows anyone who can reach it to view the
|
By default, hledger-web allows anyone who can reach it to view the
|
||||||
|
|||||||
@ -81,8 +81,7 @@ Command-line options and arguments may be used to set an initial filter
|
|||||||
on the data. These filter options are not shown in the web UI, but it
|
on the data. These filter options are not shown in the web UI, but it
|
||||||
will be applied in addition to any search query entered there.
|
will be applied in addition to any search query entered there.
|
||||||
|
|
||||||
Note: if invoking hledger-web as a hledger subcommand, write '--'
|
hledger-web provides the following options:
|
||||||
before options, as shown in the synopsis above.
|
|
||||||
|
|
||||||
'--serve'
|
'--serve'
|
||||||
|
|
||||||
@ -126,7 +125,72 @@ before options, as shown in the synopsis above.
|
|||||||
run hledger-web's tests and exit. hspec test runner args may
|
run hledger-web's tests and exit. hspec test runner args may
|
||||||
follow a -, eg: hledger-web -test - -help
|
follow a -, eg: hledger-web -test - -help
|
||||||
|
|
||||||
hledger input options:
|
By default the server listens on IP address 127.0.0.1, accessible
|
||||||
|
only to local requests. You can use '--host' to change this, eg '--host
|
||||||
|
0.0.0.0' to listen on all configured addresses.
|
||||||
|
|
||||||
|
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
||||||
|
are running multiple hledger-web instances.
|
||||||
|
|
||||||
|
Both of these options are ignored when '--socket' is used. In this
|
||||||
|
case, it creates an 'AF_UNIX' socket file at the supplied path and uses
|
||||||
|
that for communication. This is an alternative way of running multiple
|
||||||
|
hledger-web instances behind a reverse proxy that handles authentication
|
||||||
|
for different users. The path can be derived in a predictable way, eg
|
||||||
|
by using the username within the path. As an example, 'nginx' as
|
||||||
|
reverse proxy can use the variable '$remote_user' to derive a path from
|
||||||
|
the username used in a HTTP basic authentication. The following
|
||||||
|
'proxy_pass' directive allows access to all 'hledger-web' instances that
|
||||||
|
created a socket in '/tmp/hledger/':
|
||||||
|
|
||||||
|
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||||
|
|
||||||
|
You can use '--base-url' to change the protocol, hostname, port and
|
||||||
|
path that appear in hyperlinks, useful eg for integrating hledger-web
|
||||||
|
within a larger website. The default is 'http://HOST:PORT/' using the
|
||||||
|
server's configured host address and TCP port (or 'http://HOST' if PORT
|
||||||
|
is 80).
|
||||||
|
|
||||||
|
With '--file-url' you can set a different base url for static files,
|
||||||
|
eg for better caching or cookie-less serving on high performance
|
||||||
|
websites.
|
||||||
|
|
||||||
|
hledger-web also supports many of hledger's general options (and the
|
||||||
|
hledger manual's command line tips also apply here):
|
||||||
|
|
||||||
|
* Menu:
|
||||||
|
|
||||||
|
* General help options::
|
||||||
|
* General input options::
|
||||||
|
* General reporting options::
|
||||||
|
|
||||||
|
|
||||||
|
File: hledger-web.info, Node: General help options, Next: General input options, Up: OPTIONS
|
||||||
|
|
||||||
|
1.1 General help options
|
||||||
|
========================
|
||||||
|
|
||||||
|
'-h --help'
|
||||||
|
|
||||||
|
show general or COMMAND help
|
||||||
|
'--man'
|
||||||
|
|
||||||
|
show general or COMMAND user manual with man
|
||||||
|
'--info'
|
||||||
|
|
||||||
|
show general or COMMAND user manual with info
|
||||||
|
'--version'
|
||||||
|
|
||||||
|
show general or ADDONCMD version
|
||||||
|
'--debug[=N]'
|
||||||
|
|
||||||
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
|
|
||||||
|
File: hledger-web.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: OPTIONS
|
||||||
|
|
||||||
|
1.2 General input options
|
||||||
|
=========================
|
||||||
|
|
||||||
'-f FILE --file=FILE'
|
'-f FILE --file=FILE'
|
||||||
|
|
||||||
@ -156,7 +220,11 @@ before options, as shown in the synopsis above.
|
|||||||
do extra error checking (check that all posted accounts are
|
do extra error checking (check that all posted accounts are
|
||||||
declared)
|
declared)
|
||||||
|
|
||||||
hledger reporting options:
|
|
||||||
|
File: hledger-web.info, Node: General reporting options, Prev: General input options, Up: OPTIONS
|
||||||
|
|
||||||
|
1.3 General reporting options
|
||||||
|
=============================
|
||||||
|
|
||||||
'-b --begin=DATE'
|
'-b --begin=DATE'
|
||||||
|
|
||||||
@ -273,58 +341,6 @@ the last one takes precedence.
|
|||||||
|
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
|
|
||||||
hledger help options:
|
|
||||||
|
|
||||||
'-h --help'
|
|
||||||
|
|
||||||
show general or COMMAND help
|
|
||||||
'--man'
|
|
||||||
|
|
||||||
show general or COMMAND user manual with man
|
|
||||||
'--info'
|
|
||||||
|
|
||||||
show general or COMMAND user manual with info
|
|
||||||
'--version'
|
|
||||||
|
|
||||||
show general or ADDONCMD version
|
|
||||||
'--debug[=N]'
|
|
||||||
|
|
||||||
show debug output (levels 1-9, default: 1)
|
|
||||||
|
|
||||||
A @FILE argument will be expanded to the contents of FILE, which
|
|
||||||
should contain one command line option/argument per line. (To prevent
|
|
||||||
this, insert a '--' argument before.)
|
|
||||||
|
|
||||||
By default the server listens on IP address 127.0.0.1, accessible
|
|
||||||
only to local requests. You can use '--host' to change this, eg '--host
|
|
||||||
0.0.0.0' to listen on all configured addresses.
|
|
||||||
|
|
||||||
Similarly, use '--port' to set a TCP port other than 5000, eg if you
|
|
||||||
are running multiple hledger-web instances.
|
|
||||||
|
|
||||||
Both of these options are ignored when '--socket' is used. In this
|
|
||||||
case, it creates an 'AF_UNIX' socket file at the supplied path and uses
|
|
||||||
that for communication. This is an alternative way of running multiple
|
|
||||||
hledger-web instances behind a reverse proxy that handles authentication
|
|
||||||
for different users. The path can be derived in a predictable way, eg
|
|
||||||
by using the username within the path. As an example, 'nginx' as
|
|
||||||
reverse proxy can use the variable '$remote_user' to derive a path from
|
|
||||||
the username used in a HTTP basic authentication. The following
|
|
||||||
'proxy_pass' directive allows access to all 'hledger-web' instances that
|
|
||||||
created a socket in '/tmp/hledger/':
|
|
||||||
|
|
||||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
|
||||||
|
|
||||||
You can use '--base-url' to change the protocol, hostname, port and
|
|
||||||
path that appear in hyperlinks, useful eg for integrating hledger-web
|
|
||||||
within a larger website. The default is 'http://HOST:PORT/' using the
|
|
||||||
server's configured host address and TCP port (or 'http://HOST' if PORT
|
|
||||||
is 80).
|
|
||||||
|
|
||||||
With '--file-url' you can set a different base url for static files,
|
|
||||||
eg for better caching or cookie-less serving on high performance
|
|
||||||
websites.
|
|
||||||
|
|
||||||
|
|
||||||
File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
|
File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
|
||||||
|
|
||||||
@ -634,22 +650,28 @@ Tag Table:
|
|||||||
Node: Top225
|
Node: Top225
|
||||||
Node: OPTIONS2702
|
Node: OPTIONS2702
|
||||||
Ref: #options2807
|
Ref: #options2807
|
||||||
Node: PERMISSIONS10607
|
Node: General help options6118
|
||||||
Ref: #permissions10746
|
Ref: #general-help-options6268
|
||||||
Node: EDITING UPLOADING DOWNLOADING11958
|
Node: General input options6550
|
||||||
Ref: #editing-uploading-downloading12139
|
Ref: #general-input-options6736
|
||||||
Node: RELOADING12973
|
Node: General reporting options7438
|
||||||
Ref: #reloading13107
|
Ref: #general-reporting-options7603
|
||||||
Node: JSON API13540
|
Node: PERMISSIONS10993
|
||||||
Ref: #json-api13655
|
Ref: #permissions11132
|
||||||
Node: DEBUG OUTPUT19143
|
Node: EDITING UPLOADING DOWNLOADING12344
|
||||||
Ref: #debug-output19268
|
Ref: #editing-uploading-downloading12525
|
||||||
Node: Debug output19295
|
Node: RELOADING13359
|
||||||
Ref: #debug-output-119396
|
Ref: #reloading13493
|
||||||
Node: ENVIRONMENT19813
|
Node: JSON API13926
|
||||||
Ref: #environment19932
|
Ref: #json-api14041
|
||||||
Node: BUGS20049
|
Node: DEBUG OUTPUT19529
|
||||||
Ref: #bugs20133
|
Ref: #debug-output19654
|
||||||
|
Node: Debug output19681
|
||||||
|
Ref: #debug-output-119782
|
||||||
|
Node: ENVIRONMENT20199
|
||||||
|
Ref: #environment20318
|
||||||
|
Node: BUGS20435
|
||||||
|
Ref: #bugs20519
|
||||||
|
|
||||||
End Tag Table
|
End Tag Table
|
||||||
|
|
||||||
|
|||||||
@ -60,14 +60,13 @@ OPTIONS
|
|||||||
on the data. These filter options are not shown in the web UI, but it
|
on the data. These filter options are not shown in the web UI, but it
|
||||||
will be applied in addition to any search query entered there.
|
will be applied in addition to any search query entered there.
|
||||||
|
|
||||||
Note: if invoking hledger-web as a hledger subcommand, write -- before
|
hledger-web provides the following options:
|
||||||
options, as shown in the synopsis above.
|
|
||||||
|
|
||||||
--serve
|
--serve
|
||||||
serve and log requests, don't browse or auto-exit after timeout
|
serve and log requests, don't browse or auto-exit after timeout
|
||||||
|
|
||||||
--serve-api
|
--serve-api
|
||||||
like --serve, but serve only the JSON web API, without the
|
like --serve, but serve only the JSON web API, without the
|
||||||
server-side web UI
|
server-side web UI
|
||||||
|
|
||||||
--host=IPADDR
|
--host=IPADDR
|
||||||
@ -77,34 +76,78 @@ OPTIONS
|
|||||||
listen on this TCP port (default: 5000)
|
listen on this TCP port (default: 5000)
|
||||||
|
|
||||||
--socket=SOCKETFILE
|
--socket=SOCKETFILE
|
||||||
use a unix domain socket file to listen for requests instead of
|
use a unix domain socket file to listen for requests instead of
|
||||||
a TCP socket. Implies --serve. It can only be used if the op-
|
a TCP socket. Implies --serve. It can only be used if the op-
|
||||||
erating system can provide this type of socket.
|
erating system can provide this type of socket.
|
||||||
|
|
||||||
--base-url=URL
|
--base-url=URL
|
||||||
set the base url (default: http://IPADDR:PORT). Note: affects
|
set the base url (default: http://IPADDR:PORT). Note: affects
|
||||||
url generation but not route parsing. Can be useful if running
|
url generation but not route parsing. Can be useful if running
|
||||||
behind a reverse web proxy that does path rewriting.
|
behind a reverse web proxy that does path rewriting.
|
||||||
|
|
||||||
--file-url=URL
|
--file-url=URL
|
||||||
set the static files url (default: BASEURL/static). hledger-web
|
set the static files url (default: BASEURL/static). hledger-web
|
||||||
normally serves static files itself, but if you wanted to serve
|
normally serves static files itself, but if you wanted to serve
|
||||||
them from another server for efficiency, you would set the url
|
them from another server for efficiency, you would set the url
|
||||||
with this.
|
with this.
|
||||||
|
|
||||||
--capabilities=CAP[,CAP..]
|
--capabilities=CAP[,CAP..]
|
||||||
enable the view, add, and/or manage capabilities (default:
|
enable the view, add, and/or manage capabilities (default:
|
||||||
view,add)
|
view,add)
|
||||||
|
|
||||||
--capabilities-header=HTTPHEADER
|
--capabilities-header=HTTPHEADER
|
||||||
read capabilities to enable from a HTTP header, like X-Sand-
|
read capabilities to enable from a HTTP header, like X-Sand-
|
||||||
storm-Permissions (default: disabled)
|
storm-Permissions (default: disabled)
|
||||||
|
|
||||||
--test run hledger-web's tests and exit. hspec test runner args may
|
--test run hledger-web's tests and exit. hspec test runner args may
|
||||||
follow a --, eg: hledger-web --test -- --help
|
follow a --, eg: hledger-web --test -- --help
|
||||||
|
|
||||||
hledger input options:
|
By default the server listens on IP address 127.0.0.1, accessible only
|
||||||
|
to local requests. You can use --host to change this, eg --host
|
||||||
|
0.0.0.0 to listen on all configured addresses.
|
||||||
|
|
||||||
|
Similarly, use --port to set a TCP port other than 5000, eg if you are
|
||||||
|
running multiple hledger-web instances.
|
||||||
|
|
||||||
|
Both of these options are ignored when --socket is used. In this case,
|
||||||
|
it creates an AF_UNIX socket file at the supplied path and uses that
|
||||||
|
for communication. This is an alternative way of running multiple
|
||||||
|
hledger-web instances behind a reverse proxy that handles authentica-
|
||||||
|
tion for different users. The path can be derived in a predictable
|
||||||
|
way, eg by using the username within the path. As an example, nginx as
|
||||||
|
reverse proxy can use the variable $remote_user to derive a path from
|
||||||
|
the username used in a HTTP basic authentication. The following
|
||||||
|
proxy_pass directive allows access to all hledger-web instances that
|
||||||
|
created a socket in /tmp/hledger/:
|
||||||
|
|
||||||
|
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
||||||
|
|
||||||
|
You can use --base-url to change the protocol, hostname, port and path
|
||||||
|
that appear in hyperlinks, useful eg for integrating hledger-web within
|
||||||
|
a larger website. The default is http://HOST:PORT/ using the server's
|
||||||
|
configured host address and TCP port (or http://HOST if PORT is 80).
|
||||||
|
|
||||||
|
With --file-url you can set a different base url for static files, eg
|
||||||
|
for better caching or cookie-less serving on high performance websites.
|
||||||
|
|
||||||
|
hledger-web also supports many of hledger's general options (and the
|
||||||
|
hledger manual's command line tips also apply here):
|
||||||
|
|
||||||
|
General help options
|
||||||
|
-h --help
|
||||||
|
show general or COMMAND help
|
||||||
|
|
||||||
|
--man show general or COMMAND user manual with man
|
||||||
|
|
||||||
|
--info show general or COMMAND user manual with info
|
||||||
|
|
||||||
|
--version
|
||||||
|
show general or ADDONCMD version
|
||||||
|
|
||||||
|
--debug[=N]
|
||||||
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
|
General input options
|
||||||
-f FILE --file=FILE
|
-f FILE --file=FILE
|
||||||
use a different input file. For stdin, use - (default:
|
use a different input file. For stdin, use - (default:
|
||||||
$LEDGER_FILE or $HOME/.hledger.journal)
|
$LEDGER_FILE or $HOME/.hledger.journal)
|
||||||
@ -132,8 +175,7 @@ OPTIONS
|
|||||||
do extra error checking (check that all posted accounts are de-
|
do extra error checking (check that all posted accounts are de-
|
||||||
clared)
|
clared)
|
||||||
|
|
||||||
hledger reporting options:
|
General reporting options
|
||||||
|
|
||||||
-b --begin=DATE
|
-b --begin=DATE
|
||||||
include postings/txns on or after this date (will be adjusted to
|
include postings/txns on or after this date (will be adjusted to
|
||||||
preceding subperiod start when using a report interval)
|
preceding subperiod start when using a report interval)
|
||||||
@ -248,53 +290,6 @@ OPTIONS
|
|||||||
|
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
|
|
||||||
hledger help options:
|
|
||||||
|
|
||||||
-h --help
|
|
||||||
show general or COMMAND help
|
|
||||||
|
|
||||||
--man show general or COMMAND user manual with man
|
|
||||||
|
|
||||||
--info show general or COMMAND user manual with info
|
|
||||||
|
|
||||||
--version
|
|
||||||
show general or ADDONCMD version
|
|
||||||
|
|
||||||
--debug[=N]
|
|
||||||
show debug output (levels 1-9, default: 1)
|
|
||||||
|
|
||||||
A @FILE argument will be expanded to the contents of FILE, which should
|
|
||||||
contain one command line option/argument per line. (To prevent this,
|
|
||||||
insert a -- argument before.)
|
|
||||||
|
|
||||||
By default the server listens on IP address 127.0.0.1, accessible only
|
|
||||||
to local requests. You can use --host to change this, eg --host
|
|
||||||
0.0.0.0 to listen on all configured addresses.
|
|
||||||
|
|
||||||
Similarly, use --port to set a TCP port other than 5000, eg if you are
|
|
||||||
running multiple hledger-web instances.
|
|
||||||
|
|
||||||
Both of these options are ignored when --socket is used. In this case,
|
|
||||||
it creates an AF_UNIX socket file at the supplied path and uses that
|
|
||||||
for communication. This is an alternative way of running multiple
|
|
||||||
hledger-web instances behind a reverse proxy that handles authentica-
|
|
||||||
tion for different users. The path can be derived in a predictable
|
|
||||||
way, eg by using the username within the path. As an example, nginx as
|
|
||||||
reverse proxy can use the variable $remote_user to derive a path from
|
|
||||||
the username used in a HTTP basic authentication. The following
|
|
||||||
proxy_pass directive allows access to all hledger-web instances that
|
|
||||||
created a socket in /tmp/hledger/:
|
|
||||||
|
|
||||||
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
|
||||||
|
|
||||||
You can use --base-url to change the protocol, hostname, port and path
|
|
||||||
that appear in hyperlinks, useful eg for integrating hledger-web within
|
|
||||||
a larger website. The default is http://HOST:PORT/ using the server's
|
|
||||||
configured host address and TCP port (or http://HOST if PORT is 80).
|
|
||||||
|
|
||||||
With --file-url you can set a different base url for static files, eg
|
|
||||||
for better caching or cookie-less serving on high performance websites.
|
|
||||||
|
|
||||||
PERMISSIONS
|
PERMISSIONS
|
||||||
By default, hledger-web allows anyone who can reach it to view the
|
By default, hledger-web allows anyone who can reach it to view the
|
||||||
journal and to add new transactions, but not to change existing data.
|
journal and to add new transactions, but not to change existing data.
|
||||||
|
|||||||
@ -130,63 +130,19 @@ Files are most often in hledger\[aq]s journal format, with the
|
|||||||
\f[V].journal\f[R] file extension (\f[V].hledger\f[R] or \f[V].j\f[R]
|
\f[V].journal\f[R] file extension (\f[V].hledger\f[R] or \f[V].j\f[R]
|
||||||
also work); these files describe transactions, like an accounting
|
also work); these files describe transactions, like an accounting
|
||||||
general journal.
|
general journal.
|
||||||
Some other supported file formats are discussed below.
|
|
||||||
.PP
|
.PP
|
||||||
When no \f[V]-f\f[R] option is given, hledger looks for the file
|
When no file is specified, hledger looks for \f[V].hledger.journal\f[R]
|
||||||
specified by the \f[V]LEDGER_FILE\f[R] environment variable; if this is
|
in your home directory.
|
||||||
not set, it uses \f[V].hledger.journal\f[R] in your home directory.
|
|
||||||
.PP
|
.PP
|
||||||
Most people prefer to keep financial files in a dedicated folder,
|
But most people prefer to keep financial files in a dedicated folder,
|
||||||
perhaps with version control.
|
perhaps with version control.
|
||||||
Also, starting a new journal file per year is common (it\[aq]s not
|
Also, starting a new journal file each year is common (it\[aq]s not
|
||||||
required, but helps keep things fast and organised).
|
required, but helps keep things fast and organised).
|
||||||
So we usually set \f[V]LEDGER_FILE\f[R], to something like
|
So we usually configure a different journal file, by setting the
|
||||||
|
\f[V]LEDGER_FILE\f[R] environment variable, to something like
|
||||||
\f[V]\[ti]/finance/2023.journal\f[R].
|
\f[V]\[ti]/finance/2023.journal\f[R].
|
||||||
.SS Setting LEDGER_FILE
|
For more about how to do that on your system, see Common tasks > Setting
|
||||||
.PP
|
LEDGER_FILE.
|
||||||
How to set \f[V]LEDGER_FILE\f[R] permanently depends on your platform:
|
|
||||||
.PP
|
|
||||||
On unix and mac, running these commands in the terminal will work for
|
|
||||||
many people; adapt as needed:
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
$ mkdir -p \[ti]/finance
|
|
||||||
$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[ga] >> \[ti]/.profile
|
|
||||||
$ source \[ti]/.profile
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
When correctly configured, in a new terminal window
|
|
||||||
\f[V]env | grep LEDGER_FILE\f[R] will show your file, and so will
|
|
||||||
\f[V]hledger files\f[R].
|
|
||||||
.PP
|
|
||||||
On mac, this additional step might be helpful for GUI applications (like
|
|
||||||
Emacs started from the dock): add an entry to
|
|
||||||
\f[V]\[ti]/.MacOSX/environment.plist\f[R] like
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
{
|
|
||||||
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq]
|
|
||||||
}
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
and then run \f[V]killall Dock\f[R] in a terminal window (or restart the
|
|
||||||
machine).
|
|
||||||
.PP
|
|
||||||
On Windows, see https://www.java.com/en/download/help/path.html, or try
|
|
||||||
running these commands in a powershell window (let us know if it
|
|
||||||
persists across a reboot, and if you need to be an Administrator):
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
> CD
|
|
||||||
> MKDIR finance
|
|
||||||
> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq]
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.SS Data formats
|
.SS Data formats
|
||||||
.PP
|
.PP
|
||||||
Usually the data file is in hledger\[aq]s journal format, but it can be
|
Usually the data file is in hledger\[aq]s journal format, but it can be
|
||||||
@ -314,33 +270,67 @@ Are all commodity conversions declared explicitly ?
|
|||||||
.PP
|
.PP
|
||||||
You can use the check command to run individual checks -- the ones
|
You can use the check command to run individual checks -- the ones
|
||||||
listed above and some more.
|
listed above and some more.
|
||||||
.SH Environment
|
.SH Commands
|
||||||
.PP
|
.PP
|
||||||
Environment variables which affect hledger:
|
hledger provides various subcommands for getting things done.
|
||||||
|
Most of these commands do not change the journal file; they just read it
|
||||||
|
and output a report.
|
||||||
|
A few commands assist with adding data and file management.
|
||||||
.PP
|
.PP
|
||||||
\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger
|
To show the commands list, run \f[V]hledger\f[R] with no arguments.
|
||||||
commands (\f[V]register\f[R]) will format their output to this width.
|
The commands are described in detail in PART 4: COMMANDS, below.
|
||||||
If not set, they will try to use the available terminal width.
|
|
||||||
.PP
|
.PP
|
||||||
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
|
To use a particular command, run
|
||||||
with \f[V]-f/--file\f[R].
|
\f[V]hledger CMD [CMDOPTS] [CMDARGS]\f[R],
|
||||||
Default: \f[V]$HOME/.hledger.journal\f[R].
|
.IP \[bu] 2
|
||||||
|
CMD is the full command name, or its standard abbreviation shown in the
|
||||||
|
commands list, or any unambiguous prefix of the name.
|
||||||
|
.IP \[bu] 2
|
||||||
|
CMDOPTS are command-specific options, if any.
|
||||||
|
Command-specific options must be written after the command name.
|
||||||
|
Eg: \f[V]hledger print -x\f[R].
|
||||||
|
.IP \[bu] 2
|
||||||
|
CMDARGS are additional arguments to the command, if any.
|
||||||
|
Most hledger commands accept arguments representing a query, to limit
|
||||||
|
the data in some way.
|
||||||
|
Eg: \f[V]hledger reg assets:checking\f[R].
|
||||||
.PP
|
.PP
|
||||||
\f[B]NO_COLOR\f[R] If this environment variable is set (with any value),
|
To list a command\[aq]s options, arguments, and documentation in the
|
||||||
hledger will not use ANSI color codes in terminal output, unless
|
terminal, run \f[V]hledger CMD -h\f[R].
|
||||||
overridden by an explicit \f[V]--color/--colour\f[R] option.
|
Eg: \f[V]hledger bal -h\f[R].
|
||||||
|
.SS Add-on commands
|
||||||
|
.PP
|
||||||
|
In addition to the built-in commands, you can install \f[I]add-on
|
||||||
|
commands\f[R]: programs or scripts named \[dq]hledger-SOMETHING\[dq],
|
||||||
|
which will also appear in hledger\[aq]s commands list.
|
||||||
|
If you used the hledger-install script, you will have several add-ons
|
||||||
|
installed already.
|
||||||
|
Some more can be found in hledger\[aq]s bin/ directory, documented at
|
||||||
|
https://hledger.org/scripts.html.
|
||||||
|
.PP
|
||||||
|
More precisely, add-on commands are programs or scripts in your
|
||||||
|
shell\[aq]s PATH, whose name starts with \[dq]hledger-\[dq] and ends
|
||||||
|
with no extension or a recognised extension (\[dq].bat\[dq],
|
||||||
|
\[dq].com\[dq], \[dq].exe\[dq], \[dq].hs\[dq], \[dq].js\[dq],
|
||||||
|
\[dq].lhs\[dq], \[dq].lua\[dq], \[dq].php\[dq], \[dq].pl\[dq],
|
||||||
|
\[dq].py\[dq], \[dq].rb\[dq], \[dq].rkt\[dq], or \[dq].sh\[dq]), and (on
|
||||||
|
unix and mac) which has executable permission for the current user.
|
||||||
|
.PP
|
||||||
|
You can run add-on commands using hledger, much like built-in commands:
|
||||||
|
\f[V]hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]\f[R].
|
||||||
|
But note the double hyphen argument, required before add-on-specific
|
||||||
|
options.
|
||||||
|
Eg: \f[V]hledger ui -- --watch\f[R] or \f[V]hledger web -- --serve\f[R].
|
||||||
|
If this causes difficulty, you can always run the add-on directly,
|
||||||
|
without using \f[V]hledger\f[R]: \f[V]hledger-ui --watch\f[R] or
|
||||||
|
\f[V]hledger-web --serve\f[R].
|
||||||
.SH Options
|
.SH Options
|
||||||
.PP
|
.PP
|
||||||
Here is a list of flags and options common to most hledger commands, and
|
Run \f[V]hledger -h\f[R] to see general command line help, and general
|
||||||
some useful details about hledger command line parsing.
|
options which are common to most hledger commands.
|
||||||
But if you are new to hledger, feel free to skim/skip ahead to the
|
These options can be written anywhere on the command line.
|
||||||
Commands.
|
They can be grouped into help, input, and reporting options:
|
||||||
.SS General options
|
.SS General help options
|
||||||
.PP
|
|
||||||
To see general usage help, including general options which are supported
|
|
||||||
by most hledger commands, run \f[V]hledger -h\f[R].
|
|
||||||
.PP
|
|
||||||
General help options:
|
|
||||||
.TP
|
.TP
|
||||||
\f[V]-h --help\f[R]
|
\f[V]-h --help\f[R]
|
||||||
show general or COMMAND help
|
show general or COMMAND help
|
||||||
@ -356,8 +346,7 @@ show general or ADDONCMD version
|
|||||||
.TP
|
.TP
|
||||||
\f[V]--debug[=N]\f[R]
|
\f[V]--debug[=N]\f[R]
|
||||||
show debug output (levels 1-9, default: 1)
|
show debug output (levels 1-9, default: 1)
|
||||||
.PP
|
.SS General input options
|
||||||
General input options:
|
|
||||||
.TP
|
.TP
|
||||||
\f[V]-f FILE --file=FILE\f[R]
|
\f[V]-f FILE --file=FILE\f[R]
|
||||||
use a different input file.
|
use a different input file.
|
||||||
@ -385,8 +374,7 @@ assignments)
|
|||||||
.TP
|
.TP
|
||||||
\f[V]-s --strict\f[R]
|
\f[V]-s --strict\f[R]
|
||||||
do extra error checking (check that all posted accounts are declared)
|
do extra error checking (check that all posted accounts are declared)
|
||||||
.PP
|
.SS General reporting options
|
||||||
General reporting options:
|
|
||||||
.TP
|
.TP
|
||||||
\f[V]-b --begin=DATE\f[R]
|
\f[V]-b --begin=DATE\f[R]
|
||||||
include postings/txns on or after this date (will be adjusted to
|
include postings/txns on or after this date (will be adjusted to
|
||||||
@ -502,6 +490,11 @@ When a reporting option appears more than once in the command line, the
|
|||||||
last one takes precedence.
|
last one takes precedence.
|
||||||
.PP
|
.PP
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
|
.SH Command line tips
|
||||||
|
.PP
|
||||||
|
Here are some details useful to know about for hledger command lines
|
||||||
|
(and elsewhere).
|
||||||
|
Feel free to skip this section until you need it.
|
||||||
.SS Option repetition
|
.SS Option repetition
|
||||||
.PP
|
.PP
|
||||||
If options are repeated in a command line, hledger will generally use
|
If options are repeated in a command line, hledger will generally use
|
||||||
@ -511,74 +504,6 @@ Some of the boolean flags will toggle if repeated; these include:
|
|||||||
\f[V]-%/--percent\f[R], \f[V]-E/--empty\f[R], \f[V]-N/--no-total\f[R],
|
\f[V]-%/--percent\f[R], \f[V]-E/--empty\f[R], \f[V]-N/--no-total\f[R],
|
||||||
\f[V]-T/--row-total\f[R], \f[V]-A/--average\f[R], and
|
\f[V]-T/--row-total\f[R], \f[V]-A/--average\f[R], and
|
||||||
\f[V]-S/--sort-amount\f[R].
|
\f[V]-S/--sort-amount\f[R].
|
||||||
.SS Command options
|
|
||||||
.PP
|
|
||||||
To see options for a particular command, including command-specific
|
|
||||||
options, run: \f[V]hledger COMMAND -h\f[R].
|
|
||||||
.PP
|
|
||||||
Command-specific options must be written after the command name, eg:
|
|
||||||
\f[V]hledger print -x\f[R].
|
|
||||||
.PP
|
|
||||||
Additionally, if the command is an add-on, you may need to put its
|
|
||||||
options after a double-hyphen, eg: \f[V]hledger ui -- --watch\f[R].
|
|
||||||
Or, you can run the add-on executable directly:
|
|
||||||
\f[V]hledger-ui --watch\f[R].
|
|
||||||
.SS Command arguments
|
|
||||||
.PP
|
|
||||||
Most hledger commands accept arguments after the command name, which are
|
|
||||||
often a query, filtering the data in some way.
|
|
||||||
.PP
|
|
||||||
You can save a set of command line options/arguments in a file, and then
|
|
||||||
reuse them by writing \f[V]\[at]FILENAME\f[R] as a command line
|
|
||||||
argument.
|
|
||||||
Eg: \f[V]hledger bal \[at]foo.args\f[R].
|
|
||||||
(To prevent this, eg if you have an argument that begins with a literal
|
|
||||||
\f[V]\[at]\f[R], precede it with \f[V]--\f[R], eg:
|
|
||||||
\f[V]hledger bal -- \[at]ARG\f[R]).
|
|
||||||
.PP
|
|
||||||
Inside the argument file, each line should contain just one option or
|
|
||||||
argument.
|
|
||||||
Avoid the use of spaces, except inside quotes (or you\[aq]ll see a
|
|
||||||
confusing error).
|
|
||||||
Between a flag and its argument, use = (or nothing).
|
|
||||||
Bad:
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
assets depth:2
|
|
||||||
-X USD
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
Good:
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
assets
|
|
||||||
depth:2
|
|
||||||
-X=USD
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
For special characters (see below), use one less level of quoting than
|
|
||||||
you would at the command prompt.
|
|
||||||
Bad:
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
-X\[dq]$\[dq]
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
Good:
|
|
||||||
.IP
|
|
||||||
.nf
|
|
||||||
\f[C]
|
|
||||||
-X$
|
|
||||||
\f[R]
|
|
||||||
.fi
|
|
||||||
.PP
|
|
||||||
See also: Save frequently used options.
|
|
||||||
.SS Special characters
|
.SS Special characters
|
||||||
.SS Single escaping (shell metacharacters)
|
.SS Single escaping (shell metacharacters)
|
||||||
.PP
|
.PP
|
||||||
@ -794,70 +719,54 @@ Eg to search for amounts with the dollar sign in hledger-web, write
|
|||||||
On the command line, some metacharacters like \f[V]$\f[R] have a special
|
On the command line, some metacharacters like \f[V]$\f[R] have a special
|
||||||
meaning to the shell and so must be escaped at least once more.
|
meaning to the shell and so must be escaped at least once more.
|
||||||
See Special characters.
|
See Special characters.
|
||||||
.SH Commands
|
.SS Argument files
|
||||||
.PP
|
.PP
|
||||||
hledger provides a number of built-in subcommands (described below).
|
You can save a set of command line options and arguments in a file, and
|
||||||
Most of these read your data without changing it, and display a report.
|
then reuse them by writing \f[V]\[at]FILENAME\f[R] as a command line
|
||||||
A few assist with data entry and management.
|
argument.
|
||||||
|
Eg: \f[V]hledger bal \[at]foo.args\f[R].
|
||||||
.PP
|
.PP
|
||||||
Run \f[V]hledger\f[R] with no arguments to list the commands available,
|
Inside the argument file, each line should contain just one option or
|
||||||
and \f[V]hledger CMD\f[R] to run a command.
|
argument.
|
||||||
CMD can be the full command name, or its standard abbreviation shown in
|
Also, don\[aq]t use spaces except inside quotes (or you\[aq]ll see a
|
||||||
the commands list, or any unambiguous prefix of the name.
|
confusing error).
|
||||||
Eg: \f[V]hledger bal\f[R].
|
Ie, write = (or nothing) between a flag and its argument.
|
||||||
.SS Add-on commands
|
Eg, bad:
|
||||||
.PP
|
|
||||||
Add-on commands are extra subcommands provided by programs or scripts in
|
|
||||||
your PATH
|
|
||||||
.IP \[bu] 2
|
|
||||||
whose name starts with \f[V]hledger-\f[R]
|
|
||||||
.IP \[bu] 2
|
|
||||||
whose name ends with a recognised file extension:
|
|
||||||
\f[V].bat\f[R],\f[V].com\f[R],\f[V].exe\f[R],
|
|
||||||
\f[V].hs\f[R],\f[V].lhs\f[R],\f[V].pl\f[R],\f[V].py\f[R],\f[V].rb\f[R],\f[V].rkt\f[R],\f[V].sh\f[R]
|
|
||||||
or none
|
|
||||||
.IP \[bu] 2
|
|
||||||
and (on unix, mac) which are executable by the current user.
|
|
||||||
.PP
|
|
||||||
Addons can be written in any language, but haskell scripts or programs
|
|
||||||
have a big advantage: they can use hledger\[aq]s library code, for
|
|
||||||
command-line options, parsing and reporting.
|
|
||||||
.PP
|
|
||||||
Several add-on commands are installed by the hledger-install script.
|
|
||||||
See https://hledger.org/scripts.html for more details.
|
|
||||||
.PP
|
|
||||||
Note in a hledger command line, add-on command flags must have a double
|
|
||||||
dash (\f[V]--\f[R]) preceding them.
|
|
||||||
Eg you must write:
|
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger web -- --serve
|
assets -X USD
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
and not:
|
Good:
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger web --serve
|
assets
|
||||||
|
-X=USD
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
(because the \f[V]--serve\f[R] flag belongs to \f[V]hledger-web\f[R],
|
For the special characters mentioned above, use one less level of
|
||||||
not \f[V]hledger\f[R]).
|
quoting than you would at the command prompt.
|
||||||
.PP
|
Eg, bad:
|
||||||
The \f[V]-h/--help\f[R] and \f[V]--version\f[R] flags don\[aq]t require
|
|
||||||
\f[V]--\f[R].
|
|
||||||
.PP
|
|
||||||
If you have any trouble with this, remember you can always run the
|
|
||||||
add-on program directly, eg:
|
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger-web --serve
|
-X\[dq]$\[dq]
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
|
.PP
|
||||||
|
Good:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
-X$
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
See also: Save frequently used options.
|
||||||
.SH Output
|
.SH Output
|
||||||
.SS Output destination
|
.SS Output destination
|
||||||
.PP
|
.PP
|
||||||
@ -1182,6 +1091,21 @@ stderr, eg:
|
|||||||
hledger bal --debug=3 2>hledger.log
|
hledger bal --debug=3 2>hledger.log
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
|
.SH Environment
|
||||||
|
.PP
|
||||||
|
These environment variables affect hledger:
|
||||||
|
.PP
|
||||||
|
\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger
|
||||||
|
commands (\f[V]register\f[R]) will format their output to this width.
|
||||||
|
If not set, they will try to use the available terminal width.
|
||||||
|
.PP
|
||||||
|
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
|
||||||
|
with \f[V]-f/--file\f[R].
|
||||||
|
Default: \f[V]$HOME/.hledger.journal\f[R].
|
||||||
|
.PP
|
||||||
|
\f[B]NO_COLOR\f[R] If this environment variable is set (with any value),
|
||||||
|
hledger will not use ANSI color codes in terminal output, unless
|
||||||
|
overridden by an explicit \f[V]--color/--colour\f[R] option.
|
||||||
.SH PART 2: DATA FORMATS
|
.SH PART 2: DATA FORMATS
|
||||||
.PP
|
.PP
|
||||||
.SH Journal
|
.SH Journal
|
||||||
@ -2965,7 +2889,7 @@ Including the aliases doesn\[aq]t work either:
|
|||||||
\f[C]
|
\f[C]
|
||||||
include a.aliases
|
include a.aliases
|
||||||
|
|
||||||
2020-01-01 ; not affected by a.aliases
|
2023-01-01 ; not affected by a.aliases
|
||||||
foo 1
|
foo 1
|
||||||
bar
|
bar
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -2979,7 +2903,7 @@ of your top-most file, like this:
|
|||||||
alias foo=Foo
|
alias foo=Foo
|
||||||
alias bar=Bar
|
alias bar=Bar
|
||||||
|
|
||||||
2020-01-01 ; affected by aliases above
|
2023-01-01 ; affected by aliases above
|
||||||
foo 1
|
foo 1
|
||||||
bar
|
bar
|
||||||
|
|
||||||
@ -3214,7 +3138,7 @@ including directories, but this can be done, eg:
|
|||||||
.PP
|
.PP
|
||||||
The path may also be prefixed to force a specific file format,
|
The path may also be prefixed to force a specific file format,
|
||||||
overriding the file extension (as described in hledger.1 -> Input
|
overriding the file extension (as described in hledger.1 -> Input
|
||||||
files): \f[V]include timedot:\[ti]/notes/2020*.md\f[R].
|
files): \f[V]include timedot:\[ti]/notes/2023*.md\f[R].
|
||||||
.SS \f[V]P\f[R] directive
|
.SS \f[V]P\f[R] directive
|
||||||
.PP
|
.PP
|
||||||
The \f[V]P\f[R] directive declares a market price, which is a conversion
|
The \f[V]P\f[R] directive declares a market price, which is a conversion
|
||||||
@ -3326,8 +3250,8 @@ cover a whole number of that interval.
|
|||||||
(This is done to improve reports, but it also affects periodic
|
(This is done to improve reports, but it also affects periodic
|
||||||
transactions.
|
transactions.
|
||||||
Yes, it\[aq]s a bit inconsistent with the above.)
|
Yes, it\[aq]s a bit inconsistent with the above.)
|
||||||
Eg: \f[V]\[ti] every 10th day of month from 2020/01\f[R], which is
|
Eg: \f[V]\[ti] every 10th day of month from 2023/01\f[R], which is
|
||||||
equivalent to \f[V]\[ti] every 10th day of month from 2020/01/01\f[R],
|
equivalent to \f[V]\[ti] every 10th day of month from 2023/01/01\f[R],
|
||||||
will be adjusted to start on 2019/12/10.
|
will be adjusted to start on 2019/12/10.
|
||||||
.SS Periodic rule syntax
|
.SS Periodic rule syntax
|
||||||
.PP
|
.PP
|
||||||
@ -3381,10 +3305,10 @@ example:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2020\[dq]
|
; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2023\[dq]
|
||||||
; ||
|
; ||
|
||||||
; vv
|
; vv
|
||||||
\[ti] every 2 months in 2020, we will review
|
\[ti] every 2 months in 2023, we will review
|
||||||
assets:bank:checking $1500
|
assets:bank:checking $1500
|
||||||
income:acme inc
|
income:acme inc
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -4679,7 +4603,7 @@ So for example, when reading an SSV file, if the original record was:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000
|
2023-01-01; \[dq]Acme, Inc.\[dq]; 1,000
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
@ -4687,7 +4611,7 @@ the regex would see, and try to match, this modified record text:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01,Acme, Inc., 1,000
|
2023-01-01,Acme, Inc., 1,000
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
@ -4757,7 +4681,7 @@ Example:
|
|||||||
if,account2,comment
|
if,account2,comment
|
||||||
atm transaction fee,expenses:business:banking,deductible? check it
|
atm transaction fee,expenses:business:banking,deductible? check it
|
||||||
%description groceries,expenses:groceries,
|
%description groceries,expenses:groceries,
|
||||||
2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
|
2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.SS \f[V]balance-type\f[R]
|
.SS \f[V]balance-type\f[R]
|
||||||
@ -5129,7 +5053,7 @@ field(s):
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01,foo,$123.00
|
2023-01-01,foo,$123.00
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
@ -5145,7 +5069,7 @@ fields date,description,amount
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01 foo
|
2023-01-01 foo
|
||||||
expenses:unknown $123.00
|
expenses:unknown $123.00
|
||||||
income:unknown $-123.00
|
income:unknown $-123.00
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -5155,7 +5079,7 @@ If the currency is provided as a separate CSV field:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01,foo,USD,123.00
|
2023-01-01,foo,USD,123.00
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
@ -5171,7 +5095,7 @@ fields date,description,currency,amount
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01 foo
|
2023-01-01 foo
|
||||||
expenses:unknown USD123.00
|
expenses:unknown USD123.00
|
||||||
income:unknown USD-123.00
|
income:unknown USD-123.00
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -5190,7 +5114,7 @@ amount %amt %cur
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01 foo
|
2023-01-01 foo
|
||||||
expenses:unknown 123.00 USD
|
expenses:unknown 123.00 USD
|
||||||
income:unknown -123.00 USD
|
income:unknown -123.00 USD
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -5835,7 +5759,7 @@ biz:research 1
|
|||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
* Time log
|
* Time log
|
||||||
** 2020-01-01
|
** 2023-01-01
|
||||||
*** adm:time .
|
*** adm:time .
|
||||||
*** adm:finance .
|
*** adm:finance .
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -5843,9 +5767,9 @@ biz:research 1
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
* 2020 Work Diary
|
* 2023 Work Diary
|
||||||
** Q1
|
** Q1
|
||||||
*** 2020-02-29
|
*** 2023-02-29
|
||||||
**** DONE
|
**** DONE
|
||||||
0700 yoga
|
0700 yoga
|
||||||
**** UNPLANNED
|
**** UNPLANNED
|
||||||
@ -6474,7 +6398,7 @@ Regular expressions are also supported:
|
|||||||
Add a query type prefix to match other parts of the data:
|
Add a query type prefix to match other parts of the data:
|
||||||
.RS 2
|
.RS 2
|
||||||
.PP
|
.PP
|
||||||
\f[V]date:202012- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R]
|
\f[V]date:202312- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R]
|
||||||
.RE
|
.RE
|
||||||
.IP \[bu] 2
|
.IP \[bu] 2
|
||||||
Add a \f[V]not:\f[R] prefix to negate a term:
|
Add a \f[V]not:\f[R] prefix to negate a term:
|
||||||
@ -6683,7 +6607,7 @@ above)
|
|||||||
.PP
|
.PP
|
||||||
Some queries can also be expressed as command-line options:
|
Some queries can also be expressed as command-line options:
|
||||||
\f[V]depth:2\f[R] is equivalent to \f[V]--depth 2\f[R],
|
\f[V]depth:2\f[R] is equivalent to \f[V]--depth 2\f[R],
|
||||||
\f[V]date:2020\f[R] is equivalent to \f[V]-p 2020\f[R], etc.
|
\f[V]date:2023\f[R] is equivalent to \f[V]-p 2023\f[R], etc.
|
||||||
When you mix command options and query arguments, generally the
|
When you mix command options and query arguments, generally the
|
||||||
resulting query is their intersection.
|
resulting query is their intersection.
|
||||||
.SS Queries and valuation
|
.SS Queries and valuation
|
||||||
@ -11608,7 +11532,7 @@ Or, specify an existing journal file with -f or LEDGER_FILE.
|
|||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
You can override this by setting the \f[V]LEDGER_FILE\f[R] environment
|
You can override this by setting the \f[V]LEDGER_FILE\f[R] environment
|
||||||
variable.
|
variable (see below).
|
||||||
It\[aq]s a good practice to keep this important file under version
|
It\[aq]s a good practice to keep this important file under version
|
||||||
control, and to start a new file each year.
|
control, and to start a new file each year.
|
||||||
So you could do something like this:
|
So you could do something like this:
|
||||||
@ -11619,11 +11543,11 @@ $ mkdir \[ti]/finance
|
|||||||
$ cd \[ti]/finance
|
$ cd \[ti]/finance
|
||||||
$ git init
|
$ git init
|
||||||
Initialized empty Git repository in /Users/simon/finance/.git/
|
Initialized empty Git repository in /Users/simon/finance/.git/
|
||||||
$ touch 2020.journal
|
$ touch 2023.journal
|
||||||
$ echo \[dq]export LEDGER_FILE=$HOME/finance/2020.journal\[dq] >> \[ti]/.bashrc
|
$ echo \[dq]export LEDGER_FILE=$HOME/finance/2023.journal\[dq] >> \[ti]/.profile
|
||||||
$ source \[ti]/.bashrc
|
$ source \[ti]/.profile
|
||||||
$ hledger stats
|
$ hledger stats
|
||||||
Main file : /Users/simon/finance/2020.journal
|
Main file : /Users/simon/finance/2023.journal
|
||||||
Included files :
|
Included files :
|
||||||
Transactions span : to (0 days)
|
Transactions span : to (0 days)
|
||||||
Last transaction : none
|
Last transaction : none
|
||||||
@ -11636,6 +11560,50 @@ Commodities : 0 ()
|
|||||||
Market prices : 0 ()
|
Market prices : 0 ()
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
|
.SS Setting LEDGER_FILE
|
||||||
|
.PP
|
||||||
|
How to set \f[V]LEDGER_FILE\f[R] permanently depends on your setup:
|
||||||
|
.PP
|
||||||
|
On unix and mac, running these commands in the terminal will work for
|
||||||
|
many people; adapt as needed:
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[ga] >> \[ti]/.profile
|
||||||
|
$ source \[ti]/.profile
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
When correctly configured, in a new terminal window
|
||||||
|
\f[V]env | grep LEDGER_FILE\f[R] will show your file, and so will
|
||||||
|
\f[V]hledger files\f[R].
|
||||||
|
.PP
|
||||||
|
On mac, this additional step might be helpful for GUI applications (like
|
||||||
|
Emacs started from the dock): add an entry to
|
||||||
|
\f[V]\[ti]/.MacOSX/environment.plist\f[R] like
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
{
|
||||||
|
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq]
|
||||||
|
}
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
|
.PP
|
||||||
|
and then run \f[V]killall Dock\f[R] in a terminal window (or restart the
|
||||||
|
machine).
|
||||||
|
.PP
|
||||||
|
On Windows, see https://www.java.com/en/download/help/path.html, or try
|
||||||
|
running these commands in a powershell window (let us know if it
|
||||||
|
persists across a reboot, and if you need to be an Administrator):
|
||||||
|
.IP
|
||||||
|
.nf
|
||||||
|
\f[C]
|
||||||
|
> CD
|
||||||
|
> MKDIR finance
|
||||||
|
> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq]
|
||||||
|
\f[R]
|
||||||
|
.fi
|
||||||
.SS Setting opening balances
|
.SS Setting opening balances
|
||||||
.PP
|
.PP
|
||||||
Pick a starting date for which you can look up the balances of some
|
Pick a starting date for which you can look up the balances of some
|
||||||
@ -11658,7 +11626,7 @@ like this:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-01 * opening balances
|
2023-01-01 * opening balances
|
||||||
assets:bank:checking $1000 = $1000
|
assets:bank:checking $1000 = $1000
|
||||||
assets:bank:savings $2000 = $2000
|
assets:bank:savings $2000 = $2000
|
||||||
assets:cash $100 = $100
|
assets:cash $100 = $100
|
||||||
@ -11687,7 +11655,7 @@ record a similar transaction:
|
|||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger add
|
$ hledger add
|
||||||
Adding transactions to journal file /Users/simon/finance/2020.journal
|
Adding transactions to journal file /Users/simon/finance/2023.journal
|
||||||
Any command line arguments will be used as defaults.
|
Any command line arguments will be used as defaults.
|
||||||
Use tab key to complete, readline keys to edit, enter to accept defaults.
|
Use tab key to complete, readline keys to edit, enter to accept defaults.
|
||||||
An optional (CODE) may follow transaction dates.
|
An optional (CODE) may follow transaction dates.
|
||||||
@ -11695,7 +11663,7 @@ An optional ; COMMENT may follow descriptions or amounts.
|
|||||||
If you make a mistake, enter < at any prompt to go one step backward.
|
If you make a mistake, enter < at any prompt to go one step backward.
|
||||||
To end a transaction, enter . when prompted.
|
To end a transaction, enter . when prompted.
|
||||||
To quit, enter . at a date prompt or press control-d or control-c.
|
To quit, enter . at a date prompt or press control-d or control-c.
|
||||||
Date [2020-02-07]: 2020-01-01
|
Date [2023-02-07]: 2023-01-01
|
||||||
Description: * opening balances
|
Description: * opening balances
|
||||||
Account 1: assets:bank:checking
|
Account 1: assets:bank:checking
|
||||||
Amount 1: $1000
|
Amount 1: $1000
|
||||||
@ -11708,7 +11676,7 @@ Amount 4 [$-3100]: $-50
|
|||||||
Account 5: equity:opening/closing balances
|
Account 5: equity:opening/closing balances
|
||||||
Amount 5 [$-3050]:
|
Amount 5 [$-3050]:
|
||||||
Account 6 (or . or enter to finish this transaction): .
|
Account 6 (or . or enter to finish this transaction): .
|
||||||
2020-01-01 * opening balances
|
2023-01-01 * opening balances
|
||||||
assets:bank:checking $1000
|
assets:bank:checking $1000
|
||||||
assets:bank:savings $2000
|
assets:bank:savings $2000
|
||||||
assets:cash $100
|
assets:cash $100
|
||||||
@ -11718,7 +11686,7 @@ Account 6 (or . or enter to finish this transaction): .
|
|||||||
Save this transaction to the journal ? [y]:
|
Save this transaction to the journal ? [y]:
|
||||||
Saved.
|
Saved.
|
||||||
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
|
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
|
||||||
Date [2020-01-01]: .
|
Date [2023-01-01]: .
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.RE
|
.RE
|
||||||
@ -11729,7 +11697,7 @@ Eg:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ git commit -m \[aq]initial balances\[aq] 2020.journal
|
$ git commit -m \[aq]initial balances\[aq] 2023.journal
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.SS Recording transactions
|
.SS Recording transactions
|
||||||
@ -11744,15 +11712,15 @@ hledger.org for more ideas:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020/1/10 * gift received
|
2023/1/10 * gift received
|
||||||
assets:cash $20
|
assets:cash $20
|
||||||
income:gifts
|
income:gifts
|
||||||
|
|
||||||
2020.1.12 * farmers market
|
2023.1.12 * farmers market
|
||||||
expenses:food $13
|
expenses:food $13
|
||||||
assets:cash
|
assets:cash
|
||||||
|
|
||||||
2020-01-15 paycheck
|
2023-01-15 paycheck
|
||||||
income:salary
|
income:salary
|
||||||
assets:bank:checking $1000
|
assets:bank:checking $1000
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -11784,7 +11752,7 @@ $2, it could be:
|
|||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
2020-01-16 * adjust cash
|
2023-01-16 * adjust cash
|
||||||
assets:cash $-2 = $105
|
assets:cash $-2 = $105
|
||||||
expenses:misc
|
expenses:misc
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -11813,14 +11781,14 @@ After reconciling, it could be a good time to mark the reconciled
|
|||||||
transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want
|
transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want
|
||||||
to track that, by adding the \f[V]*\f[R] marker.
|
to track that, by adding the \f[V]*\f[R] marker.
|
||||||
Eg in the paycheck transaction above, insert \f[V]*\f[R] between
|
Eg in the paycheck transaction above, insert \f[V]*\f[R] between
|
||||||
\f[V]2020-01-15\f[R] and \f[V]paycheck\f[R]
|
\f[V]2023-01-15\f[R] and \f[V]paycheck\f[R]
|
||||||
.PP
|
.PP
|
||||||
If you\[aq]re using version control, this can be another good time to
|
If you\[aq]re using version control, this can be another good time to
|
||||||
commit:
|
commit:
|
||||||
.IP
|
.IP
|
||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ git commit -m \[aq]txns\[aq] 2020.journal
|
$ git commit -m \[aq]txns\[aq] 2023.journal
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.SS Reporting
|
.SS Reporting
|
||||||
@ -11832,26 +11800,26 @@ Show all transactions:
|
|||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger print
|
$ hledger print
|
||||||
2020-01-01 * opening balances
|
2023-01-01 * opening balances
|
||||||
assets:bank:checking $1000
|
assets:bank:checking $1000
|
||||||
assets:bank:savings $2000
|
assets:bank:savings $2000
|
||||||
assets:cash $100
|
assets:cash $100
|
||||||
liabilities:creditcard $-50
|
liabilities:creditcard $-50
|
||||||
equity:opening/closing balances $-3050
|
equity:opening/closing balances $-3050
|
||||||
|
|
||||||
2020-01-10 * gift received
|
2023-01-10 * gift received
|
||||||
assets:cash $20
|
assets:cash $20
|
||||||
income:gifts
|
income:gifts
|
||||||
|
|
||||||
2020-01-12 * farmers market
|
2023-01-12 * farmers market
|
||||||
expenses:food $13
|
expenses:food $13
|
||||||
assets:cash
|
assets:cash
|
||||||
|
|
||||||
2020-01-15 * paycheck
|
2023-01-15 * paycheck
|
||||||
income:salary
|
income:salary
|
||||||
assets:bank:checking $1000
|
assets:bank:checking $1000
|
||||||
|
|
||||||
2020-01-16 * adjust cash
|
2023-01-16 * adjust cash
|
||||||
assets:cash $-2 = $105
|
assets:cash $-2 = $105
|
||||||
expenses:misc
|
expenses:misc
|
||||||
\f[R]
|
\f[R]
|
||||||
@ -11923,9 +11891,9 @@ balance sheet:
|
|||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger bs -2
|
$ hledger bs -2
|
||||||
Balance Sheet 2020-01-16
|
Balance Sheet 2023-01-16
|
||||||
|
|
||||||
|| 2020-01-16
|
|| 2023-01-16
|
||||||
========================++============
|
========================++============
|
||||||
Assets ||
|
Assets ||
|
||||||
------------------------++------------
|
------------------------++------------
|
||||||
@ -11952,9 +11920,9 @@ Show income and expense totals, formatted as an income statement:
|
|||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
hledger is
|
hledger is
|
||||||
Income Statement 2020-01-01-2020-01-16
|
Income Statement 2023-01-01-2023-01-16
|
||||||
|
|
||||||
|| 2020-01-01-2020-01-16
|
|| 2023-01-01-2023-01-16
|
||||||
===============++=======================
|
===============++=======================
|
||||||
Revenues ||
|
Revenues ||
|
||||||
---------------++-----------------------
|
---------------++-----------------------
|
||||||
@ -11981,10 +11949,10 @@ Show transactions affecting your wallet, with running total:
|
|||||||
.nf
|
.nf
|
||||||
\f[C]
|
\f[C]
|
||||||
$ hledger register cash
|
$ hledger register cash
|
||||||
2020-01-01 opening balances assets:cash $100 $100
|
2023-01-01 opening balances assets:cash $100 $100
|
||||||
2020-01-10 gift received assets:cash $20 $120
|
2023-01-10 gift received assets:cash $20 $120
|
||||||
2020-01-12 farmers market assets:cash $-13 $107
|
2023-01-12 farmers market assets:cash $-13 $107
|
||||||
2020-01-16 adjust cash assets:cash $-2 $105
|
2023-01-16 adjust cash assets:cash $-2 $105
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.PP
|
.PP
|
||||||
@ -11994,8 +11962,8 @@ Show weekly posting counts as a bar chart:
|
|||||||
\f[C]
|
\f[C]
|
||||||
$ hledger activity -W
|
$ hledger activity -W
|
||||||
2019-12-30 *****
|
2019-12-30 *****
|
||||||
2020-01-06 ****
|
2023-01-06 ****
|
||||||
2020-01-13 ****
|
2023-01-13 ****
|
||||||
\f[R]
|
\f[R]
|
||||||
.fi
|
.fi
|
||||||
.SS Migrating to a new file
|
.SS Migrating to a new file
|
||||||
|
|||||||
2452
hledger/hledger.info
2452
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user