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
to stdout.
.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:
.TP
\f[CR]--serve\f[R]
serve and log requests, don\[aq]t browse or auto-exit after timeout
.TP
\f[CR]--serve-api\f[R]
like --serve, but serve only the JSON web API, without the server-side
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.
like --serve, but serve only the JSON web API, not the web UI
.TP
\f[CR]--allow=view|add|edit\f[R]
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
permissions from the \f[CR]X-Sandstorm-Permissions\f[R] request header).
.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]
run hledger-web\[aq]s tests and exit.
hspec test runner args may follow a --, eg: hledger-web --test -- --help
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[CR]--host\f[R] to change this, eg
\f[CR]--host 0.0.0.0\f[R] to listen on all configured addresses.
.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):
hledger-web also supports many of hledger\[aq]s general options.
Query options and arguments may be used to set an initial filter, which
although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
.SS General help options
.TP
\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
*********
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 and log requests, don't browse or auto-exit after timeout
'--serve-api'
like -serve, but serve only the JSON web API, without the
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.
like -serve, but serve only the JSON web API, not the web UI
'--allow=view|add|edit'
set the user's access level for changing data (default: 'add'). It
also accepts 'sandstorm' for use on that platform (reads
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'
run hledger-web's tests and exit. hspec test runner args may
follow a -, eg: hledger-web -test - -help
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):
hledger-web also supports many of hledger's general options. Query
options and arguments may be used to set an initial filter, which
although not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
* Menu:
@ -645,28 +634,28 @@ Tag Table:
Node: Top225
Node: OPTIONS2580
Ref: #options2685
Node: General help options5973
Ref: #general-help-options6123
Node: General input options6405
Ref: #general-input-options6591
Node: General reporting options7293
Ref: #general-reporting-options7458
Node: PERMISSIONS10848
Ref: #permissions10987
Node: EDITING UPLOADING DOWNLOADING12199
Ref: #editing-uploading-downloading12380
Node: RELOADING13214
Ref: #reloading13348
Node: JSON API13781
Ref: #json-api13896
Node: DEBUG OUTPUT19384
Ref: #debug-output19509
Node: Debug output19536
Ref: #debug-output-119637
Node: ENVIRONMENT20054
Ref: #environment20173
Node: BUGS20290
Ref: #bugs20374
Node: General help options5259
Ref: #general-help-options5409
Node: General input options5691
Ref: #general-input-options5877
Node: General reporting options6579
Ref: #general-reporting-options6744
Node: PERMISSIONS10134
Ref: #permissions10273
Node: EDITING UPLOADING DOWNLOADING11485
Ref: #editing-uploading-downloading11666
Node: RELOADING12500
Ref: #reloading12634
Node: JSON API13067
Ref: #json-api13182
Node: DEBUG OUTPUT18670
Ref: #debug-output18795
Node: Debug output18822
Ref: #debug-output-118923
Node: ENVIRONMENT19340
Ref: #environment19459
Node: BUGS19576
Ref: #bugs19660

End Tag Table

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

