;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
|
|
||||||
options as shown above.
|
|
||||||
|
|
||||||
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
@ -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,8 +60,7 @@ 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
|
||||||
@ -103,8 +102,52 @@ OPTIONS
|
|||||||
--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
@ -82,50 +82,18 @@ Input
|
|||||||
|
|
||||||
Files are most often in hledger's journal format, with the .journal
|
Files are most often in hledger's journal format, with the .journal
|
||||||
file extension (.hledger or .j also work); these files describe trans-
|
file extension (.hledger or .j also work); these files describe trans-
|
||||||
actions, like an accounting general journal. Some other supported file
|
actions, like an accounting general journal.
|
||||||
formats are discussed below.
|
|
||||||
|
|
||||||
When no -f option is given, hledger looks for the file specified by the
|
When no file is specified, hledger looks for .hledger.journal in your
|
||||||
LEDGER_FILE environment variable; if this is not set, it uses
|
home directory.
|
||||||
.hledger.journal in your home directory.
|
|
||||||
|
|
||||||
Most people prefer to keep financial files in a dedicated folder, per-
|
But most people prefer to keep financial files in a dedicated folder,
|
||||||
haps with version control. Also, starting a new journal file per year
|
perhaps with version control. Also, starting a new journal file each
|
||||||
is common (it's not required, but helps keep things fast and organ-
|
year is common (it's not required, but helps keep things fast and or-
|
||||||
ised). So we usually set LEDGER_FILE, to something like ~/fi-
|
ganised). So we usually configure a different journal file, by setting
|
||||||
nance/2023.journal.
|
the LEDGER_FILE environment variable, to something like ~/fi-
|
||||||
|
nance/2023.journal. For more about how to do that on your system, see
|
||||||
Setting LEDGER_FILE
|
Common tasks > Setting LEDGER_FILE.
|
||||||
How to set LEDGER_FILE permanently depends on your platform:
|
|
||||||
|
|
||||||
On unix and mac, running these commands in the terminal will work for
|
|
||||||
many people; adapt as needed:
|
|
||||||
|
|
||||||
$ mkdir -p ~/finance
|
|
||||||
$ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile
|
|
||||||
$ source ~/.profile
|
|
||||||
|
|
||||||
When correctly configured, in a new terminal window env | grep
|
|
||||||
LEDGER_FILE will show your file, and so will hledger files.
|
|
||||||
|
|
||||||
On mac, this additional step might be helpful for GUI applications
|
|
||||||
(like Emacs started from the dock): add an entry to ~/.MacOSX/environ-
|
|
||||||
ment.plist like
|
|
||||||
|
|
||||||
{
|
|
||||||
"LEDGER_FILE" : "~/finance/2023.journal"
|
|
||||||
}
|
|
||||||
|
|
||||||
and then run killall Dock in a terminal window (or restart the ma-
|
|
||||||
chine).
|
|
||||||
|
|
||||||
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 per-
|
|
||||||
sists across a reboot, and if you need to be an Administrator):
|
|
||||||
|
|
||||||
> CD
|
|
||||||
> MKDIR finance
|
|
||||||
> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
|
|
||||||
|
|
||||||
Data formats
|
Data formats
|
||||||
Usually the data file is in hledger's journal format, but it can be in
|
Usually the data file is in hledger's journal format, but it can be in
|
||||||
@ -206,31 +174,58 @@ Input
|
|||||||
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.
|
||||||
|
|
||||||
Environment
|
Commands
|
||||||
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 man-
|
||||||
|
agement.
|
||||||
|
|
||||||
COLUMNS This is normally set by your terminal; some hledger commands
|
To show the commands list, run hledger with no arguments. The commands
|
||||||
(register) will format their output to this width. If not set, they
|
are described in detail in PART 4: COMMANDS, below.
|
||||||
will try to use the available terminal width.
|
|
||||||
|
|
||||||
LEDGER_FILE The main journal file to use when not specified with
|
To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
|
||||||
-f/--file. Default: $HOME/.hledger.journal.
|
|
||||||
|
|
||||||
NO_COLOR If this environment variable is set (with any value), hledger
|
o CMD is the full command name, or its standard abbreviation shown in
|
||||||
will not use ANSI color codes in terminal output, unless overridden by
|
the commands list, or any unambiguous prefix of the name.
|
||||||
an explicit --color/--colour option.
|
|
||||||
|
o CMDOPTS are command-specific options, if any. Command-specific op-
|
||||||
|
tions must be written after the command name. Eg: hledger print -x.
|
||||||
|
|
||||||
|
o 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: hledger reg assets:checking.
|
||||||
|
|
||||||
|
To list a command's options, arguments, and documentation in the termi-
|
||||||
|
nal, run hledger CMD -h. Eg: hledger bal -h.
|
||||||
|
|
||||||
|
Add-on commands
|
||||||
|
In addition to the built-in commands, you can install add-on commands:
|
||||||
|
programs or scripts named "hledger-SOMETHING", which will also appear
|
||||||
|
in hledger'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's bin/ directory, documented at
|
||||||
|
https://hledger.org/scripts.html.
|
||||||
|
|
||||||
|
More precisely, add-on commands are programs or scripts in your shell's
|
||||||
|
PATH, whose name starts with "hledger-" and ends with no extension or a
|
||||||
|
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
|
||||||
|
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
|
||||||
|
and mac) which has executable permission for the current user.
|
||||||
|
|
||||||
|
You can run add-on commands using hledger, much like built-in commands:
|
||||||
|
hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
|
||||||
|
hyphen argument, required before add-on-specific options. Eg: hledger
|
||||||
|
ui -- --watch or hledger web -- --serve. If this causes difficulty,
|
||||||
|
you can always run the add-on directly, without using hledger: hledger-
|
||||||
|
ui --watch or hledger-web --serve.
|
||||||
|
|
||||||
Options
|
Options
|
||||||
Here is a list of flags and options common to most hledger commands,
|
Run hledger -h to see general command line help, and general options
|
||||||
and some useful details about hledger command line parsing. But if you
|
which are common to most hledger commands. These options can be writ-
|
||||||
are new to hledger, feel free to skim/skip ahead to the Commands.
|
ten anywhere on the command line. They can be grouped into help, in-
|
||||||
|
put, and reporting options:
|
||||||
General options
|
|
||||||
To see general usage help, including general options which are sup-
|
|
||||||
ported by most hledger commands, run hledger -h.
|
|
||||||
|
|
||||||
General help options:
|
|
||||||
|
|
||||||
|
General help options
|
||||||
-h --help
|
-h --help
|
||||||
show general or COMMAND help
|
show general or COMMAND help
|
||||||
|
|
||||||
@ -244,8 +239,7 @@ Options
|
|||||||
--debug[=N]
|
--debug[=N]
|
||||||
show debug output (levels 1-9, default: 1)
|
show debug output (levels 1-9, default: 1)
|
||||||
|
|
||||||
General input options:
|
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)
|
||||||
@ -273,8 +267,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)
|
||||||
|
|
||||||
General 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)
|
||||||
@ -389,6 +382,10 @@ Options
|
|||||||
|
|
||||||
Some reporting options can also be written as query arguments.
|
Some reporting options can also be written as query arguments.
|
||||||
|
|
||||||
|
Command line tips
|
||||||
|
Here are some details useful to know about for hledger command lines
|
||||||
|
(and elsewhere). Feel free to skip this section until you need it.
|
||||||
|
|
||||||
Option repetition
|
Option repetition
|
||||||
If options are repeated in a command line, hledger will generally use
|
If options are repeated in a command line, hledger will generally use
|
||||||
the last (right-most) occurence. Some of the boolean flags will toggle
|
the last (right-most) occurence. Some of the boolean flags will toggle
|
||||||
@ -396,52 +393,6 @@ Options
|
|||||||
-%/--percent, -E/--empty, -N/--no-total, -T/--row-total, -A/--average,
|
-%/--percent, -E/--empty, -N/--no-total, -T/--row-total, -A/--average,
|
||||||
and -S/--sort-amount.
|
and -S/--sort-amount.
|
||||||
|
|
||||||
Command options
|
|
||||||
To see options for a particular command, including command-specific op-
|
|
||||||
tions, run: hledger COMMAND -h.
|
|
||||||
|
|
||||||
Command-specific options must be written after the command name, eg:
|
|
||||||
hledger print -x.
|
|
||||||
|
|
||||||
Additionally, if the command is an add-on, you may need to put its op-
|
|
||||||
tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can
|
|
||||||
run the add-on executable directly: hledger-ui --watch.
|
|
||||||
|
|
||||||
Command arguments
|
|
||||||
Most hledger commands accept arguments after the command name, which
|
|
||||||
are often a query, filtering the data in some way.
|
|
||||||
|
|
||||||
You can save a set of command line options/arguments in a file, and
|
|
||||||
then reuse them by writing @FILENAME as a command line argument. Eg:
|
|
||||||
hledger bal @foo.args. (To prevent this, eg if you have an argument
|
|
||||||
that begins with a literal @, precede it with --, eg: hledger bal --
|
|
||||||
@ARG).
|
|
||||||
|
|
||||||
Inside the argument file, each line should contain just one option or
|
|
||||||
argument. Avoid the use of spaces, except inside quotes (or you'll see
|
|
||||||
a confusing error). Between a flag and its argument, use = (or noth-
|
|
||||||
ing). Bad:
|
|
||||||
|
|
||||||
assets depth:2
|
|
||||||
-X USD
|
|
||||||
|
|
||||||
Good:
|
|
||||||
|
|
||||||
assets
|
|
||||||
depth:2
|
|
||||||
-X=USD
|
|
||||||
|
|
||||||
For special characters (see below), use one less level of quoting than
|
|
||||||
you would at the command prompt. Bad:
|
|
||||||
|
|
||||||
-X"$"
|
|
||||||
|
|
||||||
Good:
|
|
||||||
|
|
||||||
-X$
|
|
||||||
|
|
||||||
See also: Save frequently used options.
|
|
||||||
|
|
||||||
Special characters
|
Special characters
|
||||||
Single escaping (shell metacharacters)
|
Single escaping (shell metacharacters)
|
||||||
In shell command lines, characters significant to your shell - such as
|
In shell command lines, characters significant to your shell - such as
|
||||||
@ -593,51 +544,33 @@ Options
|
|||||||
ing to the shell and so must be escaped at least once more. See Spe-
|
ing to the shell and so must be escaped at least once more. See Spe-
|
||||||
cial characters.
|
cial characters.
|
||||||
|
|
||||||
Commands
|
Argument files
|
||||||
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 @FILENAME as a command line argument. Eg:
|
||||||
A few assist with data entry and management.
|
hledger bal @foo.args.
|
||||||
|
|
||||||
Run hledger with no arguments to list the commands available, and
|
Inside the argument file, each line should contain just one option or
|
||||||
hledger CMD to run a command. CMD can be the full command name, or its
|
argument. Also, don't use spaces except inside quotes (or you'll see a
|
||||||
standard abbreviation shown in the commands list, or any unambiguous
|
confusing error). Ie, write = (or nothing) between a flag and its ar-
|
||||||
prefix of the name. Eg: hledger bal.
|
gument. Eg, bad:
|
||||||
|
|
||||||
Add-on commands
|
assets -X USD
|
||||||
Add-on commands are extra subcommands provided by programs or scripts
|
|
||||||
in your PATH
|
|
||||||
|
|
||||||
o whose name starts with hledger-
|
Good:
|
||||||
|
|
||||||
o whose name ends with a recognised file extension: .bat,.com,.exe,
|
assets
|
||||||
.hs,.lhs,.pl,.py,.rb,.rkt,.sh or none
|
-X=USD
|
||||||
|
|
||||||
o and (on unix, mac) which are executable by the current user.
|
For the special characters mentioned above, use one less level of quot-
|
||||||
|
ing than you would at the command prompt. Eg, bad:
|
||||||
|
|
||||||
Addons can be written in any language, but haskell scripts or programs
|
-X"$"
|
||||||
have a big advantage: they can use hledger's library code, for command-
|
|
||||||
line options, parsing and reporting.
|
|
||||||
|
|
||||||
Several add-on commands are installed by the hledger-install script.
|
Good:
|
||||||
See https://hledger.org/scripts.html for more details.
|
|
||||||
|
|
||||||
Note in a hledger command line, add-on command flags must have a double
|
-X$
|
||||||
dash (--) preceding them. Eg you must write:
|
|
||||||
|
|
||||||
$ hledger web -- --serve
|
See also: Save frequently used options.
|
||||||
|
|
||||||
and not:
|
|
||||||
|
|
||||||
$ hledger web --serve
|
|
||||||
|
|
||||||
(because the --serve flag belongs to hledger-web, not hledger).
|
|
||||||
|
|
||||||
The -h/--help and --version flags don't require --.
|
|
||||||
|
|
||||||
If you have any trouble with this, remember you can always run the add-
|
|
||||||
on program directly, eg:
|
|
||||||
|
|
||||||
$ hledger-web --serve
|
|
||||||
|
|
||||||
Output
|
Output
|
||||||
Output destination
|
Output destination
|
||||||
@ -803,6 +736,20 @@ Output
|
|||||||
|
|
||||||
hledger bal --debug=3 2>hledger.log
|
hledger bal --debug=3 2>hledger.log
|
||||||
|
|
||||||
|
Environment
|
||||||
|
These environment variables affect hledger:
|
||||||
|
|
||||||
|
COLUMNS This is normally set by your terminal; some hledger commands
|
||||||
|
(register) will format their output to this width. If not set, they
|
||||||
|
will try to use the available terminal width.
|
||||||
|
|
||||||
|
LEDGER_FILE The main journal file to use when not specified with
|
||||||
|
-f/--file. Default: $HOME/.hledger.journal.
|
||||||
|
|
||||||
|
NO_COLOR If this environment variable is set (with any value), hledger
|
||||||
|
will not use ANSI color codes in terminal output, unless overridden by
|
||||||
|
an explicit --color/--colour option.
|
||||||
|
|
||||||
PART 2: DATA FORMATS
|
PART 2: DATA FORMATS
|
||||||
Journal
|
Journal
|
||||||
hledger's default file format, representing a General Journal. Here's
|
hledger's default file format, representing a General Journal. Here's
|
||||||
@ -1678,13 +1625,13 @@ Journal
|
|||||||
purpose directive
|
purpose directive
|
||||||
--------------------------------------------------------------------------
|
--------------------------------------------------------------------------
|
||||||
READING DATA:
|
READING DATA:
|
||||||
|
|
||||||
Rewrite account names alias
|
Rewrite account names alias
|
||||||
Comment out sections of the file comment
|
Comment out sections of the file comment
|
||||||
Declare file's decimal mark, to help decimal-mark
|
Declare file's decimal mark, to help decimal-mark
|
||||||
parse amounts accurately
|
parse amounts accurately
|
||||||
Include other data files include
|
Include other data files include
|
||||||
GENERATING DATA:
|
GENERATING DATA:
|
||||||
|
|
||||||
Generate recurring transactions or bud- ~
|
Generate recurring transactions or bud- ~
|
||||||
get goals
|
get goals
|
||||||
Generate extra postings on existing =
|
Generate extra postings on existing =
|
||||||
@ -1747,9 +1694,6 @@ Journal
|
|||||||
payee Declares a payee name, for checking all entries in all files. N
|
payee Declares a payee name, for checking all entries in all files. N
|
||||||
P Declares the market price of a commodity on some date, for value N
|
P Declares the market price of a commodity on some date, for value N
|
||||||
reports.
|
reports.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
~ Declares a periodic transaction rule that generates future N
|
~ Declares a periodic transaction rule that generates future N
|
||||||
(tilde) transactions with --forecast and budget goals with balance
|
(tilde) transactions with --forecast and budget goals with balance
|
||||||
--budget.
|
--budget.
|
||||||
@ -1760,6 +1704,7 @@ Journal
|
|||||||
D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N
|
D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N
|
||||||
there is no commodity directive for this commodity: its decimal
|
there is no commodity directive for this commodity: its decimal
|
||||||
mark, balancing precision, and display style, as above.
|
mark, balancing precision, and display style, as above.
|
||||||
|
|
||||||
Y Sets a default year to use for any yearless dates, in following Y
|
Y Sets a default year to use for any yearless dates, in following Y
|
||||||
entries until end of current file.
|
entries until end of current file.
|
||||||
= Declares an auto posting rule that generates extra postings on partly
|
= Declares an auto posting rule that generates extra postings on partly
|
||||||
@ -2095,7 +2040,7 @@ Journal
|
|||||||
|
|
||||||
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
|
||||||
|
|
||||||
@ -2105,7 +2050,7 @@ Journal
|
|||||||
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
|
||||||
|
|
||||||
@ -2280,7 +2225,7 @@ Journal
|
|||||||
|
|
||||||
The path may also be prefixed to force a specific file format, overrid-
|
The path may also be prefixed to force a specific file format, overrid-
|
||||||
ing the file extension (as described in hledger.1 -> Input files): in-
|
ing the file extension (as described in hledger.1 -> Input files): in-
|
||||||
clude timedot:~/notes/2020*.md.
|
clude timedot:~/notes/2023*.md.
|
||||||
|
|
||||||
P directive
|
P directive
|
||||||
The P directive declares a market price, which is a conversion rate be-
|
The P directive declares a market price, which is a conversion rate be-
|
||||||
@ -2367,8 +2312,8 @@ Journal
|
|||||||
to cover a whole number of that interval. (This is done to improve
|
to cover a whole number of that interval. (This is done to improve
|
||||||
reports, but it also affects periodic transactions. Yes, it's a bit
|
reports, but it also affects periodic transactions. Yes, it's a bit
|
||||||
inconsistent with the above.) Eg: ~ every 10th day of month from
|
inconsistent with the above.) Eg: ~ every 10th day of month from
|
||||||
2020/01, which is equivalent to ~ every 10th day of month from
|
2023/01, which is equivalent to ~ every 10th day of month from
|
||||||
2020/01/01, will be adjusted to start on 2019/12/10.
|
2023/01/01, will be adjusted to start on 2019/12/10.
|
||||||
|
|
||||||
Periodic rule syntax
|
Periodic rule syntax
|
||||||
A periodic transaction rule looks like a normal journal entry, with the
|
A periodic transaction rule looks like a normal journal entry, with the
|
||||||
@ -2410,10 +2355,10 @@ Journal
|
|||||||
where the period expression ends, so that descriptions can not acciden-
|
where the period expression ends, so that descriptions can not acciden-
|
||||||
tally alter their meaning, as in this example:
|
tally alter their meaning, as in this example:
|
||||||
|
|
||||||
; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
|
; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
|
||||||
; ||
|
; ||
|
||||||
; vv
|
; vv
|
||||||
~ every 2 months in 2020, we will review
|
~ every 2 months in 2023, we will review
|
||||||
assets:bank:checking $1500
|
assets:bank:checking $1500
|
||||||
income:acme inc
|
income:acme inc
|
||||||
|
|
||||||
@ -2868,6 +2813,7 @@ CSV
|
|||||||
times
|
times
|
||||||
newest-first improve txn order when: there are multiple
|
newest-first improve txn order when: there are multiple
|
||||||
records, newest first, all with the same date
|
records, newest first, all with the same date
|
||||||
|
|
||||||
intra-day-reversed improve txn order when: same-day txns are in
|
intra-day-reversed improve txn order when: same-day txns are in
|
||||||
opposite order to the overall file
|
opposite order to the overall file
|
||||||
decimal-mark declare the decimal mark used in CSV amounts,
|
decimal-mark declare the decimal mark used in CSV amounts,
|
||||||
@ -3350,11 +3296,11 @@ CSV
|
|||||||
whitespace) are removed. So for example, when reading an SSV file, if
|
whitespace) are removed. So for example, when reading an SSV file, if
|
||||||
the original record was:
|
the original record was:
|
||||||
|
|
||||||
2020-01-01; "Acme, Inc."; 1,000
|
2023-01-01; "Acme, Inc."; 1,000
|
||||||
|
|
||||||
the regex would see, and try to match, this modified record text:
|
the regex would see, and try to match, this modified record text:
|
||||||
|
|
||||||
2020-01-01,Acme, Inc., 1,000
|
2023-01-01,Acme, Inc., 1,000
|
||||||
|
|
||||||
When an if block has multiple matchers, they are combined as follows:
|
When an if block has multiple matchers, they are combined as follows:
|
||||||
|
|
||||||
@ -3409,7 +3355,7 @@ CSV
|
|||||||
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
|
||||||
|
|
||||||
balance-type
|
balance-type
|
||||||
Balance assertions generated by assigning to balanceN are of the simple
|
Balance assertions generated by assigning to balanceN are of the simple
|
||||||
@ -3656,20 +3602,20 @@ CSV
|
|||||||
If the currency/commodity symbol is included in the CSV's amount
|
If the currency/commodity symbol is included in the CSV's amount
|
||||||
field(s):
|
field(s):
|
||||||
|
|
||||||
2020-01-01,foo,$123.00
|
2023-01-01,foo,$123.00
|
||||||
|
|
||||||
you don't have to do anything special for the commodity symbol, it will
|
you don't have to do anything special for the commodity symbol, it will
|
||||||
be assigned as part of the amount. Eg:
|
be assigned as part of the amount. Eg:
|
||||||
|
|
||||||
fields date,description,amount
|
fields date,description,amount
|
||||||
|
|
||||||
2020-01-01 foo
|
2023-01-01 foo
|
||||||
expenses:unknown $123.00
|
expenses:unknown $123.00
|
||||||
income:unknown $-123.00
|
income:unknown $-123.00
|
||||||
|
|
||||||
If the currency is provided as a separate CSV field:
|
If the currency is provided as a separate CSV field:
|
||||||
|
|
||||||
2020-01-01,foo,USD,123.00
|
2023-01-01,foo,USD,123.00
|
||||||
|
|
||||||
You can assign that to the currency pseudo-field, which has the special
|
You can assign that to the currency pseudo-field, which has the special
|
||||||
effect of prepending itself to every amount in the transaction (on the
|
effect of prepending itself to every amount in the transaction (on the
|
||||||
@ -3677,7 +3623,7 @@ CSV
|
|||||||
|
|
||||||
fields date,description,currency,amount
|
fields date,description,currency,amount
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
@ -3688,7 +3634,7 @@ CSV
|
|||||||
fields date,description,cur,amt
|
fields date,description,cur,amt
|
||||||
amount %amt %cur
|
amount %amt %cur
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
@ -4204,13 +4150,13 @@ Timedot
|
|||||||
biz:research 1
|
biz:research 1
|
||||||
|
|
||||||
* Time log
|
* Time log
|
||||||
** 2020-01-01
|
** 2023-01-01
|
||||||
*** adm:time .
|
*** adm:time .
|
||||||
*** adm:finance .
|
*** adm:finance .
|
||||||
|
|
||||||
* 2020 Work Diary
|
* 2023 Work Diary
|
||||||
** Q1
|
** Q1
|
||||||
*** 2020-02-29
|
*** 2023-02-29
|
||||||
**** DONE
|
**** DONE
|
||||||
0700 yoga
|
0700 yoga
|
||||||
**** UNPLANNED
|
**** UNPLANNED
|
||||||
@ -4322,7 +4268,6 @@ Time periods
|
|||||||
row
|
row
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
last/this/next -1, 0, 1 periods from the current period
|
last/this/next -1, 0, 1 periods from the current period
|
||||||
day/week/month/quar-
|
day/week/month/quar-
|
||||||
ter/year
|
ter/year
|
||||||
@ -4565,7 +4510,7 @@ Queries
|
|||||||
|
|
||||||
o Add a query type prefix to match other parts of the data:
|
o Add a query type prefix to match other parts of the data:
|
||||||
|
|
||||||
date:202012- desc:amazon cur:USD amt:">100" status:
|
date:202312- desc:amazon cur:USD amt:">100" status:
|
||||||
|
|
||||||
o Add a not: prefix to negate a term:
|
o Add a not: prefix to negate a term:
|
||||||
|
|
||||||
@ -4701,7 +4646,7 @@ Queries
|
|||||||
|
|
||||||
Queries and command options
|
Queries and command options
|
||||||
Some queries can also be expressed as command-line options: depth:2 is
|
Some queries can also be expressed as command-line options: depth:2 is
|
||||||
equivalent to --depth 2, date:2020 is equivalent to -p 2020, etc. When
|
equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When
|
||||||
you mix command options and query arguments, generally the resulting
|
you mix command options and query arguments, generally the resulting
|
||||||
query is their intersection.
|
query is their intersection.
|
||||||
|
|
||||||
@ -5677,6 +5622,7 @@ Valuation
|
|||||||
(-H) with port or posting was made port or
|
(-H) with port or posting was made port or
|
||||||
report journal journal
|
report journal journal
|
||||||
interval start start
|
interval start start
|
||||||
|
|
||||||
posting cost value at re- value at posting value at re- value at
|
posting cost value at re- value at posting value at re- value at
|
||||||
amounts port or date port or DATE/today
|
amounts port or date port or DATE/today
|
||||||
journal end journal end
|
journal end journal end
|
||||||
@ -5718,9 +5664,6 @@ Valuation
|
|||||||
fore report all postings respective post- all postings
|
fore report all postings respective post- all postings
|
||||||
start before re- ing dates before re-
|
start before re- ing dates before re-
|
||||||
port start port start
|
port start port start
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
balance sums of same as sums of values of balance value at
|
balance sums of same as sums of values of balance value at
|
||||||
changes costs of --value=end postings in pe- change in DATE/today of
|
changes costs of --value=end postings in pe- change in DATE/today of
|
||||||
(bal, is, postings in riod at respec- each period, sums of post-
|
(bal, is, postings in riod at respec- each period, sums of post-
|
||||||
@ -8503,20 +8446,20 @@ PART 5: COMMON TASKS
|
|||||||
Please create it first, eg with "hledger add" or a text editor.
|
Please create it first, eg with "hledger add" or a text editor.
|
||||||
Or, specify an existing journal file with -f or LEDGER_FILE.
|
Or, specify an existing journal file with -f or LEDGER_FILE.
|
||||||
|
|
||||||
You can override this by setting the LEDGER_FILE environment variable.
|
You can override this by setting the LEDGER_FILE environment variable
|
||||||
It's a good practice to keep this important file under version control,
|
(see below). It's a good practice to keep this important file under
|
||||||
and to start a new file each year. So you could do something like
|
version control, and to start a new file each year. So you could do
|
||||||
this:
|
something like this:
|
||||||
|
|
||||||
$ mkdir ~/finance
|
$ mkdir ~/finance
|
||||||
$ cd ~/finance
|
$ cd ~/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 "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc
|
$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
|
||||||
$ source ~/.bashrc
|
$ source ~/.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
|
||||||
@ -8528,6 +8471,37 @@ PART 5: COMMON TASKS
|
|||||||
Commodities : 0 ()
|
Commodities : 0 ()
|
||||||
Market prices : 0 ()
|
Market prices : 0 ()
|
||||||
|
|
||||||
|
Setting LEDGER_FILE
|
||||||
|
How to set LEDGER_FILE permanently depends on your setup:
|
||||||
|
|
||||||
|
On unix and mac, running these commands in the terminal will work for
|
||||||
|
many people; adapt as needed:
|
||||||
|
|
||||||
|
$ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile
|
||||||
|
$ source ~/.profile
|
||||||
|
|
||||||
|
When correctly configured, in a new terminal window env | grep
|
||||||
|
LEDGER_FILE will show your file, and so will hledger files.
|
||||||
|
|
||||||
|
On mac, this additional step might be helpful for GUI applications
|
||||||
|
(like Emacs started from the dock): add an entry to ~/.MacOSX/environ-
|
||||||
|
ment.plist like
|
||||||
|
|
||||||
|
{
|
||||||
|
"LEDGER_FILE" : "~/finance/2023.journal"
|
||||||
|
}
|
||||||
|
|
||||||
|
and then run killall Dock in a terminal window (or restart the ma-
|
||||||
|
chine).
|
||||||
|
|
||||||
|
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 per-
|
||||||
|
sists across a reboot, and if you need to be an Administrator):
|
||||||
|
|
||||||
|
> CD
|
||||||
|
> MKDIR finance
|
||||||
|
> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
|
||||||
|
|
||||||
Setting opening balances
|
Setting opening balances
|
||||||
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
|
||||||
real-world assets (bank accounts, wallet..) and liabilities (credit
|
real-world assets (bank accounts, wallet..) and liabilities (credit
|
||||||
@ -8545,7 +8519,7 @@ PART 5: COMMON TASKS
|
|||||||
o The first way: open the journal in any text editor and save an entry
|
o The first way: open the journal in any text editor and save an entry
|
||||||
like this:
|
like this:
|
||||||
|
|
||||||
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
|
||||||
@ -8568,7 +8542,7 @@ PART 5: COMMON TASKS
|
|||||||
similar transaction:
|
similar transaction:
|
||||||
|
|
||||||
$ 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.
|
||||||
@ -8576,7 +8550,7 @@ PART 5: COMMON TASKS
|
|||||||
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
|
||||||
@ -8589,7 +8563,7 @@ PART 5: COMMON TASKS
|
|||||||
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
|
||||||
@ -8599,12 +8573,12 @@ PART 5: COMMON TASKS
|
|||||||
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]: .
|
||||||
|
|
||||||
If you're using version control, this could be a good time to commit
|
If you're using version control, this could be a good time to commit
|
||||||
the journal. Eg:
|
the journal. Eg:
|
||||||
|
|
||||||
$ git commit -m 'initial balances' 2020.journal
|
$ git commit -m 'initial balances' 2023.journal
|
||||||
|
|
||||||
Recording transactions
|
Recording transactions
|
||||||
As you spend or receive money, you can record these transactions using
|
As you spend or receive money, you can record these transactions using
|
||||||
@ -8615,15 +8589,15 @@ PART 5: COMMON TASKS
|
|||||||
Here are some simple transactions, see the hledger_journal(5) manual
|
Here are some simple transactions, see the hledger_journal(5) manual
|
||||||
and hledger.org for more ideas:
|
and hledger.org for more ideas:
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
@ -8647,7 +8621,7 @@ PART 5: COMMON TASKS
|
|||||||
transaction. Eg if you have $105 after the above, and can't explain
|
transaction. Eg if you have $105 after the above, and can't explain
|
||||||
the missing $2, it could be:
|
the missing $2, it could be:
|
||||||
|
|
||||||
2020-01-16 * adjust cash
|
2023-01-16 * adjust cash
|
||||||
assets:cash $-2 = $105
|
assets:cash $-2 = $105
|
||||||
expenses:misc
|
expenses:misc
|
||||||
|
|
||||||
@ -8670,12 +8644,12 @@ PART 5: COMMON TASKS
|
|||||||
After reconciling, it could be a good time to mark the reconciled
|
After reconciling, it could be a good time to mark the reconciled
|
||||||
transactions' status as "cleared and confirmed", if you want to track
|
transactions' status as "cleared and confirmed", if you want to track
|
||||||
that, by adding the * marker. Eg in the paycheck transaction above,
|
that, by adding the * marker. Eg in the paycheck transaction above,
|
||||||
insert * between 2020-01-15 and paycheck
|
insert * between 2023-01-15 and paycheck
|
||||||
|
|
||||||
If you're using version control, this can be another good time to com-
|
If you're using version control, this can be another good time to com-
|
||||||
mit:
|
mit:
|
||||||
|
|
||||||
$ git commit -m 'txns' 2020.journal
|
$ git commit -m 'txns' 2023.journal
|
||||||
|
|
||||||
Reporting
|
Reporting
|
||||||
Here are some basic reports.
|
Here are some basic reports.
|
||||||
@ -8683,26 +8657,26 @@ PART 5: COMMON TASKS
|
|||||||
Show all transactions:
|
Show all transactions:
|
||||||
|
|
||||||
$ 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
|
||||||
|
|
||||||
@ -8758,9 +8732,9 @@ PART 5: COMMON TASKS
|
|||||||
balance sheet:
|
balance sheet:
|
||||||
|
|
||||||
$ hledger bs -2
|
$ hledger bs -2
|
||||||
Balance Sheet 2020-01-16
|
Balance Sheet 2023-01-16
|
||||||
|
|
||||||
|| 2020-01-16
|
|| 2023-01-16
|
||||||
========================++============
|
========================++============
|
||||||
Assets ||
|
Assets ||
|
||||||
------------------------++------------
|
------------------------++------------
|
||||||
@ -8783,9 +8757,9 @@ PART 5: COMMON TASKS
|
|||||||
Show income and expense totals, formatted as an income statement:
|
Show income and expense totals, formatted as an income statement:
|
||||||
|
|
||||||
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 ||
|
||||||
---------------++-----------------------
|
---------------++-----------------------
|
||||||
@ -8808,17 +8782,17 @@ PART 5: COMMON TASKS
|
|||||||
Show transactions affecting your wallet, with running total:
|
Show transactions affecting your wallet, with running total:
|
||||||
|
|
||||||
$ 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
|
||||||
|
|
||||||
Show weekly posting counts as a bar chart:
|
Show weekly posting counts as a bar chart:
|
||||||
|
|
||||||
$ hledger activity -W
|
$ hledger activity -W
|
||||||
2019-12-30 *****
|
2019-12-30 *****
|
||||||
2020-01-06 ****
|
2023-01-06 ****
|
||||||
2020-01-13 ****
|
2023-01-13 ****
|
||||||
|
|
||||||
Migrating to a new file
|
Migrating to a new file
|
||||||
At the end of the year, you may want to continue your journal in a new
|
At the end of the year, you may want to continue your journal in a new
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user