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]

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

@ -75,10 +75,6 @@ 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
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'
@ -86,72 +82,65 @@ will be applied in addition to any search query entered there.
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

103
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).
--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 --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

460
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:food:dining $32
expenses:gifts $100 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 ---------------++--------------------
.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] || $400 [80% of $500]
.EE .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 In this case, the budget goal transactions are generated on first days
account, all its parents would have budget as well. 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 .PP
To illustrate this, consider the following budget: To fix this kind of thing, be more explicit about the report period
.IP (and/or the periodic rules\[aq] dates).
.EX In this case, adding \f[CR]-b 2020\f[R] does the trick.
\[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

1495
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

379
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:food:dining $32
expenses:gifts $100 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 ---------------++--------------------
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:
$ 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] || $400 [80% of $500]
Budgets and subaccounts In this case, the budget goal transactions are generated on first days
You can add budgets to any account in your account hierarchy. If you of of month (this can be seen with hledger print --forecast tag:gener-
have budgets on both parent account and some of its children, then bud- ated expenses). Whereas the report period defaults to just the 15th
get(s) of the child account(s) would be added to the budget of their day of january (this can be seen from the report table's column head-
parent, much like account balances behave. ings).
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' dates). In this case, adding -b 2020 does
the trick.
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