@ -52,79 +52,66 @@ DESCRIPTION
to stdout.
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:
--serve
serve and log requests, don't browse or auto-exit after timeout
--serve-api
like --serve, but serve only the JSON web API, without the
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.
like --serve, but serve only the JSON web API, not the web UI
--allow=view|add|edit
set the user's access level for changing data (default: add).
It also accepts sandstorm for use on that platform (reads per-
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
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):
hledger-web also supports many of hledger's general options. Query op-
tions and arguments may be used to set an initial filter, which al-
though not shown in the UI, will restrict the data shown, in addition
to any search query entered in the UI.
General help options
-h --help
@ -146,7 +133,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE
Conversion rules file to use when reading CSV (default:
Conversion rules file to use when reading CSV (default:
FILE.rules)
--separator=CHAR
@ -165,7 +152,7 @@ OPTIONS
assignments)
-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)
General reporting options
@ -193,7 +180,7 @@ OPTIONS
multiperiod/multicolumn report by year
-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
--date2
@ -201,7 +188,7 @@ OPTIONS
fects)
--today=DATE
override today's date (affects relative smart dates, for
override today's date (affects relative smart dates, for
tests/examples)
-U --unmarked
@ -220,21 +207,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep
-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)
-B --cost
convert amounts to their cost/selling amount at transaction time
-V --market
convert amounts to their market value in default valuation com-
convert amounts to their market value in default valuation com-
modities
-X --exchange=COMM
convert amounts to their market value in commodity COMM
--value
convert amounts to cost or market value, more flexibly than
convert amounts to cost or market value, more flexibly than
-B/-V/-X
--infer-equity
@ -244,38 +231,38 @@ OPTIONS
infer costs from conversion equity postings
--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
--forecast
generate transactions from periodic rules, between the latest
recorded txn and 6 months from today, or during the specified
PERIOD (= is required). Auto posting rules will be applied to
these transactions as well. Also, in hledger-ui make future-
generate transactions from periodic rules, between the latest
recorded txn and 6 months from today, or during the specified
PERIOD (= is required). Auto posting rules will be applied to
these transactions as well. Also, in hledger-ui make future-
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)
--verbose-tags
add visible tags indicating transactions or postings which have
add visible tags indicating transactions or postings which have
been generated/modified
--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'.
--color=WHEN (or --colour=WHEN)
Should color-supporting commands use ANSI color codes in text
output. 'auto' (default): whenever stdout seems to be a color-
supporting terminal. 'always' or 'yes': always, useful eg when
piping output into 'less -R'. 'never' or 'no': never. A
Should color-supporting commands use ANSI color codes in text
output. 'auto' (default): whenever stdout seems to be a color-
supporting terminal. 'always' or 'yes': always, useful eg when
piping output into 'less -R'. 'never' or 'no': never. A
NO_COLOR environment variable overrides this.
--pretty[=WHEN]
Show prettier output, e.g. using unicode box-drawing charac-
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
'never' also work). If you provide an argument you must use
Show prettier output, e.g. using unicode box-drawing charac-
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
'never' also work). If you provide an argument you must use
'=', e.g. '--pretty=yes'.
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.
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.
You can restrict who can reach it by
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-
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-
chine.
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
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:
o view - allows viewing the journal file and all included files
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
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
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
let you edit, upload, or download the journal file or any files it in-
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
let you edit, upload, or download the journal file or any files it in-
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.
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
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
Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not
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
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
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
data when you reload the page or navigate to a new page. If a change
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
makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed.
@ -345,8 +332,8 @@ RELOADING
that both machine clocks are roughly in step.)
JSON API
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
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
only, you can use the --serve-api flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api
@ -363,7 +350,7 @@ JSON API
/accounttransactions/ACCOUNTNAME
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):
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
@ -404,25 +391,25 @@ JSON API
"aprice": null,
...
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
on the various data types, eg Transaction. And for a higher level un-
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
on the various data types, eg Transaction. And for a higher level un-
derstanding, see the journal docs.
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
at the source for the appropriate handler to see what it returns. Eg
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
for /accounttransactions it's getAccounttransactionsR, returning a "ac-
countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe-
countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe-
portItem (etc).
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
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
default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can
hledger transaction (partial data won't do). You can get sample JSON
from hledger-web's /transactions or /accounttransactions, or you can
export it with hledger-lib, eg like so:
.../hledger$ stack ghci hledger-lib
@ -518,28 +505,28 @@ JSON API
"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:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
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-
cally you would start with 1 and increase until you are seeing enough.
Debug output goes to stderr, interleaved with the requests logged on
cally you would start with 1 and increase until you are seeing enough.
Debug output goes to stderr, interleaved with the requests logged on
stdout. To capture debug output in a log file instead, you can usually
redirect stderr, eg:
hledger-web --debug=3 2>hledger-web.log.
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.
BUGS
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).
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:euro 0 == 1€
.EE
.SS Assertions and prices
.SS Assertions and costs
Balance assertions ignore costs, and should normally be written without
one:
.IP
@ -1947,11 +1947,12 @@ one:
(a) $1 \[at] €1 = $1
.EE
.PP
We do allow prices to be written there, however, and print shows them,
even though they don\[aq]t affect whether the assertion passes or fails.
We do allow costs to be written in balance assertion amounts, however,
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
generate balance assertions with prices), and because balance
\f[I]assignments\f[R] do use them (see below).
generate balance assertions with costs), and because balance
\f[I]assignments\f[R] do use costs (see below).
.SS Assertions and subaccounts
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
@ -8431,157 +8432,131 @@ DATE-value of change from journal start to period end
T}
.TE
.SS Budget report
The \f[CR]--budget\f[R] report type activates extra columns showing any
budget goals for each account and period.
The budget goals are defined by periodic transactions.
The \f[CR]--budget\f[R] report type is like a regular balance report,
but with two main differences:
.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
usage, etc.
.PP
For example, you can take average monthly expenses in the common expense
categories to construct a minimal monthly budget:
Periodic transaction rules are used to define budget goals.
For example, here\[aq]s a periodic rule defining monthly goals for bus
travel and food expenses:
.IP
.EX
;; Budget
\[ti] monthly
income $2000
expenses:food $400
expenses:bus $50
expenses:movies $30
assets:bank:checking
(expenses:bus) $30
(expenses:food) $400
.EE
.PP
After recording some actual expenses,
.IP
.EX
;; Two months worth of expenses
2017-11-01
income $1950
expenses:food $396
expenses:bus $49
expenses:movies $30
expenses:supplies $20
income $-1950
expenses:bus $35
expenses:food:groceries $310
expenses:food:dining $42
expenses:movies $38
assets:bank:checking
2017-12-01
income $2100
expenses:food $412
expenses:bus $53
expenses:gifts $100
income $-2100
expenses:bus $53
expenses:food:groceries $380
expenses:food:dining $32
expenses:gifts $100
assets:bank:checking
.EE
.PP
You can now see a monthly budget report:
we can see a budget report like this:
.IP
.EX
$ hledger balance -M --budget
Budget performance in 2017/11/01-2017/12/31:
$ hledger bal -M --budget
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:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
|| Nov Dec
===============++============================================
<unbudgeted> || $-425 $-565
expenses || $425 [ 99% of $430] $565 [131% of $430]
expenses:bus || $35 [117% of $30] $53 [177% of $30]
expenses:food || $352 [ 88% of $400] $412 [103% of $400]
---------------++--------------------------------------------
|| 0 [ 0% of $430] 0 [ 0% of $430]
.EE
.PP
This is different from a normal balance report in several ways.
Currently:
This is \[dq]goal-based budgeting\[dq]; you define goals for accounts
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
Accounts with budget goals during the report period, and their parents,
are shown.
In the above example, \f[CR]expenses:bus\f[R] and
\f[CR]expenses:food\f[R] are shown because they have budget goals during
the report period.
.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
Accounts without budget goals, if any, are aggregated and shown as
\[dq]<unbudgeted>\[dq].
The subaccounts \f[CR]expenses:food:groceries\f[R] and
\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
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
After each actual amount, the corresponding goal amount and percentage
of goal reached are also shown, in square brackets.
The other unbudgeted accounts \f[CR]income\f[R] and
\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
This means that the numbers displayed will not always add up!
Eg above, the \f[CR]expenses\f[R] actual amount includes the gifts and
supplies transactions, but the \f[CR]expenses:gifts\f[R] and
\f[CR]expenses:supplies\f[R] accounts are not shown, as they have no
budget amounts declared.
.PP
This can be confusing.
When you need to make things clearer, use the \f[CR]-E/--empty\f[R]
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:
See also: https://hledger.org/budgeting.html.
.SS Budget date surprises
With small data, or when starting out, some of the generated budget goal
transaction dates might fall outside the report periods.
Eg with the following journal and report, the first period appears to
have no \f[CR]expenses:food\f[R] budget.
(Also the \f[CR]<unbudgeted>\f[R] account should be excluded by the
\f[CR]expenses\f[R] query, but isn\[aq]t.):
.IP
.EX
\[ti] monthly in 2020
@ -8593,137 +8568,27 @@ Eg here the default report period is just the day of 2020-01-15:
.EE
.IP
.EX
$ hledger bal expenses --budget
$ hledger bal --budget expenses
Budget performance in 2020-01-15:
|| 2020-01-15
==============++============
<unbudgeted> || $400
--------------++------------
|| $400
|| 2020-01-15
===============++====================
<unbudgeted> || $400
expenses:food || 0 [ 0% of $500]
---------------++--------------------
|| $400 [80% of $500]
.EE
.PP
To avoid this, specify the budget report\[aq]s period, or at least the
start date, with
\f[CR]-b\f[R]/\f[CR]-e\f[R]/\f[CR]-p\f[R]/\f[CR]date:\f[R], to ensure it
includes the budget goal transactions (periodic transactions) that you
want.
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.
In this case, the budget goal transactions are generated on first days
of of month (this can be seen with
\f[CR]hledger print --forecast tag:generated expenses\f[R]).
Whereas the report period defaults to just the 15th day of january (this
can be seen from the report table\[aq]s column headings).
.PP
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
.PP
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
To fix this kind of thing, be more explicit about the report period
(and/or the periodic rules\[aq] dates).
In this case, adding \f[CR]-b 2020\f[R] does the trick.
.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
rules to generate goals.
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
regular expression or query).
This means you can give your periodic rules descriptions (remember that
two spaces are needed), and then select from multiple budgets defined in
your journal.
.SS Budget vs forecast
\f[CR]hledger --forecast ...\f[R] and
\f[CR]hledger balance --budget ...\f[R] are separate features, though
both of them use the periodic transaction rules defined in the journal,
and both of them generate temporary transactions for reporting purposes
(\[dq]forecast transactions\[dq] and \[dq]budget goal transactions\[dq],
respectively).
You can use both features at the same time if you want.
Here are some differences between them, as of hledger 1.29:
two spaces are needed between period expression and description), and
then select from multiple budgets defined in your journal.
.SS Budgeting vs forecasting
\f[CR]--budget\f[R] and \f[CR]--forecast\f[R] both use the periodic
transaction rules in the journal to generate temporary transactions for
reporting purposes.
However they are separate features - though you can use both at the same
time if you want.
Here are some differences between them:
.IP "1." 3
\f[CR]--budget\f[R] is a command-specific option; it selects the
\f[B]budget report\f[R].
.RS 4
.PP
CLI:
.IP \[bu] 2
--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
\f[CR]--forecast\f[R] is a general option; \f[B]forecasting works with
all reports\f[R].
.RE
.IP \[bu] 2
--budget generates budget goal transactions
.RS 2
.IP \[bu] 2
throughout the report period
.IP \[bu] 2
possibly restricted by a period specified in the periodic transaction
rule.
.IP "2." 3
\f[CR]--budget\f[R] uses \f[B]all periodic rules\f[R];
\f[CR]--budget=DESCPAT\f[R] uses \f[B]just the rules matched\f[R] by
DESCPAT.
.RS 4
.PP
\f[CR]--forecast\f[R] uses \f[B]all periodic rules\f[R].
.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
.SS Balance report layout
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:euro 0 == 1
Assertions and prices
Assertions and costs
Balance assertions ignore costs, and should normally be written without
one:
2019/1/1
(a) $1 @ 1 = $1
We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
ments do use them (see below).
We do allow costs to be written in balance assertion amounts, however,
and print shows them, but they don't affect whether the assertion
passes or fails. This is for backward compatibility (hledger's close
command used to generate balance assertions with costs), and because
balance assignments do use costs (see below).
Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from
@ -6565,140 +6565,120 @@ PART 4: COMMANDS
ance) end end
Budget report
The --budget report type activates extra columns showing any budget
goals for each account and period. The budget goals are defined by pe-
riodic transactions. This is useful for comparing planned and actual
income, expenses, time usage, etc.
The --budget report type is like a regular balance report, but with two
main differences:
For example, you can take average monthly expenses in the common ex-
pense categories to construct a minimal monthly budget:
o Budget goals and performance percentages are also shown, in brackets
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
~ monthly
income $2000
expenses:food $400
expenses:bus $50
expenses:movies $30
assets:bank:checking
(expenses:bus) $30
(expenses:food) $400
After recording some actual expenses,
;; Two months worth of expenses
2017-11-01
income $1950
expenses:food $396
expenses:bus $49
expenses:movies $30
expenses:supplies $20
income $-1950
expenses:bus $35
expenses:food:groceries $310
expenses:food:dining $42
expenses:movies $38
assets:bank:checking
2017-12-01
income $2100
expenses:food $412
expenses:bus $53
expenses:gifts $100
income $-2100
expenses:bus $53
expenses:food:groceries $380
expenses:food:dining $32
expenses:gifts $100
assets:bank:checking
You can now see a monthly budget report:
we can see a budget report like this:
$ hledger balance -M --budget
Budget performance in 2017/11/01-2017/12/31:
$ hledger bal -M --budget
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:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
|| Nov Dec
===============++============================================
<unbudgeted> || $-425 $-565
expenses || $425 [ 99% of $430] $565 [131% of $430]
expenses:bus || $35 [117% of $30] $53 [177% of $30]
expenses:food || $352 [ 88% of $400] $412 [103% of $400]
---------------++--------------------------------------------
|| 0 [ 0% of $430] 0 [ 0% of $430]
This is different from a normal balance report in several ways. Cur-
rently:
This is "goal-based budgeting"; you define goals for accounts and peri-
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-
ents, are shown.
Using the budget report
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
"<unbudgeted>".
o Their parent expenses is also shown, with budget goals aggregated
from the children.
o Amounts are always inclusive (subaccount-including), even in list
mode.
o The subaccounts expenses:food:groceries and expenses:food:dining are
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-
age of goal reached are also shown, in square brackets.
o Unbudgeted accounts expenses:movies and expenses:gifts are also not
shown, but they contribute to expenses's actual amount.
This means that the numbers displayed will not always add up! Eg
above, the expenses actual amount includes the gifts and supplies
transactions, but the expenses:gifts and expenses:supplies accounts are
not shown, as they have no budget amounts declared.
o The other unbudgeted accounts income and assets:bank:checking are
grouped as <unbudgeted>.
This can be confusing. When you need to make things clearer, use the
-E/--empty flag, which will reveal all accounts including unbudgeted
ones, giving the full picture. Eg:
o --depth or depth: can be used to limit report depth in the usual way
(but will not reveal unbudgeted subaccounts).
$ hledger balance -M --budget --empty
Budget performance in 2017/11/01-2017/12/31:
o Amounts are always inclusive of subaccounts (even in -l/--list mode).
|| 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]
o Numbers displayed in a --budget report will not always agree with the
totals, because of hidden unbudgeted accounts; this is normal.
-E/--empty can be used to reveal the hidden accounts.
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
Budget performance in 2017/11/01-2017/12/31:
o You can filter budget reports with the usual queries, eg to focus on
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
======================++====================================================
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]
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
(cur:COMM). If you do need to show multiple currencies at once,
--layout bare can be helpful.
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):
hledger bal -M --budget type:rx
It's also common to limit or convert them to a single currency
(cur:COMM or -X COMM [--infer-market-prices]). If showing multiple
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:
Budget date surprises
With small data, or when starting out, some of the generated budget
goal transaction dates might fall outside the report periods. Eg with
the following journal and report, the first period appears to have no
expenses:food budget. (Also the <unbudgeted> account should be ex-
cluded by the expenses query, but isn't.):
~ monthly in 2020
(expenses:food) $500
@ -6707,120 +6687,27 @@ PART 4: COMMANDS
expenses:food $400
assets:checking
$ hledger bal expenses --budget
$ hledger bal --budget expenses
Budget performance in 2020-01-15:
|| 2020-01-15
==============++============
<unbudgeted> || $400
--------------++------------
|| $400
|| 2020-01-15
===============++====================
<unbudgeted> || $400
expenses:food || 0 [ 0% of $500]
---------------++--------------------
|| $400 [80% of $500]
To avoid this, specify the budget report's period, or at least the
start date, with -b/-e/-p/date:, to ensure it includes the budget goal
transactions (periodic transactions) that you want. Eg, adding -b
2020/1/1 to the above:
In this case, the budget goal transactions are generated on first days
of of month (this can be seen with hledger print --forecast tag:gener-
ated expenses). Whereas the report period defaults to just the 15th
day of january (this can be seen from the report table's column head-
ings).
$ 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]
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]
To fix this kind of thing, be more explicit about the report period
(and/or the periodic rules' dates). In this case, adding -b 2020 does
the trick.
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
rules to generate goals. This includes rules with a different report
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
whose description contains DESCPAT, a case-insensitive substring (not a
regular expression or query). This means you can give your periodic
rules descriptions (remember that two spaces are needed), and then se-
lect from multiple budgets defined in your journal.
rules descriptions (remember that two spaces are needed between period
expression and description), and then select from multiple budgets de-
fined in your journal.
Budget vs forecast
hledger --forecast ... and hledger balance --budget ... are separate
features, though both of them use the periodic transaction rules de-
fined in the journal, and both of them generate temporary transactions
for reporting purposes ("forecast transactions" and "budget goal trans-
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:
Budgeting vs forecasting
--budget and --forecast both use the periodic transaction rules in the
journal to generate temporary transactions for reporting purposes.
However they are separate features - though you can use both at the
same time if you want. Here are some differences between them:
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-
actions
3. --budget's budget goal transactions are invisible, except that they
produce goal amounts.
o budget goal transactions are invisible except for the goal amounts
they produce in --budget reports.
--forecast's forecast transactions are visible, and appear in re-
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
o --budget uses all periodic rules (--budget) or a selected subset
(--budget=DESCPAT)
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.
--forecast generates forecast transactions from after the last reg-
ular transaction, to the end of the report period; while --fore-
cast=PERIODEXPR generates them throughout the specified period;
both optionally restricted by periods specified in the periodic
transaction rules.
Balance report layout
The --layout option affects how balance reports show multi-commodity