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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2023-12-15 13:59:02 -10:00
parent 60f7896dd5
commit ac50d8c5a6
6 changed files with 1219 additions and 1660 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
hledger-web/hledger-web.1
View File

@ -59,44 +59,13 @@ With \f[CR]--serve-api\f[R]: only the JSON API is served.
In all cases hledger-web runs as a foreground process, logging requests In all cases hledger-web runs as a foreground process, logging requests
to stdout. to stdout.
.SH OPTIONS .SH OPTIONS
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 will be applied
in addition to any search query entered there.
.PP
hledger-web provides the following options: hledger-web provides the following options:
.TP .TP
\f[CR]--serve\f[R] \f[CR]--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
.TP .TP
\f[CR]--serve-api\f[R] \f[CR]--serve-api\f[R]
like --serve, but serve only the JSON web API, without the server-side like --serve, but serve only the JSON web API, not the web UI
web UI
.TP
\f[CR]--host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1)
.TP
\f[CR]--port=PORT\f[R]
listen on this TCP port (default: 5000)
.TP
\f[CR]--socket=SOCKETFILE\f[R]
use a unix domain socket file to listen for requests instead of a TCP
socket.
Implies \f[CR]--serve\f[R].
It can only be used if the operating system can provide this type of
socket.
.TP
\f[CR]--base-url=URL\f[R]
set the base url (default: http://IPADDR:PORT).
Note: affects url generation but not route parsing.
Can be useful if running behind a reverse web proxy that does path
rewriting.
.TP
\f[CR]--file-url=URL\f[R]
set the static files url (default: BASEURL/static).
hledger-web normally serves static files itself, but if you wanted to
serve them from another server for efficiency, you would set the url
with this.
.TP .TP
\f[CR]--allow=view|add|edit\f[R] \f[CR]--allow=view|add|edit\f[R]
set the user\[aq]s access level for changing data (default: set the user\[aq]s access level for changing data (default:
@ -104,49 +73,59 @@ set the user\[aq]s access level for changing data (default:
It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads
permissions from the \f[CR]X-Sandstorm-Permissions\f[R] request header). permissions from the \f[CR]X-Sandstorm-Permissions\f[R] request header).
.TP .TP
\f[CR]--cors=ORIGIN\f[R]
allow cross-origin requests from the specified origin; setting ORIGIN to
\[dq]*\[dq] allows requests from any origin
.TP
\f[CR]--host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1)
.PP
By default the server listens on IP address \f[CR]127.0.0.1\f[R], which
is accessible only to requests from the local machine..
You can use \f[CR]--host\f[R] to listen on a different address
configured on the machine, eg to allow access from other machines.
The special address \f[CR]0.0.0.0\f[R] causes it to listen on all
addresses configured on the machine.
.TP
\f[CR]--port=PORT\f[R]
listen on this TCP port (default: 5000)
.PP
Similarly, you can use \f[CR]--port\f[R] to listen on a TCP port other
than 5000.
This is useful if you want to run multiple hledger-web instances on a
machine.
.TP
\f[CR]--socket=SOCKETFILE\f[R]
listen on the given unix socket instead of an IP address and port (unix
only; implies --serve)
.PP
When \f[CR]--socket\f[R] is used, hledger-web creates and communicates
via a socket file instead of a TCP port.
This can be more secure, respects unix file permissions, and makes
certain use cases easier, such as running per-user instances behind an
nginx reverse proxy.
(Eg:
\f[CR]proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;\f[R].)
.TP
\f[CR]--base-url=URL\f[R]
set the base url (default: http://IPADDR:PORT).
.PP
You can use \f[CR]--base-url\f[R] to change the protocol, hostname, port
and path that appear in hledger-web\[aq]s hyperlinks.
This is useful eg when integrating hledger-web within a larger website.
The default is \f[CR]http://HOST:PORT/\f[R] using the server\[aq]s
configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT
is 80).
Note this affects url generation but not route parsing.
.TP
\f[CR]--test\f[R] \f[CR]--test\f[R]
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
By default the server listens on IP address 127.0.0.1, accessible only hledger-web also supports many of hledger\[aq]s general options.
to local requests. Query options and arguments may be used to set an initial filter, which
You can use \f[CR]--host\f[R] to change this, eg although not shown in the UI, will restrict the data shown, in addition
\f[CR]--host 0.0.0.0\f[R] to listen on all configured addresses. to any search query entered in the UI.
.PP
Similarly, use \f[CR]--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[CR]--socket\f[R] is used.
In this case, it creates an \f[CR]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[CR]nginx\f[R] as reverse proxy can use the variable
\f[CR]$remote_user\f[R] to derive a path from the username used in a
HTTP basic authentication.
The following \f[CR]proxy_pass\f[R] directive allows access to all
\f[CR]hledger-web\f[R] instances that created a socket in
\f[CR]/tmp/hledger/\f[R]:
.IP
.EX
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
.EE
.PP
You can use \f[CR]--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[CR]http://HOST:PORT/\f[R] using the server\[aq]s
configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT
is 80).
.PP
With \f[CR]--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 .SS General help options
.TP .TP
\f[CR]-h --help\f[R] \f[CR]-h --help\f[R]

155
hledger-web/hledger-web.info
View File

