diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index c38c5dc98..21375856c 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -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] diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index e4cce2e12..418aec9b5 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -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 diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index fc05078b5..c21f449b5 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -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: diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 2de797bbf..036c1d077 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -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 +===============++============================================ + || $-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]\[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]\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]\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]\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 -==============++============ - || $400 ---------------++------------ - || $400 + || 2020-01-15 +===============++==================== + || $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 diff --git a/hledger/hledger.info b/hledger/hledger.info index 9d7f85251..50ac72c7e 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1853,7 +1853,7 @@ does not disable balance assignments, described below). * Assertions and multiple included files:: * Assertions and multiple -f files:: * Assertions and commodities:: -* Assertions and prices:: +* Assertions and costs:: * Assertions and subaccounts:: * Assertions and virtual postings:: * Assertions and auto postings:: @@ -1909,7 +1909,7 @@ problems in earlier files to disrupt valid assertions in later files. 'include', or concatenate the files temporarily.  -File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions +File: hledger.info, Node: Assertions and commodities, Next: Assertions and costs, Prev: Assertions and multiple -f files, Up: Balance assertions 9.14.4 Assertions and commodities --------------------------------- @@ -1957,10 +1957,10 @@ commodity into its own subaccount: a:euro 0 == 1€  -File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions +File: hledger.info, Node: Assertions and costs, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions -9.14.5 Assertions and prices ----------------------------- +9.14.5 Assertions and costs +--------------------------- Balance assertions ignore costs, and should normally be written without one: @@ -1968,14 +1968,14 @@ 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 -_assignments_ 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).  -File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions +File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and costs, Up: Balance assertions 9.14.6 Assertions and subaccounts --------------------------------- @@ -8113,148 +8113,138 @@ File: hledger.info, Node: Budget report, Next: Balance report layout, Prev: B 24.6.14 Budget report --------------------- -The '--budget' report type activates extra columns showing any budget -goals for each account and period. The budget goals are defined by -periodic 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 -expense categories to construct a minimal monthly budget: + * Budget goals and performance percentages are also shown, in + brackets + * 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 +example, 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 +===============++============================================ + || $-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. -Currently: - - * Accounts with budget goals during the report period, and their - parents, are shown. - * Their subaccounts are not shown (regardless of the depth setting). - * Accounts without budget goals, if any, are aggregated and shown as - "". - * Amounts are always inclusive (subaccount-including), even in list - mode. - * After each actual amount, the corresponding goal amount and - percentage of goal reached are also shown, in square brackets. - - 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. - - 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: - -$ 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] - - You can roll over unspent budgets to next period with '--cumulative': - -$ 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] - - It's common to limit budgets/budget reports to just expenses - -hledger bal -M --budget expenses - - 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. + This is "goal-based budgeting"; you define goals for accounts and +periods, often recurring, and hledger shows performance relative to the +goals. This contrasts with "envelope budgeting", 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. * Menu: -* Budget report start date:: -* Budgets and subaccounts:: +* Using the budget report:: +* Budget date surprises:: * Selecting budget goals:: -* Budget vs forecast:: +* Budgeting vs forecasting::  -File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report +File: hledger.info, Node: Using the budget report, Next: Budget date surprises, Up: Budget report -24.6.14.1 Budget report start date -.................................. +24.6.14.1 Using the budget report +................................. -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: +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 +troubleshooting. + + * In the above example, 'expenses:bus' and 'expenses:food' are shown + because they have budget goals during the report period. + + * Their parent 'expenses' is also shown, with budget goals aggregated + from the children. + + * The subaccounts 'expenses:food:groceries' and + 'expenses:food:dining' are not shown since they have no budget goal + of their own, but they contribute to 'expenses:food''s actual + amount. + + * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also + not shown, but they contribute to 'expenses''s actual amount. + + * The other unbudgeted accounts 'income' and 'assets:bank:checking' + are grouped as ''. + + * '--depth' or 'depth:' can be used to limit report depth in the + usual way (but will not reveal unbudgeted subaccounts). + + * Amounts are always inclusive of subaccounts (even in '-l/--list' + mode). + + * 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. + + * In the periodic rules used for setting budget goals, unbalanced + postings are convenient. + + * 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 '' account is occasionally hard to + exclude; this is because of date surprises, discussed below.) + + * 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. + + * You can "roll over" amounts (actual and budgeted) to the next + period with '--cumulative'. + + See also: https://hledger.org/budgeting.html. + + +File: hledger.info, Node: Budget date surprises, Next: Selecting budget goals, Prev: Using the budget report, Up: Budget report + +24.6.14.2 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 '' account should be +excluded by the 'expenses' query, but isn't.): ~ monthly in 2020 (expenses:food) $500 @@ -8263,131 +8253,33 @@ default report period is just the day of 2020-01-15: expenses:food $400 assets:checking -$ hledger bal expenses --budget +$ hledger bal --budget expenses Budget performance in 2020-01-15: - || 2020-01-15 -==============++============ - || $400 ---------------++------------ - || $400 + || 2020-01-15 +===============++==================== + || $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:generated expenses'). Whereas the report period defaults to just +the 15th day of january (this can be seen from the report table's column +headings). -$ 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] + 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.  -File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report - -24.6.14.2 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 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 -towards 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:electronics:upgrades' and 'expenses:personal:train -tickets', and since both of these accounts are without explicitly -defined budget, these transactions 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] - - -File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report +File: hledger.info, Node: Selecting budget goals, Next: Budgeting vs forecasting, Prev: Budget date surprises, Up: Budget report 24.6.14.3 Selecting budget goals ................................ -The budget report evaluates periodic transaction rules to generate -special "goal transactions", which generate the goal amounts for each -account 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 interval from your report. Eg if you have daily, weekly and monthly periodic rules, all of these will contribute to the goals in a monthly @@ -8397,56 +8289,47 @@ budget report. 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 -select 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 +defined in your journal.  -File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report +File: hledger.info, Node: Budgeting vs forecasting, Prev: Selecting budget goals, Up: Budget report -24.6.14.4 Budget vs forecast -............................ +24.6.14.4 Budgeting vs forecasting +.................................. -'hledger --forecast ...' and 'hledger balance --budget ...' 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 ("forecast transactions" and "budget goal -transactions", respectively). You can use both features at the same -time if you want. Here are some differences between them, as of hledger -1.29: +'--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*. - * -forecast is a general hledger option, usable with any command - * -budget is a 'balance' command option, usable only with that - command. + '--forecast' is a general option; *forecasting works with all + reports*. - Visibility of generated transactions: + 2. '--budget' uses *all periodic rules*; '--budget=DESCPAT' uses *just + the rules matched* by DESCPAT. - * forecast transactions are visible in any report, like ordinary - transactions - * budget goal transactions are invisible except for the goal amounts - they produce in -budget reports. + '--forecast' uses *all periodic rules*. - Periodic transaction rules: + 3. '--budget''s budget goal transactions are invisible, except that + they produce *goal amounts*. - * -forecast uses all available periodic transaction rules - * -budget uses all periodic rules ('--budget') or a selected subset - ('--budget=DESCPAT') + '--forecast''s forecast transactions are visible, and *appear in + reports*. - Period of generated transactions: + 4. '--budget' generates budget goal transactions *throughout the + report period*, optionally restricted by periods specified in the + periodic transaction rules. - * -forecast generates forecast transactions - * from after the last regular transaction to the end of the - report period ('--forecast') - * or, during a specified period ('--forecast=PERIODEXPR') - * possibly further restricted by a period specified in the - periodic transaction rule - * and always restricted within the bounds of the report period - - * -budget generates budget goal transactions - * throughout the report period - * possibly restricted by a period specified in the periodic - transaction rule. + '--forecast' generates forecast transactions from *after the last + regular transaction*, to the end of the report period; while + '--forecast=PERIODEXPR' generates them *throughout the specified + period*; both optionally restricted by periods specified in the + periodic transaction rules.  File: hledger.info, Node: Balance report layout, Next: Useful balance reports, Prev: Budget report, Up: balance @@ -11006,536 +10889,536 @@ Node: Other cost/lot notations61978 Ref: #other-costlot-notations62110 Node: Balance assertions64699 Ref: #balance-assertions64850 -Node: Assertions and ordering65933 -Ref: #assertions-and-ordering66122 -Node: Assertions and multiple included files66822 -Ref: #assertions-and-multiple-included-files67082 -Node: Assertions and multiple -f files67582 -Ref: #assertions-and-multiple--f-files67833 -Node: Assertions and commodities68230 -Ref: #assertions-and-commodities68452 -Node: Assertions and prices69632 -Ref: #assertions-and-prices69838 -Node: Assertions and subaccounts70265 -Ref: #assertions-and-subaccounts70486 -Node: Assertions and virtual postings70810 -Ref: #assertions-and-virtual-postings71048 -Node: Assertions and auto postings71180 -Ref: #assertions-and-auto-postings71410 -Node: Assertions and precision72055 -Ref: #assertions-and-precision72237 -Node: Posting comments72504 -Ref: #posting-comments72650 -Node: Tags73027 -Ref: #tags73141 -Node: Tag values74334 -Ref: #tag-values74423 -Node: Directives75182 -Ref: #directives75309 -Node: Directives and multiple files76639 -Ref: #directives-and-multiple-files76817 -Node: Directive effects77584 -Ref: #directive-effects77738 -Node: account directive80751 -Ref: #account-directive80907 -Node: Account comments82305 -Ref: #account-comments82455 -Node: Account subdirectives82963 -Ref: #account-subdirectives83154 -Node: Account error checking83296 -Ref: #account-error-checking83494 -Node: Account display order84683 -Ref: #account-display-order84871 -Node: Account types85972 -Ref: #account-types86113 -Node: alias directive89740 -Ref: #alias-directive89901 -Node: Basic aliases90951 -Ref: #basic-aliases91082 -Node: Regex aliases91826 -Ref: #regex-aliases91983 -Node: Combining aliases92873 -Ref: #combining-aliases93051 -Node: Aliases and multiple files94327 -Ref: #aliases-and-multiple-files94531 -Node: end aliases directive95110 -Ref: #end-aliases-directive95329 -Node: Aliases can generate bad account names95478 -Ref: #aliases-can-generate-bad-account-names95726 -Node: Aliases and account types96311 -Ref: #aliases-and-account-types96503 -Node: commodity directive97199 -Ref: #commodity-directive97373 -Node: Commodity directive syntax98558 -Ref: #commodity-directive-syntax98743 -Node: Commodity error checking100194 -Ref: #commodity-error-checking100375 -Node: decimal-mark directive100669 -Ref: #decimal-mark-directive100851 -Node: include directive101248 -Ref: #include-directive101412 -Node: P directive102324 -Ref: #p-directive102469 -Node: payee directive103358 -Ref: #payee-directive103507 -Node: tag directive103980 -Ref: #tag-directive104135 -Node: Periodic transactions104603 -Ref: #periodic-transactions104768 -Node: Periodic rule syntax106474 -Ref: #periodic-rule-syntax106652 -Node: Periodic rules and relative dates107297 -Ref: #periodic-rules-and-relative-dates107563 -Node: Two spaces between period expression and description!108074 -Ref: #two-spaces-between-period-expression-and-description108351 -Node: Auto postings109035 -Ref: #auto-postings109183 -Node: Auto postings and multiple files111620 -Ref: #auto-postings-and-multiple-files111784 -Node: Auto postings and dates112185 -Ref: #auto-postings-and-dates112433 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions112608 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112964 -Node: Auto posting tags113467 -Ref: #auto-posting-tags113749 -Node: Auto postings on forecast transactions only114385 -Ref: #auto-postings-on-forecast-transactions-only114631 -Node: Other syntax114878 -Ref: #other-syntax114994 -Node: Balance assignments115621 -Ref: #balance-assignments115777 -Node: Balance assignments and prices117150 -Ref: #balance-assignments-and-prices117365 -Node: Balance assignments and multiple files117576 -Ref: #balance-assignments-and-multiple-files117807 -Node: Bracketed posting dates118000 -Ref: #bracketed-posting-dates118184 -Node: D directive118698 -Ref: #d-directive118866 -Node: apply account directive120466 -Ref: #apply-account-directive120646 -Node: Y directive121333 -Ref: #y-directive121493 -Node: Secondary dates122321 -Ref: #secondary-dates122475 -Node: Star comments123289 -Ref: #star-comments123449 -Node: Valuation expressions123981 -Ref: #valuation-expressions124158 -Node: Virtual postings124280 -Ref: #virtual-postings124457 -Node: Other Ledger directives125894 -Ref: #other-ledger-directives126057 -Node: CSV126623 -Ref: #csv126716 -Node: CSV rules cheatsheet128796 -Ref: #csv-rules-cheatsheet128925 -Node: source130723 -Ref: #source130846 -Node: separator131726 -Ref: #separator131839 -Node: skip132379 -Ref: #skip132487 -Node: date-format133031 -Ref: #date-format133152 -Node: timezone133876 -Ref: #timezone133999 -Node: newest-first135004 -Ref: #newest-first135142 -Node: intra-day-reversed135719 -Ref: #intra-day-reversed135873 -Node: decimal-mark136321 -Ref: #decimal-mark136462 -Node: fields list136801 -Ref: #fields-list136940 -Node: Field assignment138611 -Ref: #field-assignment138755 -Node: Field names139832 -Ref: #field-names139963 -Node: date field141166 -Ref: #date-field141284 -Node: date2 field141332 -Ref: #date2-field141473 -Node: status field141529 -Ref: #status-field141672 -Node: code field141721 -Ref: #code-field141866 -Node: description field141911 -Ref: #description-field142071 -Node: comment field142130 -Ref: #comment-field142285 -Node: account field142578 -Ref: #account-field142728 -Node: amount field143298 -Ref: #amount-field143447 -Node: currency field146139 -Ref: #currency-field146292 -Node: balance field146549 -Ref: #balance-field146681 -Node: if block147053 -Ref: #if-block147174 -Node: Matchers148582 -Ref: #matchers148696 -Node: What matchers match149493 -Ref: #what-matchers-match149642 -Node: Combining matchers150082 -Ref: #combining-matchers150250 -Node: Match groups150736 -Ref: #match-groups150864 -Node: if table151611 -Ref: #if-table151733 -Node: balance-type153295 -Ref: #balance-type153424 -Node: include154124 -Ref: #include154251 -Node: Working with CSV154695 -Ref: #working-with-csv154842 -Node: Rapid feedback155249 -Ref: #rapid-feedback155382 -Node: Valid CSV155834 -Ref: #valid-csv155980 -Node: File Extension156712 -Ref: #file-extension156885 -Node: Reading CSV from standard input157449 -Ref: #reading-csv-from-standard-input157673 -Node: Reading multiple CSV files157837 -Ref: #reading-multiple-csv-files158068 -Node: Reading files specified by rule158309 -Ref: #reading-files-specified-by-rule158537 -Node: Valid transactions159708 -Ref: #valid-transactions159907 -Node: Deduplicating importing160535 -Ref: #deduplicating-importing160730 -Node: Setting amounts161766 -Ref: #setting-amounts161937 -Node: Amount signs164295 -Ref: #amount-signs164465 -Node: Setting currency/commodity165362 -Ref: #setting-currencycommodity165566 -Node: Amount decimal places166740 -Ref: #amount-decimal-places166946 -Node: Referencing other fields167258 -Ref: #referencing-other-fields167471 -Node: How CSV rules are evaluated168368 -Ref: #how-csv-rules-are-evaluated168585 -Node: Well factored rules170038 -Ref: #well-factored-rules170206 -Node: CSV rules examples170530 -Ref: #csv-rules-examples170665 -Node: Bank of Ireland170730 -Ref: #bank-of-ireland170867 -Node: Coinbase172329 -Ref: #coinbase172467 -Node: Amazon173514 -Ref: #amazon173639 -Node: Paypal175358 -Ref: #paypal175466 -Node: Timeclock183110 -Ref: #timeclock183215 -Node: Timedot185393 -Ref: #timedot185516 -Node: Timedot examples188621 -Ref: #timedot-examples188727 -Node: PART 3 REPORTING CONCEPTS190898 -Ref: #part-3-reporting-concepts191080 -Node: Amount formatting parseability191080 -Ref: #amount-formatting-parseability191277 -Node: Time periods193482 -Ref: #time-periods193621 -Node: Report start & end date193739 -Ref: #report-start-end-date193891 -Node: Smart dates195550 -Ref: #smart-dates195703 -Node: Report intervals197571 -Ref: #report-intervals197726 -Node: Date adjustment198144 -Ref: #date-adjustment198304 -Node: Period expressions199155 -Ref: #period-expressions199296 -Node: Period expressions with a report interval201060 -Ref: #period-expressions-with-a-report-interval201294 -Node: More complex report intervals201508 -Ref: #more-complex-report-intervals201753 -Node: Multiple weekday intervals203554 -Ref: #multiple-weekday-intervals203743 -Node: Depth204565 -Ref: #depth204667 -Node: Queries204963 -Ref: #queries205065 -Node: Query types206190 -Ref: #query-types206311 -Node: Combining query terms209647 -Ref: #combining-query-terms209824 -Node: Queries and command options211092 -Ref: #queries-and-command-options211291 -Node: Queries and valuation211540 -Ref: #queries-and-valuation211735 -Node: Querying with account aliases211964 -Ref: #querying-with-account-aliases212175 -Node: Querying with cost or value212305 -Ref: #querying-with-cost-or-value212482 -Node: Pivoting212783 -Ref: #pivoting212897 -Node: Generating data214674 -Ref: #generating-data214806 -Node: Forecasting216389 -Ref: #forecasting216514 -Node: --forecast217045 -Ref: #forecast217176 -Node: Inspecting forecast transactions218222 -Ref: #inspecting-forecast-transactions218424 -Node: Forecast reports219554 -Ref: #forecast-reports219727 -Node: Forecast tags220663 -Ref: #forecast-tags220823 -Node: Forecast period in detail221283 -Ref: #forecast-period-in-detail221477 -Node: Forecast troubleshooting222371 -Ref: #forecast-troubleshooting222539 -Node: Budgeting223442 -Ref: #budgeting223562 -Node: Cost reporting223999 -Ref: #cost-reporting224133 -Node: Recording costs224794 -Ref: #recording-costs224930 -Node: Reporting at cost226521 -Ref: #reporting-at-cost226696 -Node: Equity conversion postings227286 -Ref: #equity-conversion-postings227500 -Node: Inferring equity conversion postings229931 -Ref: #inferring-equity-conversion-postings230194 -Node: Combining costs and equity conversion postings230946 -Ref: #combining-costs-and-equity-conversion-postings231256 -Node: Requirements for detecting equity conversion postings232244 -Ref: #requirements-for-detecting-equity-conversion-postings232566 -Node: Infer cost and equity by default ?233766 -Ref: #infer-cost-and-equity-by-default233995 -Node: Value reporting234203 -Ref: #value-reporting234345 -Node: -V Value235119 -Ref: #v-value235251 -Node: -X Value in specified commodity235446 -Ref: #x-value-in-specified-commodity235647 -Node: Valuation date235796 -Ref: #valuation-date235973 -Node: Finding market price236756 -Ref: #finding-market-price236967 -Node: --infer-market-prices market prices from transactions238136 -Ref: #infer-market-prices-market-prices-from-transactions238418 -Node: Valuation commodity241180 -Ref: #valuation-commodity241399 -Node: Simple valuation examples242612 -Ref: #simple-valuation-examples242816 -Node: --value Flexible valuation243475 -Ref: #value-flexible-valuation243685 -Node: More valuation examples245329 -Ref: #more-valuation-examples245544 -Node: Interaction of valuation and queries246814 -Ref: #interaction-of-valuation-and-queries247061 -Node: Effect of valuation on reports247533 -Ref: #effect-of-valuation-on-reports247736 -Node: PART 4 COMMANDS255433 -Ref: #part-4-commands255582 -Node: Commands overview255961 -Ref: #commands-overview256095 -Node: DATA ENTRY256274 -Ref: #data-entry256398 -Node: DATA CREATION256597 -Ref: #data-creation256751 -Node: DATA MANAGEMENT256869 -Ref: #data-management257034 -Node: REPORTS FINANCIAL257155 -Ref: #reports-financial257330 -Node: REPORTS VERSATILE257635 -Ref: #reports-versatile257808 -Node: REPORTS BASIC258061 -Ref: #reports-basic258213 -Node: HELP258722 -Ref: #help258844 -Node: ADD-ONS258954 -Ref: #add-ons259060 -Node: accounts259639 -Ref: #accounts259772 -Node: activity261659 -Ref: #activity261778 -Node: add262152 -Ref: #add262262 -Node: aregister265073 -Ref: #aregister265194 -Node: aregister and posting dates268082 -Ref: #aregister-and-posting-dates268227 -Node: balance268983 -Ref: #balance269109 -Node: balance features270094 -Ref: #balance-features270234 -Node: Simple balance report272200 -Ref: #simple-balance-report272385 -Node: Balance report line format274010 -Ref: #balance-report-line-format274212 -Node: Filtered balance report276370 -Ref: #filtered-balance-report276562 -Node: List or tree mode276889 -Ref: #list-or-tree-mode277057 -Node: Depth limiting278402 -Ref: #depth-limiting278568 -Node: Dropping top-level accounts279169 -Ref: #dropping-top-level-accounts279369 -Node: Showing declared accounts279679 -Ref: #showing-declared-accounts279878 -Node: Sorting by amount280409 -Ref: #sorting-by-amount280576 -Node: Percentages281246 -Ref: #percentages281405 -Node: Multi-period balance report281953 -Ref: #multi-period-balance-report282153 -Node: Balance change end balance284428 -Ref: #balance-change-end-balance284637 -Node: Balance report types286065 -Ref: #balance-report-types286246 -Node: Calculation type286744 -Ref: #calculation-type286899 -Node: Accumulation type287448 -Ref: #accumulation-type287628 -Node: Valuation type288530 -Ref: #valuation-type288718 -Node: Combining balance report types289719 -Ref: #combining-balance-report-types289913 -Node: Budget report291751 -Ref: #budget-report291913 -Node: Budget report start date297567 -Ref: #budget-report-start-date297745 -Node: Budgets and subaccounts299077 -Ref: #budgets-and-subaccounts299284 -Node: Selecting budget goals302724 -Ref: #selecting-budget-goals302923 -Node: Budget vs forecast303958 -Ref: #budget-vs-forecast304117 -Node: Balance report layout305747 -Ref: #balance-report-layout305927 -Node: Useful balance reports314112 -Ref: #useful-balance-reports314272 -Node: balancesheet315357 -Ref: #balancesheet315502 -Node: balancesheetequity316829 -Ref: #balancesheetequity316987 -Node: cashflow318383 -Ref: #cashflow318514 -Node: check319949 -Ref: #check320063 -Node: Default checks320867 -Ref: #default-checks320993 -Node: Strict checks321490 -Ref: #strict-checks321635 -Node: Other checks322115 -Ref: #other-checks322257 -Node: Custom checks322790 -Ref: #custom-checks322947 -Node: More about specific checks323364 -Ref: #more-about-specific-checks323526 -Node: close324232 -Ref: #close324343 -Node: close and balance assertions327808 -Ref: #close-and-balance-assertions327986 -Node: Example retain earnings329137 -Ref: #example-retain-earnings329354 -Node: Example migrate balances to a new file329786 -Ref: #example-migrate-balances-to-a-new-file330051 -Node: Example excluding closing/opening transactions330627 -Ref: #example-excluding-closingopening-transactions330876 -Node: codes332094 -Ref: #codes332211 -Node: commodities333075 -Ref: #commodities333203 -Node: demo333273 -Ref: #demo333394 -Node: descriptions334310 -Ref: #descriptions334440 -Node: diff334731 -Ref: #diff334846 -Node: files335888 -Ref: #files335997 -Node: help336138 -Ref: #help-1336247 -Node: import337620 -Ref: #import337743 -Node: Deduplication338851 -Ref: #deduplication338976 -Node: Import testing340995 -Ref: #import-testing341160 -Node: Importing balance assignments342003 -Ref: #importing-balance-assignments342209 -Node: Commodity display styles342858 -Ref: #commodity-display-styles343031 -Node: incomestatement343160 -Ref: #incomestatement343302 -Node: notes344630 -Ref: #notes344752 -Node: payees345114 -Ref: #payees345229 -Node: prices345748 -Ref: #prices345863 -Node: print346516 -Ref: #print346631 -Node: print explicitness347607 -Ref: #print-explicitness347750 -Node: print amount style348529 -Ref: #print-amount-style348699 -Node: print parseability349751 -Ref: #print-parseability349923 -Node: print other features350672 -Ref: #print-other-features350851 -Node: print output format351372 -Ref: #print-output-format351520 -Node: register354639 -Ref: #register354761 -Node: Custom register output359792 -Ref: #custom-register-output359923 -Node: rewrite361267 -Ref: #rewrite361385 -Node: Re-write rules in a file363283 -Ref: #re-write-rules-in-a-file363446 -Node: Diff output format364595 -Ref: #diff-output-format364778 -Node: rewrite vs print --auto365870 -Ref: #rewrite-vs.-print---auto366030 -Node: roi366586 -Ref: #roi366693 -Node: Spaces and special characters in --inv and --pnl368505 -Ref: #spaces-and-special-characters-in---inv-and---pnl368745 -Node: Semantics of --inv and --pnl369233 -Ref: #semantics-of---inv-and---pnl369472 -Node: IRR and TWR explained371322 -Ref: #irr-and-twr-explained371482 -Node: stats374735 -Ref: #stats374843 -Node: tags376230 -Ref: #tags-1376337 -Node: test377346 -Ref: #test377439 -Node: PART 5 COMMON TASKS378181 -Ref: #part-5-common-tasks378327 -Node: Getting help378625 -Ref: #getting-help378766 -Node: Constructing command lines379526 -Ref: #constructing-command-lines379727 -Node: Starting a journal file380384 -Ref: #starting-a-journal-file380586 -Node: Setting LEDGER_FILE381788 -Ref: #setting-ledger_file381980 -Node: Setting opening balances382937 -Ref: #setting-opening-balances383138 -Node: Recording transactions386279 -Ref: #recording-transactions386468 -Node: Reconciling387024 -Ref: #reconciling387176 -Node: Reporting389433 -Ref: #reporting389582 -Node: Migrating to a new file393567 -Ref: #migrating-to-a-new-file393724 -Node: BUGS394023 -Ref: #bugs394113 -Node: Troubleshooting394992 -Ref: #troubleshooting395092 +Node: Assertions and ordering65932 +Ref: #assertions-and-ordering66121 +Node: Assertions and multiple included files66821 +Ref: #assertions-and-multiple-included-files67081 +Node: Assertions and multiple -f files67581 +Ref: #assertions-and-multiple--f-files67832 +Node: Assertions and commodities68229 +Ref: #assertions-and-commodities68450 +Node: Assertions and costs69630 +Ref: #assertions-and-costs69833 +Node: Assertions and subaccounts70274 +Ref: #assertions-and-subaccounts70494 +Node: Assertions and virtual postings70818 +Ref: #assertions-and-virtual-postings71056 +Node: Assertions and auto postings71188 +Ref: #assertions-and-auto-postings71418 +Node: Assertions and precision72063 +Ref: #assertions-and-precision72245 +Node: Posting comments72512 +Ref: #posting-comments72658 +Node: Tags73035 +Ref: #tags73149 +Node: Tag values74342 +Ref: #tag-values74431 +Node: Directives75190 +Ref: #directives75317 +Node: Directives and multiple files76647 +Ref: #directives-and-multiple-files76825 +Node: Directive effects77592 +Ref: #directive-effects77746 +Node: account directive80759 +Ref: #account-directive80915 +Node: Account comments82313 +Ref: #account-comments82463 +Node: Account subdirectives82971 +Ref: #account-subdirectives83162 +Node: Account error checking83304 +Ref: #account-error-checking83502 +Node: Account display order84691 +Ref: #account-display-order84879 +Node: Account types85980 +Ref: #account-types86121 +Node: alias directive89748 +Ref: #alias-directive89909 +Node: Basic aliases90959 +Ref: #basic-aliases91090 +Node: Regex aliases91834 +Ref: #regex-aliases91991 +Node: Combining aliases92881 +Ref: #combining-aliases93059 +Node: Aliases and multiple files94335 +Ref: #aliases-and-multiple-files94539 +Node: end aliases directive95118 +Ref: #end-aliases-directive95337 +Node: Aliases can generate bad account names95486 +Ref: #aliases-can-generate-bad-account-names95734 +Node: Aliases and account types96319 +Ref: #aliases-and-account-types96511 +Node: commodity directive97207 +Ref: #commodity-directive97381 +Node: Commodity directive syntax98566 +Ref: #commodity-directive-syntax98751 +Node: Commodity error checking100202 +Ref: #commodity-error-checking100383 +Node: decimal-mark directive100677 +Ref: #decimal-mark-directive100859 +Node: include directive101256 +Ref: #include-directive101420 +Node: P directive102332 +Ref: #p-directive102477 +Node: payee directive103366 +Ref: #payee-directive103515 +Node: tag directive103988 +Ref: #tag-directive104143 +Node: Periodic transactions104611 +Ref: #periodic-transactions104776 +Node: Periodic rule syntax106482 +Ref: #periodic-rule-syntax106660 +Node: Periodic rules and relative dates107305 +Ref: #periodic-rules-and-relative-dates107571 +Node: Two spaces between period expression and description!108082 +Ref: #two-spaces-between-period-expression-and-description108359 +Node: Auto postings109043 +Ref: #auto-postings109191 +Node: Auto postings and multiple files111628 +Ref: #auto-postings-and-multiple-files111792 +Node: Auto postings and dates112193 +Ref: #auto-postings-and-dates112441 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions112616 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112972 +Node: Auto posting tags113475 +Ref: #auto-posting-tags113757 +Node: Auto postings on forecast transactions only114393 +Ref: #auto-postings-on-forecast-transactions-only114639 +Node: Other syntax114886 +Ref: #other-syntax115002 +Node: Balance assignments115629 +Ref: #balance-assignments115785 +Node: Balance assignments and prices117158 +Ref: #balance-assignments-and-prices117373 +Node: Balance assignments and multiple files117584 +Ref: #balance-assignments-and-multiple-files117815 +Node: Bracketed posting dates118008 +Ref: #bracketed-posting-dates118192 +Node: D directive118706 +Ref: #d-directive118874 +Node: apply account directive120474 +Ref: #apply-account-directive120654 +Node: Y directive121341 +Ref: #y-directive121501 +Node: Secondary dates122329 +Ref: #secondary-dates122483 +Node: Star comments123297 +Ref: #star-comments123457 +Node: Valuation expressions123989 +Ref: #valuation-expressions124166 +Node: Virtual postings124288 +Ref: #virtual-postings124465 +Node: Other Ledger directives125902 +Ref: #other-ledger-directives126065 +Node: CSV126631 +Ref: #csv126724 +Node: CSV rules cheatsheet128804 +Ref: #csv-rules-cheatsheet128933 +Node: source130731 +Ref: #source130854 +Node: separator131734 +Ref: #separator131847 +Node: skip132387 +Ref: #skip132495 +Node: date-format133039 +Ref: #date-format133160 +Node: timezone133884 +Ref: #timezone134007 +Node: newest-first135012 +Ref: #newest-first135150 +Node: intra-day-reversed135727 +Ref: #intra-day-reversed135881 +Node: decimal-mark136329 +Ref: #decimal-mark136470 +Node: fields list136809 +Ref: #fields-list136948 +Node: Field assignment138619 +Ref: #field-assignment138763 +Node: Field names139840 +Ref: #field-names139971 +Node: date field141174 +Ref: #date-field141292 +Node: date2 field141340 +Ref: #date2-field141481 +Node: status field141537 +Ref: #status-field141680 +Node: code field141729 +Ref: #code-field141874 +Node: description field141919 +Ref: #description-field142079 +Node: comment field142138 +Ref: #comment-field142293 +Node: account field142586 +Ref: #account-field142736 +Node: amount field143306 +Ref: #amount-field143455 +Node: currency field146147 +Ref: #currency-field146300 +Node: balance field146557 +Ref: #balance-field146689 +Node: if block147061 +Ref: #if-block147182 +Node: Matchers148590 +Ref: #matchers148704 +Node: What matchers match149501 +Ref: #what-matchers-match149650 +Node: Combining matchers150090 +Ref: #combining-matchers150258 +Node: Match groups150744 +Ref: #match-groups150872 +Node: if table151619 +Ref: #if-table151741 +Node: balance-type153303 +Ref: #balance-type153432 +Node: include154132 +Ref: #include154259 +Node: Working with CSV154703 +Ref: #working-with-csv154850 +Node: Rapid feedback155257 +Ref: #rapid-feedback155390 +Node: Valid CSV155842 +Ref: #valid-csv155988 +Node: File Extension156720 +Ref: #file-extension156893 +Node: Reading CSV from standard input157457 +Ref: #reading-csv-from-standard-input157681 +Node: Reading multiple CSV files157845 +Ref: #reading-multiple-csv-files158076 +Node: Reading files specified by rule158317 +Ref: #reading-files-specified-by-rule158545 +Node: Valid transactions159716 +Ref: #valid-transactions159915 +Node: Deduplicating importing160543 +Ref: #deduplicating-importing160738 +Node: Setting amounts161774 +Ref: #setting-amounts161945 +Node: Amount signs164303 +Ref: #amount-signs164473 +Node: Setting currency/commodity165370 +Ref: #setting-currencycommodity165574 +Node: Amount decimal places166748 +Ref: #amount-decimal-places166954 +Node: Referencing other fields167266 +Ref: #referencing-other-fields167479 +Node: How CSV rules are evaluated168376 +Ref: #how-csv-rules-are-evaluated168593 +Node: Well factored rules170046 +Ref: #well-factored-rules170214 +Node: CSV rules examples170538 +Ref: #csv-rules-examples170673 +Node: Bank of Ireland170738 +Ref: #bank-of-ireland170875 +Node: Coinbase172337 +Ref: #coinbase172475 +Node: Amazon173522 +Ref: #amazon173647 +Node: Paypal175366 +Ref: #paypal175474 +Node: Timeclock183118 +Ref: #timeclock183223 +Node: Timedot185401 +Ref: #timedot185524 +Node: Timedot examples188629 +Ref: #timedot-examples188735 +Node: PART 3 REPORTING CONCEPTS190906 +Ref: #part-3-reporting-concepts191088 +Node: Amount formatting parseability191088 +Ref: #amount-formatting-parseability191285 +Node: Time periods193490 +Ref: #time-periods193629 +Node: Report start & end date193747 +Ref: #report-start-end-date193899 +Node: Smart dates195558 +Ref: #smart-dates195711 +Node: Report intervals197579 +Ref: #report-intervals197734 +Node: Date adjustment198152 +Ref: #date-adjustment198312 +Node: Period expressions199163 +Ref: #period-expressions199304 +Node: Period expressions with a report interval201068 +Ref: #period-expressions-with-a-report-interval201302 +Node: More complex report intervals201516 +Ref: #more-complex-report-intervals201761 +Node: Multiple weekday intervals203562 +Ref: #multiple-weekday-intervals203751 +Node: Depth204573 +Ref: #depth204675 +Node: Queries204971 +Ref: #queries205073 +Node: Query types206198 +Ref: #query-types206319 +Node: Combining query terms209655 +Ref: #combining-query-terms209832 +Node: Queries and command options211100 +Ref: #queries-and-command-options211299 +Node: Queries and valuation211548 +Ref: #queries-and-valuation211743 +Node: Querying with account aliases211972 +Ref: #querying-with-account-aliases212183 +Node: Querying with cost or value212313 +Ref: #querying-with-cost-or-value212490 +Node: Pivoting212791 +Ref: #pivoting212905 +Node: Generating data214682 +Ref: #generating-data214814 +Node: Forecasting216397 +Ref: #forecasting216522 +Node: --forecast217053 +Ref: #forecast217184 +Node: Inspecting forecast transactions218230 +Ref: #inspecting-forecast-transactions218432 +Node: Forecast reports219562 +Ref: #forecast-reports219735 +Node: Forecast tags220671 +Ref: #forecast-tags220831 +Node: Forecast period in detail221291 +Ref: #forecast-period-in-detail221485 +Node: Forecast troubleshooting222379 +Ref: #forecast-troubleshooting222547 +Node: Budgeting223450 +Ref: #budgeting223570 +Node: Cost reporting224007 +Ref: #cost-reporting224141 +Node: Recording costs224802 +Ref: #recording-costs224938 +Node: Reporting at cost226529 +Ref: #reporting-at-cost226704 +Node: Equity conversion postings227294 +Ref: #equity-conversion-postings227508 +Node: Inferring equity conversion postings229939 +Ref: #inferring-equity-conversion-postings230202 +Node: Combining costs and equity conversion postings230954 +Ref: #combining-costs-and-equity-conversion-postings231264 +Node: Requirements for detecting equity conversion postings232252 +Ref: #requirements-for-detecting-equity-conversion-postings232574 +Node: Infer cost and equity by default ?233774 +Ref: #infer-cost-and-equity-by-default234003 +Node: Value reporting234211 +Ref: #value-reporting234353 +Node: -V Value235127 +Ref: #v-value235259 +Node: -X Value in specified commodity235454 +Ref: #x-value-in-specified-commodity235655 +Node: Valuation date235804 +Ref: #valuation-date235981 +Node: Finding market price236764 +Ref: #finding-market-price236975 +Node: --infer-market-prices market prices from transactions238144 +Ref: #infer-market-prices-market-prices-from-transactions238426 +Node: Valuation commodity241188 +Ref: #valuation-commodity241407 +Node: Simple valuation examples242620 +Ref: #simple-valuation-examples242824 +Node: --value Flexible valuation243483 +Ref: #value-flexible-valuation243693 +Node: More valuation examples245337 +Ref: #more-valuation-examples245552 +Node: Interaction of valuation and queries246822 +Ref: #interaction-of-valuation-and-queries247069 +Node: Effect of valuation on reports247541 +Ref: #effect-of-valuation-on-reports247744 +Node: PART 4 COMMANDS255441 +Ref: #part-4-commands255590 +Node: Commands overview255969 +Ref: #commands-overview256103 +Node: DATA ENTRY256282 +Ref: #data-entry256406 +Node: DATA CREATION256605 +Ref: #data-creation256759 +Node: DATA MANAGEMENT256877 +Ref: #data-management257042 +Node: REPORTS FINANCIAL257163 +Ref: #reports-financial257338 +Node: REPORTS VERSATILE257643 +Ref: #reports-versatile257816 +Node: REPORTS BASIC258069 +Ref: #reports-basic258221 +Node: HELP258730 +Ref: #help258852 +Node: ADD-ONS258962 +Ref: #add-ons259068 +Node: accounts259647 +Ref: #accounts259780 +Node: activity261667 +Ref: #activity261786 +Node: add262160 +Ref: #add262270 +Node: aregister265081 +Ref: #aregister265202 +Node: aregister and posting dates268090 +Ref: #aregister-and-posting-dates268235 +Node: balance268991 +Ref: #balance269117 +Node: balance features270102 +Ref: #balance-features270242 +Node: Simple balance report272208 +Ref: #simple-balance-report272393 +Node: Balance report line format274018 +Ref: #balance-report-line-format274220 +Node: Filtered balance report276378 +Ref: #filtered-balance-report276570 +Node: List or tree mode276897 +Ref: #list-or-tree-mode277065 +Node: Depth limiting278410 +Ref: #depth-limiting278576 +Node: Dropping top-level accounts279177 +Ref: #dropping-top-level-accounts279377 +Node: Showing declared accounts279687 +Ref: #showing-declared-accounts279886 +Node: Sorting by amount280417 +Ref: #sorting-by-amount280584 +Node: Percentages281254 +Ref: #percentages281413 +Node: Multi-period balance report281961 +Ref: #multi-period-balance-report282161 +Node: Balance change end balance284436 +Ref: #balance-change-end-balance284645 +Node: Balance report types286073 +Ref: #balance-report-types286254 +Node: Calculation type286752 +Ref: #calculation-type286907 +Node: Accumulation type287456 +Ref: #accumulation-type287636 +Node: Valuation type288538 +Ref: #valuation-type288726 +Node: Combining balance report types289727 +Ref: #combining-balance-report-types289921 +Node: Budget report291759 +Ref: #budget-report291921 +Node: Using the budget report294064 +Ref: #using-the-budget-report294237 +Node: Budget date surprises296340 +Ref: #budget-date-surprises296540 +Node: Selecting budget goals297704 +Ref: #selecting-budget-goals297907 +Node: Budgeting vs forecasting298652 +Ref: #budgeting-vs-forecasting298829 +Node: Balance report layout300100 +Ref: #balance-report-layout300280 +Node: Useful balance reports308465 +Ref: #useful-balance-reports308625 +Node: balancesheet309710 +Ref: #balancesheet309855 +Node: balancesheetequity311182 +Ref: #balancesheetequity311340 +Node: cashflow312736 +Ref: #cashflow312867 +Node: check314302 +Ref: #check314416 +Node: Default checks315220 +Ref: #default-checks315346 +Node: Strict checks315843 +Ref: #strict-checks315988 +Node: Other checks316468 +Ref: #other-checks316610 +Node: Custom checks317143 +Ref: #custom-checks317300 +Node: More about specific checks317717 +Ref: #more-about-specific-checks317879 +Node: close318585 +Ref: #close318696 +Node: close and balance assertions322161 +Ref: #close-and-balance-assertions322339 +Node: Example retain earnings323490 +Ref: #example-retain-earnings323707 +Node: Example migrate balances to a new file324139 +Ref: #example-migrate-balances-to-a-new-file324404 +Node: Example excluding closing/opening transactions324980 +Ref: #example-excluding-closingopening-transactions325229 +Node: codes326447 +Ref: #codes326564 +Node: commodities327428 +Ref: #commodities327556 +Node: demo327626 +Ref: #demo327747 +Node: descriptions328663 +Ref: #descriptions328793 +Node: diff329084 +Ref: #diff329199 +Node: files330241 +Ref: #files330350 +Node: help330491 +Ref: #help-1330600 +Node: import331973 +Ref: #import332096 +Node: Deduplication333204 +Ref: #deduplication333329 +Node: Import testing335348 +Ref: #import-testing335513 +Node: Importing balance assignments336356 +Ref: #importing-balance-assignments336562 +Node: Commodity display styles337211 +Ref: #commodity-display-styles337384 +Node: incomestatement337513 +Ref: #incomestatement337655 +Node: notes338983 +Ref: #notes339105 +Node: payees339467 +Ref: #payees339582 +Node: prices340101 +Ref: #prices340216 +Node: print340869 +Ref: #print340984 +Node: print explicitness341960 +Ref: #print-explicitness342103 +Node: print amount style342882 +Ref: #print-amount-style343052 +Node: print parseability344104 +Ref: #print-parseability344276 +Node: print other features345025 +Ref: #print-other-features345204 +Node: print output format345725 +Ref: #print-output-format345873 +Node: register348992 +Ref: #register349114 +Node: Custom register output354145 +Ref: #custom-register-output354276 +Node: rewrite355620 +Ref: #rewrite355738 +Node: Re-write rules in a file357636 +Ref: #re-write-rules-in-a-file357799 +Node: Diff output format358948 +Ref: #diff-output-format359131 +Node: rewrite vs print --auto360223 +Ref: #rewrite-vs.-print---auto360383 +Node: roi360939 +Ref: #roi361046 +Node: Spaces and special characters in --inv and --pnl362858 +Ref: #spaces-and-special-characters-in---inv-and---pnl363098 +Node: Semantics of --inv and --pnl363586 +Ref: #semantics-of---inv-and---pnl363825 +Node: IRR and TWR explained365675 +Ref: #irr-and-twr-explained365835 +Node: stats369088 +Ref: #stats369196 +Node: tags370583 +Ref: #tags-1370690 +Node: test371699 +Ref: #test371792 +Node: PART 5 COMMON TASKS372534 +Ref: #part-5-common-tasks372680 +Node: Getting help372978 +Ref: #getting-help373119 +Node: Constructing command lines373879 +Ref: #constructing-command-lines374080 +Node: Starting a journal file374737 +Ref: #starting-a-journal-file374939 +Node: Setting LEDGER_FILE376141 +Ref: #setting-ledger_file376333 +Node: Setting opening balances377290 +Ref: #setting-opening-balances377491 +Node: Recording transactions380632 +Ref: #recording-transactions380821 +Node: Reconciling381377 +Ref: #reconciling381529 +Node: Reporting383786 +Ref: #reporting383935 +Node: Migrating to a new file387920 +Ref: #migrating-to-a-new-file388077 +Node: BUGS388376 +Ref: #bugs388466 +Node: Troubleshooting389345 +Ref: #troubleshooting389445  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 92ff6d49c..883036fd3 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -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 + ===============++============================================ + || $-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 - "". + 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 . - 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 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 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 - ==============++============ - || $400 - --------------++------------ - || $400 + || 2020-01-15 + ===============++==================== + || $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