@ -75,83 +75,72 @@ File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
1 OPTIONS 1 OPTIONS
********* *********
Command-line options and arguments may be used to set an initial filter hledger-web provides the following options:
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.
hledger-web provides the following options:
'--serve' '--serve'
serve and log requests, don't browse or auto-exit after timeout serve and log requests, don't browse or auto-exit after timeout
'--serve-api' '--serve-api'
like -serve, but serve only the JSON web API, without the like -serve, but serve only the JSON web API, not the web UI
server-side web UI
'--host=IPADDR'
listen on this IP address (default: 127.0.0.1)
'--port=PORT'
listen on this TCP port (default: 5000)
'--socket=SOCKETFILE'
use a unix domain socket file to listen for requests instead of a
TCP socket. Implies '--serve'. It can only be used if the
operating system can provide this type of socket.
'--base-url=URL'
set the base url (default: http://IPADDR:PORT). Note: affects url
generation but not route parsing. Can be useful if running behind
a reverse web proxy that does path rewriting.
'--file-url=URL'
set the static files url (default: BASEURL/static). hledger-web
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url with
this.
'--allow=view|add|edit' '--allow=view|add|edit'
set the user's access level for changing data (default: 'add'). It set the user's access level for changing data (default: 'add'). It
also accepts 'sandstorm' for use on that platform (reads also accepts 'sandstorm' for use on that platform (reads
permissions from the 'X-Sandstorm-Permissions' request header). permissions from the 'X-Sandstorm-Permissions' request header).
'--cors=ORIGIN'
allow cross-origin requests from the specified origin; setting
ORIGIN to "*" allows requests from any origin
'--host=IPADDR'
listen on this IP address (default: 127.0.0.1)
By default the server listens on IP address '127.0.0.1', which is
accessible only to requests from the local machine.. You can use
'--host' to listen on a different address configured on the machine, eg
to allow access from other machines. The special address '0.0.0.0'
causes it to listen on all addresses configured on the machine.
'--port=PORT'
listen on this TCP port (default: 5000)
Similarly, you can use '--port' to listen on a TCP port other than
5000. This is useful if you want to run multiple hledger-web instances
on a machine.
'--socket=SOCKETFILE'
listen on the given unix socket instead of an IP address and port
(unix only; implies -serve)
When '--socket' is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as
running per-user instances behind an nginx reverse proxy. (Eg:
'proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;'.)
'--base-url=URL'
set the base url (default: http://IPADDR:PORT).
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hledger-web's hyperlinks. This is useful eg when
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). Note this affects url generation
but not route parsing.
'--test' '--test'
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
By default the server listens on IP address 127.0.0.1, accessible hledger-web also supports many of hledger's general options. Query
only to local requests. You can use '--host' to change this, eg '--host options and arguments may be used to set an initial filter, which
0.0.0.0' to listen on all configured addresses. although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
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: * Menu:
@ -645,28 +634,28 @@ Tag Table:
Node: Top225 Node: Top225
Node: OPTIONS2580 Node: OPTIONS2580
Ref: #options2685 Ref: #options2685
Node: General help options5973 Node: General help options5259
Ref: #general-help-options6123 Ref: #general-help-options5409
Node: General input options6405 Node: General input options5691
Ref: #general-input-options6591 Ref: #general-input-options5877
Node: General reporting options7293 Node: General reporting options6579
Ref: #general-reporting-options7458 Ref: #general-reporting-options6744
Node: PERMISSIONS10848 Node: PERMISSIONS10134
Ref: #permissions10987 Ref: #permissions10273
Node: EDITING UPLOADING DOWNLOADING12199 Node: EDITING UPLOADING DOWNLOADING11485
Ref: #editing-uploading-downloading12380 Ref: #editing-uploading-downloading11666
Node: RELOADING13214 Node: RELOADING12500
Ref: #reloading13348 Ref: #reloading12634
Node: JSON API13781 Node: JSON API13067
Ref: #json-api13896 Ref: #json-api13182
Node: DEBUG OUTPUT19384 Node: DEBUG OUTPUT18670
Ref: #debug-output19509 Ref: #debug-output18795
Node: Debug output19536 Node: Debug output18822
Ref: #debug-output-119637 Ref: #debug-output-118923
Node: ENVIRONMENT20054 Node: ENVIRONMENT19340
Ref: #environment20173 Ref: #environment19459
Node: BUGS20290 Node: BUGS19576
Ref: #bugs20374 Ref: #bugs19660
 
End Tag Table End Tag Table

231
hledger-web/hledger-web.txt
View File

@ -52,79 +52,66 @@ DESCRIPTION
to stdout. to stdout.
OPTIONS OPTIONS
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
will be applied in addition to any search query entered there.
hledger-web provides the following options: hledger-web provides the following options:
--serve --serve
serve and log requests, don't browse or auto-exit after timeout serve and log requests, don't browse or auto-exit after timeout
--serve-api --serve-api
like --serve, but serve only the JSON web API, without the like --serve, but serve only the JSON web API, not the web UI
server-side web UI
--host=IPADDR
listen on this IP address (default: 127.0.0.1)
--port=PORT
listen on this TCP port (default: 5000)
--socket=SOCKETFILE
use a unix domain socket file to listen for requests instead of
a TCP socket. Implies --serve. It can only be used if the op-
erating system can provide this type of socket.
--base-url=URL
set the base url (default: http://IPADDR:PORT). Note: affects
url generation but not route parsing. Can be useful if running
behind a reverse web proxy that does path rewriting.
--file-url=URL
set the static files url (default: BASEURL/static). hledger-web
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url
with this.
--allow=view|add|edit --allow=view|add|edit
set the user's access level for changing data (default: add). set the user's access level for changing data (default: add).
It also accepts sandstorm for use on that platform (reads per- It also accepts sandstorm for use on that platform (reads per-
missions from the X-Sandstorm-Permissions request header). missions from the X-Sandstorm-Permissions request header).
--test run hledger-web's tests and exit. hspec test runner args may --cors=ORIGIN
allow cross-origin requests from the specified origin; setting
ORIGIN to "*" allows requests from any origin
--host=IPADDR
listen on this IP address (default: 127.0.0.1)
By default the server listens on IP address 127.0.0.1, which is acces-
sible only to requests from the local machine.. You can use --host to
listen on a different address configured on the machine, eg to allow
access from other machines. The special address 0.0.0.0 causes it to
listen on all addresses configured on the machine.
--port=PORT
listen on this TCP port (default: 5000)
Similarly, you can use --port to listen on a TCP port other than 5000.
This is useful if you want to run multiple hledger-web instances on a
machine.
--socket=SOCKETFILE
listen on the given unix socket instead of an IP address and
port (unix only; implies --serve)
When --socket is used, hledger-web creates and communicates via a
socket file instead of a TCP port. This can be more secure, respects
unix file permissions, and makes certain use cases easier, such as run-
ning per-user instances behind an nginx reverse proxy. (Eg: proxy_pass
http://unix:/tmp/hledger/${remote_user}.socket;.)
--base-url=URL
set the base url (default: http://IPADDR:PORT).
You can use --base-url to change the protocol, hostname, port and path
that appear in hledger-web's hyperlinks. This is useful eg when inte-
grating 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). Note this affects url generation
but not route parsing.
--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
By default the server listens on IP address 127.0.0.1, accessible only hledger-web also supports many of hledger's general options. Query op-
to local requests. You can use --host to change this, eg --host tions and arguments may be used to set an initial filter, which al-
0.0.0.0 to listen on all configured addresses. though not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
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 General help options
-h --help -h --help
@ -146,7 +133,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal) $LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE --rules-file=RULESFILE
Conversion rules file to use when reading CSV (default: Conversion rules file to use when reading CSV (default:
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
@ -165,7 +152,7 @@ OPTIONS
assignments) assignments)
-s --strict -s --strict
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
@ -193,7 +180,7 @@ OPTIONS
multiperiod/multicolumn report by year multiperiod/multicolumn report by year
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax using period expressions syntax
--date2 --date2
@ -201,7 +188,7 @@ OPTIONS
fects) fects)
--today=DATE --today=DATE
override today's date (affects relative smart dates, for override today's date (affects relative smart dates, for
tests/examples) tests/examples)
-U --unmarked -U --unmarked
@ -220,21 +207,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep hide/aggregate accounts or postings more than NUM levels deep
-E --empty -E --empty
show items with zero amount, normally hidden (and vice-versa in show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost/selling amount at transaction time convert amounts to their cost/selling amount at transaction time
-V --market -V --market
convert amounts to their market value in default valuation com- convert amounts to their market value in default valuation com-
modities modities
-X --exchange=COMM -X --exchange=COMM
convert amounts to their market value in commodity COMM convert amounts to their market value in commodity COMM
--value --value
convert amounts to cost or market value, more flexibly than convert amounts to cost or market value, more flexibly than
-B/-V/-X -B/-V/-X
--infer-equity --infer-equity
@ -244,38 +231,38 @@ OPTIONS
infer costs from conversion equity postings infer costs from conversion equity postings
--infer-market-prices --infer-market-prices
use costs as additional market prices, as if they were P direc- use costs as additional market prices, as if they were P direc-
tives tives
--forecast --forecast
generate transactions from periodic rules, between the latest generate transactions from periodic rules, between the latest
recorded txn and 6 months from today, or during the specified recorded txn and 6 months from today, or during the specified
PERIOD (= is required). Auto posting rules will be applied to PERIOD (= is required). Auto posting rules will be applied to
these transactions as well. Also, in hledger-ui make future- these transactions as well. Also, in hledger-ui make future-
dated transactions visible. dated transactions visible.
--auto generate extra postings by applying auto posting rules to all --auto generate extra postings by applying auto posting rules to all
txns (not just forecast txns) txns (not just forecast txns)
--verbose-tags --verbose-tags
add visible tags indicating transactions or postings which have add visible tags indicating transactions or postings which have
been generated/modified been generated/modified
--commodity-style --commodity-style
Override the commodity style in the output for the specified Override the commodity style in the output for the specified
commodity. For example 'EUR1.000,00'. commodity. For example 'EUR1.000,00'.
--color=WHEN (or --colour=WHEN) --color=WHEN (or --colour=WHEN)
Should color-supporting commands use ANSI color codes in text Should color-supporting commands use ANSI color codes in text
output. 'auto' (default): whenever stdout seems to be a color- output. 'auto' (default): whenever stdout seems to be a color-
supporting terminal. 'always' or 'yes': always, useful eg when supporting terminal. 'always' or 'yes': always, useful eg when
piping output into 'less -R'. 'never' or 'no': never. A piping output into 'less -R'. 'never' or 'no': never. A
NO_COLOR environment variable overrides this. NO_COLOR environment variable overrides this.
--pretty[=WHEN] --pretty[=WHEN]
Show prettier output, e.g. using unicode box-drawing charac- Show prettier output, e.g. using unicode box-drawing charac-
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
'never' also work). If you provide an argument you must use 'never' also work). If you provide an argument you must use
'=', e.g. '--pretty=yes'. '=', e.g. '--pretty=yes'.
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
@ -284,13 +271,13 @@ OPTIONS
Some reporting options can also be written as query arguments. Some reporting options can also be written as query arguments.
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.
You can restrict who can reach it by You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma- it listens on 127.0.0.1, accessible to all users on the local ma-
chine. chine.
o putting it behind an authenticating proxy, using eg apache or nginx o putting it behind an authenticating proxy, using eg apache or nginx
@ -300,44 +287,44 @@ PERMISSIONS
You can restrict what the users who reach it can do, by You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is one or more of the following capabilities. The default value is
view,add: view,add:
o view - allows viewing the journal file and all included files o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or in- o manage - allows editing, uploading or downloading the main or in-
cluded files cluded files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default. with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will "spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in- let you edit, upload, or download the journal file or any files it in-
cludes. cludes.
Note, unlike any other hledger command, in this mode you (or any visi- Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files. tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur- full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr). yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This (eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.) needs re-testing.)
RELOADING RELOADING
hledger-web detects changes made to the files by other means (eg if you hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message un- makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed. til the file has been fixed.
@ -345,8 +332,8 @@ RELOADING
that both machine clocks are roughly in step.) that both machine clocks are roughly in step.)
JSON API JSON API
In addition to the web UI, hledger-web also serves a JSON API that can In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API be used to get data or add new transactions. If you want the JSON API
only, you can use the --serve-api flag. Eg: only, you can use the --serve-api flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api $ hledger-web -f examples/sample.journal --serve-api
@ -363,7 +350,7 @@ JSON API
/accounttransactions/ACCOUNTNAME /accounttransactions/ACCOUNTNAME
Eg, all account names in the journal (similar to the accounts command). Eg, all account names in the journal (similar to the accounts command).
(hledger-web's JSON does not include newlines, here we use python to (hledger-web's JSON does not include newlines, here we use python to
prettify it): prettify it):
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
@ -404,25 +391,25 @@ JSON API
"aprice": null, "aprice": null,
... ...
Most of the JSON corresponds to hledger's data types; for details of Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level un- on the various data types, eg Transaction. And for a higher level un-
derstanding, see the journal docs. derstanding, see the journal docs.
In some cases there is outer JSON corresponding to a "Report" type. To In some cases there is outer JSON corresponding to a "Report" type. To
understand that, go to the Hledger.Web.Handler.MiscR haddock and look understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg at the source for the appropriate handler to see what it returns. Eg
for /accounttransactions it's getAccounttransactionsR, returning a "ac- for /accounttransactions it's getAccounttransactionsR, returning a "ac-
countTransactionsReport ...". Looking up the haddock for that we can countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport, see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe- which consists of a report title and a list of AccountTransactionsRe-
portItem (etc). portItem (etc).
You can add a new transaction to the journal with a PUT request to You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by /add, if hledger-web was started with the add capability (enabled by
default). The payload must be the full, exact JSON representation of a default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can from hledger-web's /transactions or /accounttransactions, or you can
export it with hledger-lib, eg like so: export it with hledger-lib, eg like so:
.../hledger$ stack ghci hledger-lib .../hledger$ stack ghci hledger-lib
@ -518,28 +505,28 @@ JSON API
"tstatus": "Unmarked" "tstatus": "Unmarked"
} }
And here's how to test adding it with curl. This should add a new en- And here's how to test adding it with curl. This should add a new en-
try to your journal: try to your journal:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
DEBUG OUTPUT DEBUG OUTPUT
Debug output Debug output
You can add --debug[=N] to the command line to log debug output. N You can add --debug[=N] to the command line to log debug output. N
ranges from 1 (least output, the default) to 9 (maximum output). Typi- ranges from 1 (least output, the default) to 9 (maximum output). Typi-
cally you would start with 1 and increase until you are seeing enough. cally you would start with 1 and increase until you are seeing enough.
Debug output goes to stderr, interleaved with the requests logged on Debug output goes to stderr, interleaved with the requests logged on
stdout. To capture debug output in a log file instead, you can usually stdout. To capture debug output in a log file instead, you can usually
redirect stderr, eg: redirect stderr, eg:
hledger-web --debug=3 2>hledger-web.log. hledger-web --debug=3 2>hledger-web.log.
ENVIRONMENT ENVIRONMENT
LEDGER_FILE The main journal file to use when not specified with LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal. -f/--file. Default: $HOME/.hledger.journal.
BUGS BUGS
We welcome bug reports in the hledger issue tracker (shortcut: We welcome bug reports in the hledger issue tracker (shortcut:
http://bugs.hledger.org), or on the #hledger chat or hledger mail list http://bugs.hledger.org), or on the #hledger chat or hledger mail list
(https://hledger.org/support). (https://hledger.org/support).
Some known issues: Some known issues:

472
hledger/hledger.1
View File

@ -1938,7 +1938,7 @@ One workaround is to isolate each commodity into its own subaccount:
a:usd 0 == $1 a:usd 0 == $1
a:euro 0 == 1€ a:euro 0 == 1€
.EE .EE
.SS Assertions and prices .SS Assertions and costs
Balance assertions ignore costs, and should normally be written without Balance assertions ignore costs, and should normally be written without
one: one:
.IP .IP
@ -1947,11 +1947,12 @@ one:
(a) $1 \[at] €1 = $1 (a) $1 \[at] €1 = $1
.EE .EE
.PP .PP
We do allow prices to be written there, however, and print shows them, We do allow costs to be written in balance assertion amounts, however,
even though they don\[aq]t affect whether the assertion passes or fails. and print shows them, but they don\[aq]t affect whether the assertion
passes or fails.
This is for backward compatibility (hledger\[aq]s close command used to This is for backward compatibility (hledger\[aq]s close command used to
generate balance assertions with prices), and because balance generate balance assertions with costs), and because balance
\f[I]assignments\f[R] do use them (see below). \f[I]assignments\f[R] do use costs (see below).
.SS Assertions and subaccounts .SS Assertions and subaccounts
The balance assertions above (\f[CR]=\f[R] and \f[CR]==\f[R]) do not The balance assertions above (\f[CR]=\f[R] and \f[CR]==\f[R]) do not
count the balance from subaccounts; they check the account\[aq]s count the balance from subaccounts; they check the account\[aq]s
@ -8431,157 +8432,131 @@ DATE-value of change from journal start to period end
T} T}
.TE .TE
.SS Budget report .SS Budget report
The \f[CR]--budget\f[R] report type activates extra columns showing any The \f[CR]--budget\f[R] report type is like a regular balance report,
budget goals for each account and period. but with two main differences:
The budget goals are defined by periodic transactions. .IP \[bu] 2
Budget goals and performance percentages are also shown, in brackets
.IP \[bu] 2
Accounts which don\[aq]t have budget goals are hidden by default.
.PP
This is useful for comparing planned and actual income, expenses, time This is useful for comparing planned and actual income, expenses, time
usage, etc. usage, etc.
.PP .PP
For example, you can take average monthly expenses in the common expense Periodic transaction rules are used to define budget goals.
categories to construct a minimal monthly budget: For example, here\[aq]s a periodic rule defining monthly goals for bus
travel and food expenses:
.IP .IP
.EX .EX
;; Budget ;; Budget
\[ti] monthly \[ti] monthly
income $2000 (expenses:bus) $30
expenses:food $400 (expenses:food) $400
expenses:bus $50 .EE
expenses:movies $30 .PP
assets:bank:checking After recording some actual expenses,
.IP
.EX
;; Two months worth of expenses ;; Two months worth of expenses
2017-11-01 2017-11-01
income $1950 income $-1950
expenses:food $396 expenses:bus $35
expenses:bus $49 expenses:food:groceries $310
expenses:movies $30 expenses:food:dining $42
expenses:supplies $20 expenses:movies $38
assets:bank:checking assets:bank:checking
2017-12-01 2017-12-01
income $2100 income $-2100
expenses:food $412 expenses:bus $53
expenses:bus $53 expenses:food:groceries $380
expenses:gifts $100 expenses:food:dining $32
expenses:gifts $100
assets:bank:checking assets:bank:checking
.EE .EE
.PP .PP
You can now see a monthly budget report: we can see a budget report like this:
.IP .IP
.EX .EX
$ hledger balance -M --budget $ hledger bal -M --budget
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017-11-01..2017-12-31:
|| Nov Dec || Nov Dec
======================++==================================================== ===============++============================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] <unbudgeted> || $-425 $-565
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] expenses || $425 [ 99% of $430] $565 [131% of $430]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] expenses:bus || $35 [117% of $30] $53 [177% of $30]
expenses || $495 [ 103% of $480] $565 [ 118% of $480] expenses:food || $352 [ 88% of $400] $412 [103% of $400]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] ---------------++--------------------------------------------
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] || 0 [ 0% of $430] 0 [ 0% of $430]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
.EE .EE
.PP .PP
This is different from a normal balance report in several ways. This is \[dq]goal-based budgeting\[dq]; you define goals for accounts
Currently: and periods, often recurring, and hledger shows performance relative to
the goals.
This contrasts with \[dq]envelope budgeting\[dq], which is more detailed
and strict - useful when cash is tight, but also quite a bit more work.
https://plaintextaccounting.org/Budgeting has more on this topic.
.SS Using the budget report
Historically this report has been confusing and fragile.
hledger\[aq]s version should be relatively robust and intuitive, but you
may still find surprises.
Here are more notes to help with learning and troubleshooting.
.IP \[bu] 2 .IP \[bu] 2
Accounts with budget goals during the report period, and their parents, In the above example, \f[CR]expenses:bus\f[R] and
are shown. \f[CR]expenses:food\f[R] are shown because they have budget goals during
the report period.
.IP \[bu] 2 .IP \[bu] 2
Their subaccounts are not shown (regardless of the depth setting). Their parent \f[CR]expenses\f[R] is also shown, with budget goals
aggregated from the children.
.IP \[bu] 2 .IP \[bu] 2
Accounts without budget goals, if any, are aggregated and shown as The subaccounts \f[CR]expenses:food:groceries\f[R] and
\[dq]<unbudgeted>\[dq]. \f[CR]expenses:food:dining\f[R] are not shown since they have no budget
goal of their own, but they contribute to \f[CR]expenses:food\f[R]\[aq]s
actual amount.
.IP \[bu] 2 .IP \[bu] 2
Amounts are always inclusive (subaccount-including), even in list mode. Unbudgeted accounts \f[CR]expenses:movies\f[R] and
\f[CR]expenses:gifts\f[R] are also not shown, but they contribute to
\f[CR]expenses\f[R]\[aq]s actual amount.
.IP \[bu] 2 .IP \[bu] 2
After each actual amount, the corresponding goal amount and percentage The other unbudgeted accounts \f[CR]income\f[R] and
of goal reached are also shown, in square brackets. \f[CR]assets:bank:checking\f[R] are grouped as \f[CR]<unbudgeted>\f[R].
.IP \[bu] 2
\f[CR]--depth\f[R] or \f[CR]depth:\f[R] can be used to limit report
depth in the usual way (but will not reveal unbudgeted subaccounts).
.IP \[bu] 2
Amounts are always inclusive of subaccounts (even in
\f[CR]-l/--list\f[R] mode).
.IP \[bu] 2
Numbers displayed in a --budget report will not always agree with the
totals, because of hidden unbudgeted accounts; this is normal.
\f[CR]-E/--empty\f[R] can be used to reveal the hidden accounts.
.IP \[bu] 2
In the periodic rules used for setting budget goals, unbalanced postings
are convenient.
.IP \[bu] 2
You can filter budget reports with the usual queries, eg to focus on
particular accounts.
It\[aq]s common to restrict them to just expenses.
(The \f[CR]<unbudgeted>\f[R] account is occasionally hard to exclude;
this is because of date surprises, discussed below.)
.IP \[bu] 2
When you have multiple currencies, you may want to convert them to one
(\f[CR]-X COMM --infer-market-prices\f[R]) and/or show just one at a
time (\f[CR]cur:COMM\f[R]).
If you do need to show multiple currencies at once,
\f[CR]--layout bare\f[R] can be helpful.
.IP \[bu] 2
You can \[dq]roll over\[dq] amounts (actual and budgeted) to the next
period with \f[CR]--cumulative\f[R].
.PP .PP
This means that the numbers displayed will not always add up! See also: https://hledger.org/budgeting.html.
Eg above, the \f[CR]expenses\f[R] actual amount includes the gifts and .SS Budget date surprises
supplies transactions, but the \f[CR]expenses:gifts\f[R] and With small data, or when starting out, some of the generated budget goal
\f[CR]expenses:supplies\f[R] accounts are not shown, as they have no transaction dates might fall outside the report periods.
budget amounts declared. Eg with the following journal and report, the first period appears to
.PP have no \f[CR]expenses:food\f[R] budget.
This can be confusing. (Also the \f[CR]<unbudgeted>\f[R] account should be excluded by the
When you need to make things clearer, use the \f[CR]-E/--empty\f[R] \f[CR]expenses\f[R] query, but isn\[aq]t.):
flag, which will reveal all accounts including unbudgeted ones, giving
the full picture.
Eg:
.IP
.EX
$ hledger balance -M --budget --empty
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
.EE
.PP
You can roll over unspent budgets to next period with
\f[CR]--cumulative\f[R]:
.IP
.EX
$ hledger balance -M --budget --cumulative
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec
======================++====================================================
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
.EE
.PP
It\[aq]s common to limit budgets/budget reports to just expenses
.IP
.EX
hledger bal -M --budget expenses
.EE
.PP
or just revenues and expenses (eg, using account types):
.IP
.EX
hledger bal -M --budget type:rx
.EE
.PP
It\[aq]s also common to limit or convert them to a single currency
(\f[CR]cur:COMM\f[R] or \f[CR]-X COMM [--infer-market-prices]\f[R]).
If showing multiple currencies, \f[CR]--layout bare\f[R] or
\f[CR]--layout tall\f[R] can help.
.PP
For more examples and notes, see Budgeting.
.SS Budget report start date
This might be a bug, but for now: when making budget reports, it\[aq]s a
good idea to explicitly set the report\[aq]s start date to the first day
of a reporting period, because a periodic rule like
\f[CR]\[ti] monthly\f[R] generates its transactions on the 1st of each
month, and if your journal has no regular transactions on the 1st, the
default report start date could exclude that budget goal, which can be a
little surprising.
Eg here the default report period is just the day of 2020-01-15:
.IP .IP
.EX .EX
\[ti] monthly in 2020 \[ti] monthly in 2020
@ -8593,137 +8568,27 @@ Eg here the default report period is just the day of 2020-01-15:
.EE .EE
.IP .IP
.EX .EX
$ hledger bal expenses --budget $ hledger bal --budget expenses
Budget performance in 2020-01-15: Budget performance in 2020-01-15:
|| 2020-01-15 || 2020-01-15
==============++============ ===============++====================
<unbudgeted> || $400 <unbudgeted> || $400
--------------++------------ expenses:food || 0 [ 0% of $500]
|| $400 ---------------++--------------------
|| $400 [80% of $500]
.EE .EE
.PP .PP
To avoid this, specify the budget report\[aq]s period, or at least the In this case, the budget goal transactions are generated on first days
start date, with of of month (this can be seen with
\f[CR]-b\f[R]/\f[CR]-e\f[R]/\f[CR]-p\f[R]/\f[CR]date:\f[R], to ensure it \f[CR]hledger print --forecast tag:generated expenses\f[R]).
includes the budget goal transactions (periodic transactions) that you Whereas the report period defaults to just the 15th day of january (this
want. can be seen from the report table\[aq]s column headings).
Eg, adding \f[CR]-b 2020/1/1\f[R] to the above:
.IP
.EX
$ hledger bal expenses --budget -b 2020/1/1
Budget performance in 2020-01-01..2020-01-15:
|| 2020-01-01..2020-01-15
===============++========================
expenses:food || $400 [80% of $500]
---------------++------------------------
|| $400 [80% of $500]
.EE
.SS Budgets and subaccounts
You can add budgets to any account in your account hierarchy.
If you have budgets on both parent account and some of its children,
then budget(s) of the child account(s) would be added to the budget of
their parent, much like account balances behave.
.PP .PP
In the most simple case this means that once you add a budget to any To fix this kind of thing, be more explicit about the report period
account, all its parents would have budget as well. (and/or the periodic rules\[aq] dates).
.PP In this case, adding \f[CR]-b 2020\f[R] does the trick.
To illustrate this, consider the following budget:
.IP
.EX
\[ti] monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
.EE
.PP
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicitly
means that budget for both \f[CR]expenses:personal\f[R] and
\f[CR]expenses\f[R] is $1100.
.PP
Transactions in \f[CR]expenses:personal:electronics\f[R] will be counted
both towards its $100 budget and $1100 of \f[CR]expenses:personal\f[R] ,
and transactions in any other subaccount of \f[CR]expenses:personal\f[R]
would be counted towards only towards the budget of
\f[CR]expenses:personal\f[R].
.PP
For example, let\[aq]s consider these transactions:
.IP
.EX
\[ti] monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
.EE
.PP
As you can see, we have transactions in
\f[CR]expenses:personal:electronics:upgrades\f[R] and
\f[CR]expenses:personal:train tickets\f[R], and since both of these
accounts are without explicitly defined budget, these transactions would
be counted towards budgets of \f[CR]expenses:personal:electronics\f[R]
and \f[CR]expenses:personal\f[R] accordingly:
.IP
.EX
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
.EE
.PP
And with \f[CR]--empty\f[R], we can get a better picture of budget
allocation and consumption:
.IP
.EX
$ hledger balance --budget -M --empty
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 0 [ 0]
.EE
.SS Selecting budget goals .SS Selecting budget goals
The budget report evaluates periodic transaction rules to generate
special \[dq]goal transactions\[dq], which generate the goal amounts for
each account in each report subperiod.
When troubleshooting, you can use \f[CR]print --forecast\f[R] to show
these as forecasted transactions:
.IP
.EX
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
.EE
.PP
By default, the budget report uses all available periodic transaction By default, the budget report uses all available periodic transaction
rules to generate goals. rules to generate goals.
This includes rules with a different report interval from your report. This includes rules with a different report interval from your report.
@ -8736,63 +8601,50 @@ the \f[CR]--budget\f[R] flag.
description contains DESCPAT, a case-insensitive substring (not a description contains DESCPAT, a case-insensitive substring (not a
regular expression or query). regular expression or query).
This means you can give your periodic rules descriptions (remember that This means you can give your periodic rules descriptions (remember that
two spaces are needed), and then select from multiple budgets defined in two spaces are needed between period expression and description), and
your journal. then select from multiple budgets defined in your journal.
.SS Budget vs forecast .SS Budgeting vs forecasting
\f[CR]hledger --forecast ...\f[R] and \f[CR]--budget\f[R] and \f[CR]--forecast\f[R] both use the periodic
\f[CR]hledger balance --budget ...\f[R] are separate features, though transaction rules in the journal to generate temporary transactions for
both of them use the periodic transaction rules defined in the journal, reporting purposes.
and both of them generate temporary transactions for reporting purposes However they are separate features - though you can use both at the same
(\[dq]forecast transactions\[dq] and \[dq]budget goal transactions\[dq], time if you want.
respectively). Here are some differences between them:
You can use both features at the same time if you want. .IP "1." 3
Here are some differences between them, as of hledger 1.29: \f[CR]--budget\f[R] is a command-specific option; it selects the
\f[B]budget report\f[R].
.RS 4
.PP .PP
CLI: \f[CR]--forecast\f[R] is a general option; \f[B]forecasting works with
.IP \[bu] 2 all reports\f[R].
--forecast is a general hledger option, usable with any command
.IP \[bu] 2
--budget is a \f[CR]balance\f[R] command option, usable only with that
command.
.PP
Visibility of generated transactions:
.IP \[bu] 2
forecast transactions are visible in any report, like ordinary
transactions
.IP \[bu] 2
budget goal transactions are invisible except for the goal amounts they
produce in --budget reports.
.PP
Periodic transaction rules:
.IP \[bu] 2
--forecast uses all available periodic transaction rules
.IP \[bu] 2
--budget uses all periodic rules (\f[CR]--budget\f[R]) or a selected
subset (\f[CR]--budget=DESCPAT\f[R])
.PP
Period of generated transactions:
.IP \[bu] 2
--forecast generates forecast transactions
.RS 2
.IP \[bu] 2
from after the last regular transaction to the end of the report period
(\f[CR]--forecast\f[R])
.IP \[bu] 2
or, during a specified period (\f[CR]--forecast=PERIODEXPR\f[R])
.IP \[bu] 2
possibly further restricted by a period specified in the periodic
transaction rule
.IP \[bu] 2
and always restricted within the bounds of the report period
.RE .RE
.IP \[bu] 2 .IP "2." 3
--budget generates budget goal transactions \f[CR]--budget\f[R] uses \f[B]all periodic rules\f[R];
.RS 2 \f[CR]--budget=DESCPAT\f[R] uses \f[B]just the rules matched\f[R] by
.IP \[bu] 2 DESCPAT.
throughout the report period .RS 4
.IP \[bu] 2 .PP
possibly restricted by a period specified in the periodic transaction \f[CR]--forecast\f[R] uses \f[B]all periodic rules\f[R].
rule. .RE
.IP "3." 3
\f[CR]--budget\f[R]\[aq]s budget goal transactions are invisible, except
that they produce \f[B]goal amounts\f[R].
.RS 4
.PP
\f[CR]--forecast\f[R]\[aq]s forecast transactions are visible, and
\f[B]appear in reports\f[R].
.RE
.IP "4." 3
\f[CR]--budget\f[R] generates budget goal transactions \f[B]throughout
the report period\f[R], optionally restricted by periods specified in
the periodic transaction rules.
.RS 4
.PP
\f[CR]--forecast\f[R] generates forecast transactions from \f[B]after
the last regular transaction\f[R], to the end of the report period;
while \f[CR]--forecast=PERIODEXPR\f[R] generates them \f[B]throughout
the specified period\f[R]; both optionally restricted by periods
specified in the periodic transaction rules.
.RE .RE
.SS Balance report layout .SS Balance report layout
The \f[CR]--layout\f[R] option affects how balance reports show The \f[CR]--layout\f[R] option affects how balance reports show

1509
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

391
hledger/hledger.txt
View File

@ -1512,18 +1512,18 @@ Journal
a:usd 0 == $1 a:usd 0 == $1
a:euro 0 == 1 a:euro 0 == 1
Assertions and prices Assertions and costs
Balance assertions ignore costs, and should normally be written without Balance assertions ignore costs, and should normally be written without
one: one:
2019/1/1 2019/1/1
(a) $1 @ 1 = $1 (a) $1 @ 1 = $1
We do allow prices to be written there, however, and print shows them, We do allow costs to be written in balance assertion amounts, however,
even though they don't affect whether the assertion passes or fails. and print shows them, but they don't affect whether the assertion
This is for backward compatibility (hledger's close command used to passes or fails. This is for backward compatibility (hledger's close
generate balance assertions with prices), and because balance assign- command used to generate balance assertions with costs), and because
ments do use them (see below). balance assignments do use costs (see below).
Assertions and subaccounts Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from The balance assertions above (= and ==) do not count the balance from
@ -6565,140 +6565,120 @@ PART 4: COMMANDS
ance) end end ance) end end
Budget report Budget report
The --budget report type activates extra columns showing any budget The --budget report type is like a regular balance report, but with two
goals for each account and period. The budget goals are defined by pe- main differences:
riodic transactions. This is useful for comparing planned and actual
income, expenses, time usage, etc.
For example, you can take average monthly expenses in the common ex- o Budget goals and performance percentages are also shown, in brackets
pense categories to construct a minimal monthly budget:
o Accounts which don't have budget goals are hidden by default.
This is useful for comparing planned and actual income, expenses, time
usage, etc.
Periodic transaction rules are used to define budget goals. For exam-
ple, here's a periodic rule defining monthly goals for bus travel and
food expenses:
;; Budget ;; Budget
~ monthly ~ monthly
income $2000 (expenses:bus) $30
expenses:food $400 (expenses:food) $400
expenses:bus $50
expenses:movies $30 After recording some actual expenses,
assets:bank:checking
;; Two months worth of expenses ;; Two months worth of expenses
2017-11-01 2017-11-01
income $1950 income $-1950
expenses:food $396 expenses:bus $35
expenses:bus $49 expenses:food:groceries $310
expenses:movies $30 expenses:food:dining $42
expenses:supplies $20 expenses:movies $38
assets:bank:checking assets:bank:checking
2017-12-01 2017-12-01
income $2100 income $-2100
expenses:food $412 expenses:bus $53
expenses:bus $53 expenses:food:groceries $380
expenses:gifts $100 expenses:food:dining $32
expenses:gifts $100
assets:bank:checking assets:bank:checking
You can now see a monthly budget report: we can see a budget report like this:
$ hledger balance -M --budget $ hledger bal -M --budget
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017-11-01..2017-12-31:
|| Nov Dec || Nov Dec
======================++==================================================== ===============++============================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] <unbudgeted> || $-425 $-565
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] expenses || $425 [ 99% of $430] $565 [131% of $430]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] expenses:bus || $35 [117% of $30] $53 [177% of $30]
expenses || $495 [ 103% of $480] $565 [ 118% of $480] expenses:food || $352 [ 88% of $400] $412 [103% of $400]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] ---------------++--------------------------------------------
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] || 0 [ 0% of $430] 0 [ 0% of $430]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
This is different from a normal balance report in several ways. Cur- This is "goal-based budgeting"; you define goals for accounts and peri-
rently: ods, often recurring, and hledger shows performance relative to the
goals. This contrasts with "envelope budgeting", which is more de-
tailed and strict - useful when cash is tight, but also quite a bit
more work. https://plaintextaccounting.org/Budgeting has more on this
topic.
o Accounts with budget goals during the report period, and their par- Using the budget report
ents, are shown. Historically this report has been confusing and fragile. hledger's
version should be relatively robust and intuitive, but you may still
find surprises. Here are more notes to help with learning and trou-
bleshooting.
o Their subaccounts are not shown (regardless of the depth setting). o In the above example, expenses:bus and expenses:food are shown be-
cause they have budget goals during the report period.
o Accounts without budget goals, if any, are aggregated and shown as o Their parent expenses is also shown, with budget goals aggregated
"<unbudgeted>". from the children.
o Amounts are always inclusive (subaccount-including), even in list o The subaccounts expenses:food:groceries and expenses:food:dining are
mode. not shown since they have no budget goal of their own, but they con-
tribute to expenses:food's actual amount.
o After each actual amount, the corresponding goal amount and percent- o Unbudgeted accounts expenses:movies and expenses:gifts are also not
age of goal reached are also shown, in square brackets. shown, but they contribute to expenses's actual amount.
This means that the numbers displayed will not always add up! Eg o The other unbudgeted accounts income and assets:bank:checking are
above, the expenses actual amount includes the gifts and supplies grouped as <unbudgeted>.
transactions, but the expenses:gifts and expenses:supplies accounts are
not shown, as they have no budget amounts declared.
This can be confusing. When you need to make things clearer, use the o --depth or depth: can be used to limit report depth in the usual way
-E/--empty flag, which will reveal all accounts including unbudgeted (but will not reveal unbudgeted subaccounts).
ones, giving the full picture. Eg:
$ hledger balance -M --budget --empty o Amounts are always inclusive of subaccounts (even in -l/--list mode).
Budget performance in 2017/11/01-2017/12/31:
|| Nov Dec o Numbers displayed in a --budget report will not always agree with the
======================++==================================================== totals, because of hidden unbudgeted accounts; this is normal.
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] -E/--empty can be used to reveal the hidden accounts.
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
You can roll over unspent budgets to next period with --cumulative: o In the periodic rules used for setting budget goals, unbalanced post-
ings are convenient.
$ hledger balance -M --budget --cumulative o You can filter budget reports with the usual queries, eg to focus on
Budget performance in 2017/11/01-2017/12/31: particular accounts. It's common to restrict them to just expenses.
(The <unbudgeted> account is occasionally hard to exclude; this is
because of date surprises, discussed below.)
|| Nov Dec o When you have multiple currencies, you may want to convert them to
======================++==================================================== one (-X COMM --infer-market-prices) and/or show just one at a time
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] (cur:COMM). If you do need to show multiple currencies at once,
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] --layout bare can be helpful.
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
It's common to limit budgets/budget reports to just expenses o You can "roll over" amounts (actual and budgeted) to the next period
with --cumulative.
hledger bal -M --budget expenses See also: https://hledger.org/budgeting.html.
or just revenues and expenses (eg, using account types): Budget date surprises
With small data, or when starting out, some of the generated budget
hledger bal -M --budget type:rx goal transaction dates might fall outside the report periods. Eg with
the following journal and report, the first period appears to have no
It's also common to limit or convert them to a single currency expenses:food budget. (Also the <unbudgeted> account should be ex-
(cur:COMM or -X COMM [--infer-market-prices]). If showing multiple cluded by the expenses query, but isn't.):
currencies, --layout bare or --layout tall can help.
For more examples and notes, see Budgeting.
Budget report start date
This might be a bug, but for now: when making budget reports, it's a
good idea to explicitly set the report's start date to the first day of
a reporting period, because a periodic rule like ~ monthly generates
its transactions on the 1st of each month, and if your journal has no
regular transactions on the 1st, the default report start date could
exclude that budget goal, which can be a little surprising. Eg here
the default report period is just the day of 2020-01-15:
~ monthly in 2020 ~ monthly in 2020
(expenses:food) $500 (expenses:food) $500
@ -6707,120 +6687,27 @@ PART 4: COMMANDS
expenses:food $400 expenses:food $400
assets:checking assets:checking
$ hledger bal expenses --budget $ hledger bal --budget expenses
Budget performance in 2020-01-15: Budget performance in 2020-01-15:
|| 2020-01-15 || 2020-01-15
==============++============ ===============++====================
<unbudgeted> || $400 <unbudgeted> || $400
--------------++------------ expenses:food || 0 [ 0% of $500]
|| $400 ---------------++--------------------
|| $400 [80% of $500]
To avoid this, specify the budget report's period, or at least the In this case, the budget goal transactions are generated on first days
start date, with -b/-e/-p/date:, to ensure it includes the budget goal of of month (this can be seen with hledger print --forecast tag:gener-
transactions (periodic transactions) that you want. Eg, adding -b ated expenses). Whereas the report period defaults to just the 15th
2020/1/1 to the above: day of january (this can be seen from the report table's column head-
ings).
$ hledger bal expenses --budget -b 2020/1/1 To fix this kind of thing, be more explicit about the report period
Budget performance in 2020-01-01..2020-01-15: (and/or the periodic rules' dates). In this case, adding -b 2020 does
the trick.
|| 2020-01-01..2020-01-15
===============++========================
expenses:food || $400 [80% of $500]
---------------++------------------------
|| $400 [80% of $500]
Budgets and subaccounts
You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then bud-
get(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicitly
means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both to-
wards its $100 budget and $1100 of expenses:personal , and transactions
in any other subaccount of expenses:personal would be counted towards
only towards the budget of expenses:personal.
For example, let's consider these transactions:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
As you can see, we have transactions in expenses:personal:electron-
ics:upgrades and expenses:personal:train tickets, and since both of
these accounts are without explicitly defined budget, these transac-
tions would be counted towards budgets of expenses:personal:electronics
and expenses:personal accordingly:
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
And with --empty, we can get a better picture of budget allocation and
consumption:
$ hledger balance --budget -M --empty
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 0 [ 0]
Selecting budget goals Selecting budget goals
The budget report evaluates periodic transaction rules to generate spe-
cial "goal transactions", which generate the goal amounts for each ac-
count in each report subperiod. When troubleshooting, you can use
print --forecast to show these as forecasted transactions:
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
By default, the budget report uses all available periodic transaction By default, the budget report uses all available periodic transaction
rules to generate goals. This includes rules with a different report rules to generate goals. This includes rules with a different report
interval from your report. Eg if you have daily, weekly and monthly interval from your report. Eg if you have daily, weekly and monthly
@ -6831,58 +6718,40 @@ PART 4: COMMANDS
the --budget flag. --budget=DESCPAT will match all periodic rules the --budget flag. --budget=DESCPAT will match all periodic rules
whose description contains DESCPAT, a case-insensitive substring (not a whose description contains DESCPAT, a case-insensitive substring (not a
regular expression or query). This means you can give your periodic regular expression or query). This means you can give your periodic
rules descriptions (remember that two spaces are needed), and then se- rules descriptions (remember that two spaces are needed between period
lect from multiple budgets defined in your journal. expression and description), and then select from multiple budgets de-
fined in your journal.
Budget vs forecast Budgeting vs forecasting
hledger --forecast ... and hledger balance --budget ... are separate --budget and --forecast both use the periodic transaction rules in the
features, though both of them use the periodic transaction rules de- journal to generate temporary transactions for reporting purposes.
fined in the journal, and both of them generate temporary transactions However they are separate features - though you can use both at the
for reporting purposes ("forecast transactions" and "budget goal trans- same time if you want. Here are some differences between them:
actions", respectively). You can use both features at the same time if
you want. Here are some differences between them, as of hledger 1.29:
CLI: 1. --budget is a command-specific option; it selects the budget report.
o --forecast is a general hledger option, usable with any command --forecast is a general option; forecasting works with all reports.
o --budget is a balance command option, usable only with that command. 2. --budget uses all periodic rules; --budget=DESCPAT uses just the
rules matched by DESCPAT.
Visibility of generated transactions: --forecast uses all periodic rules.
o forecast transactions are visible in any report, like ordinary trans- 3. --budget's budget goal transactions are invisible, except that they
actions produce goal amounts.
o budget goal transactions are invisible except for the goal amounts --forecast's forecast transactions are visible, and appear in re-
they produce in --budget reports. ports.
Periodic transaction rules: 4. --budget generates budget goal transactions throughout the report
period, optionally restricted by periods specified in the periodic
transaction rules.
o --forecast uses all available periodic transaction rules --forecast generates forecast transactions from after the last reg-
ular transaction, to the end of the report period; while --fore-
o --budget uses all periodic rules (--budget) or a selected subset cast=PERIODEXPR generates them throughout the specified period;
(--budget=DESCPAT) both optionally restricted by periods specified in the periodic
transaction rules.
Period of generated transactions:
o --forecast generates forecast transactions
o from after the last regular transaction to the end of the report
period (--forecast)
o or, during a specified period (--forecast=PERIODEXPR)
o possibly further restricted by a period specified in the periodic
transaction rule
o and always restricted within the bounds of the report period
o --budget generates budget goal transactions
o throughout the report period
o possibly restricted by a period specified in the periodic transac-
tion rule.
Balance report layout Balance report layout
The --layout option affects how balance reports show multi-commodity The --layout option affects how balance reports show multi-commodity