From 19cc3743a8a16e77c04be0f3118711ae2e37cf90 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 31 May 2023 07:57:37 -1000 Subject: [PATCH] ;doc: update manuals --- hledger-ui/hledger-ui.1 | 49 +- hledger-ui/hledger-ui.info | 142 +- hledger-ui/hledger-ui.txt | 49 +- hledger-web/hledger-web.1 | 125 +- hledger-web/hledger-web.info | 166 ++- hledger-web/hledger-web.txt | 119 +- hledger/hledger.1 | 452 +++---- hledger/hledger.info | 2452 +++++++++++++++++----------------- hledger/hledger.txt | 774 ++++++----- 9 files changed, 2147 insertions(+), 2181 deletions(-) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 03ad884b2..37bbc1b76 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -45,11 +45,10 @@ transactions, by pressing the F key (or starting with --forecast) to enable \[dq]forecast mode\[dq]. .SH OPTIONS .PP -Note: if invoking hledger-ui as a hledger subcommand, write \f[V]--\f[R] -before options as shown above. -.PP Any QUERYARGS are interpreted as a hledger search query which filters the data. +.PP +hledger-ui provides the following options: .TP \f[V]-w --watch\f[R] watch for data and date changes and reload automatically @@ -84,7 +83,25 @@ show accounts as a flat list (default) \f[V]-t --tree\f[R] show accounts as a tree .PP -hledger input options: +hledger-ui also supports many of hledger\[aq]s general options (and the +hledger manual\[aq]s command line tips also apply here): +.SS General help options +.TP +\f[V]-h --help\f[R] +show general or COMMAND help +.TP +\f[V]--man\f[R] +show general or COMMAND user manual with man +.TP +\f[V]--info\f[R] +show general or COMMAND user manual with info +.TP +\f[V]--version\f[R] +show general or ADDONCMD version +.TP +\f[V]--debug[=N]\f[R] +show debug output (levels 1-9, default: 1) +.SS General input options .TP \f[V]-f FILE --file=FILE\f[R] use a different input file. @@ -112,8 +129,7 @@ assignments) .TP \f[V]-s --strict\f[R] do extra error checking (check that all posted accounts are declared) -.PP -hledger reporting options: +.SS General reporting options .TP \f[V]-b --begin=DATE\f[R] include postings/txns on or after this date (will be adjusted to @@ -229,27 +245,6 @@ When a reporting option appears more than once in the command line, the last one takes precedence. .PP Some reporting options can also be written as query arguments. -.PP -hledger help options: -.TP -\f[V]-h --help\f[R] -show general or COMMAND help -.TP -\f[V]--man\f[R] -show general or COMMAND user manual with man -.TP -\f[V]--info\f[R] -show general or COMMAND user manual with info -.TP -\f[V]--version\f[R] -show general or ADDONCMD version -.TP -\f[V]--debug[=N]\f[R] -show debug output (levels 1-9, default: 1) -.PP -A \[at]FILE argument will be expanded to the contents of FILE, which -should contain one command line option/argument per line. -(To prevent this, insert a \f[V]--\f[R] argument before.) .SH MOUSE .PP In most modern terminals, you can navigate through the screens with a diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 4e1fbe133..29a66eec5 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -58,12 +58,11 @@ File: hledger-ui.info, Node: OPTIONS, Next: MOUSE, Prev: Top, Up: Top 1 OPTIONS ********* -Note: if invoking hledger-ui as a hledger subcommand, write '--' before -options as shown above. - - Any QUERYARGS are interpreted as a hledger search query which filters +Any QUERYARGS are interpreted as a hledger search query which filters the data. + hledger-ui provides the following options: + '-w --watch' watch for data and date changes and reload automatically @@ -99,7 +98,42 @@ the data. show accounts as a tree - hledger input options: + hledger-ui also supports many of hledger's general options (and the +hledger manual's command line tips also apply here): + +* Menu: + +* General help options:: +* General input options:: +* General reporting options:: + + +File: hledger-ui.info, Node: General help options, Next: General input options, Up: OPTIONS + +1.1 General help options +======================== + +'-h --help' + + show general or COMMAND help +'--man' + + show general or COMMAND user manual with man +'--info' + + show general or COMMAND user manual with info +'--version' + + show general or ADDONCMD version +'--debug[=N]' + + show debug output (levels 1-9, default: 1) + + +File: hledger-ui.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: OPTIONS + +1.2 General input options +========================= '-f FILE --file=FILE' @@ -129,7 +163,11 @@ the data. do extra error checking (check that all posted accounts are declared) - hledger reporting options: + +File: hledger-ui.info, Node: General reporting options, Prev: General input options, Up: OPTIONS + +1.3 General reporting options +============================= '-b --begin=DATE' @@ -246,28 +284,6 @@ the last one takes precedence. Some reporting options can also be written as query arguments. - hledger help options: - -'-h --help' - - show general or COMMAND help -'--man' - - show general or COMMAND user manual with man -'--info' - - show general or COMMAND user manual with info -'--version' - - show general or ADDONCMD version -'--debug[=N]' - - show debug output (levels 1-9, default: 1) - - A @FILE argument will be expanded to the contents of FILE, which -should contain one command line option/argument per line. (To prevent -this, insert a '--' argument before.) -  File: hledger-ui.info, Node: MOUSE, Next: KEYS, Prev: OPTIONS, Up: Top @@ -651,38 +667,44 @@ Tag Table: Node: Top223 Node: OPTIONS1838 Ref: #options1936 -Node: MOUSE7432 -Ref: #mouse7527 -Node: KEYS7764 -Ref: #keys7857 -Node: SCREENS12370 -Ref: #screens12468 -Node: Menu13048 -Ref: #menu13141 -Node: Cash accounts13336 -Ref: #cash-accounts13478 -Node: Balance sheet accounts13662 -Ref: #balance-sheet-accounts13843 -Node: Income statement accounts13963 -Ref: #income-statement-accounts14149 -Node: All accounts14313 -Ref: #all-accounts14459 -Node: Register14641 -Ref: #register14765 -Node: Transaction16727 -Ref: #transaction16850 -Node: Error18267 -Ref: #error18361 -Node: TIPS18605 -Ref: #tips18704 -Node: Watch mode18746 -Ref: #watch-mode18853 -Node: Debug output20312 -Ref: #debug-output20423 -Node: ENVIRONMENT20635 -Ref: #environment20745 -Node: BUGS20936 -Ref: #bugs21019 +Node: General help options2959 +Ref: #general-help-options3108 +Node: General input options3390 +Ref: #general-input-options3575 +Node: General reporting options4277 +Ref: #general-reporting-options4441 +Node: MOUSE7831 +Ref: #mouse7926 +Node: KEYS8163 +Ref: #keys8256 +Node: SCREENS12769 +Ref: #screens12867 +Node: Menu13447 +Ref: #menu13540 +Node: Cash accounts13735 +Ref: #cash-accounts13877 +Node: Balance sheet accounts14061 +Ref: #balance-sheet-accounts14242 +Node: Income statement accounts14362 +Ref: #income-statement-accounts14548 +Node: All accounts14712 +Ref: #all-accounts14858 +Node: Register15040 +Ref: #register15164 +Node: Transaction17126 +Ref: #transaction17249 +Node: Error18666 +Ref: #error18760 +Node: TIPS19004 +Ref: #tips19103 +Node: Watch mode19145 +Ref: #watch-mode19252 +Node: Debug output20711 +Ref: #debug-output20822 +Node: ENVIRONMENT21034 +Ref: #environment21144 +Node: BUGS21335 +Ref: #bugs21418  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index a37e58bba..2cc8d4cb2 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -38,12 +38,11 @@ DESCRIPTION enable "forecast mode". OPTIONS - Note: if invoking hledger-ui as a hledger subcommand, write -- before - options as shown above. - - Any QUERYARGS are interpreted as a hledger search query which filters + Any QUERYARGS are interpreted as a hledger search query which filters the data. + hledger-ui provides the following options: + -w --watch watch for data and date changes and reload automatically @@ -64,7 +63,7 @@ OPTIONS start in the (first) matched account's register screen --change - show period balances (changes) at startup instead of historical + show period balances (changes) at startup instead of historical balances -l --flat @@ -73,8 +72,24 @@ OPTIONS -t --tree show accounts as a tree - hledger input options: + hledger-ui also supports many of hledger's general options (and the + hledger manual's command line tips also apply here): + General help options + -h --help + show general or COMMAND help + + --man show general or COMMAND user manual with man + + --info show general or COMMAND user manual with info + + --version + show general or ADDONCMD version + + --debug[=N] + show debug output (levels 1-9, default: 1) + + General input options -f FILE --file=FILE use a different input file. For stdin, use - (default: $LEDGER_FILE or $HOME/.hledger.journal) @@ -102,8 +117,7 @@ OPTIONS do extra error checking (check that all posted accounts are de- clared) - hledger reporting options: - + General reporting options -b --begin=DATE include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval) @@ -218,25 +232,6 @@ OPTIONS Some reporting options can also be written as query arguments. - hledger help options: - - -h --help - show general or COMMAND help - - --man show general or COMMAND user manual with man - - --info show general or COMMAND user manual with info - - --version - show general or ADDONCMD version - - --debug[=N] - show debug output (levels 1-9, default: 1) - - A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, - insert a -- argument before.) - MOUSE In most modern terminals, you can navigate through the screens with a mouse or touchpad: diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index e52950275..9ebb3ac81 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -76,8 +76,7 @@ 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 -Note: if invoking hledger-web as a hledger subcommand, write -\f[V]--\f[R] before options, as shown in the synopsis above. +hledger-web provides the following options: .TP \f[V]--serve\f[R] serve and log requests, don\[aq]t browse or auto-exit after timeout @@ -122,7 +121,64 @@ X-Sandstorm-Permissions (default: disabled) run hledger-web\[aq]s tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help .PP -hledger input options: +By default the server listens on IP address 127.0.0.1, accessible only +to local requests. +You can use \f[V]--host\f[R] to change this, eg \f[V]--host 0.0.0.0\f[R] +to listen on all configured addresses. +.PP +Similarly, use \f[V]--port\f[R] to set a TCP port other than 5000, eg if +you are running multiple hledger-web instances. +.PP +Both of these options are ignored when \f[V]--socket\f[R] is used. +In this case, it creates an \f[V]AF_UNIX\f[R] socket file at the +supplied path and uses that for communication. +This is an alternative way of running multiple hledger-web instances +behind a reverse proxy that handles authentication for different users. +The path can be derived in a predictable way, eg by using the username +within the path. +As an example, \f[V]nginx\f[R] as reverse proxy can use the variable +\f[V]$remote_user\f[R] to derive a path from the username used in a HTTP +basic authentication. +The following \f[V]proxy_pass\f[R] directive allows access to all +\f[V]hledger-web\f[R] instances that created a socket in +\f[V]/tmp/hledger/\f[R]: +.IP +.nf +\f[C] + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; +\f[R] +.fi +.PP +You can use \f[V]--base-url\f[R] to change the protocol, hostname, port +and path that appear in hyperlinks, useful eg for integrating +hledger-web within a larger website. +The default is \f[V]http://HOST:PORT/\f[R] using the server\[aq]s +configured host address and TCP port (or \f[V]http://HOST\f[R] if PORT +is 80). +.PP +With \f[V]--file-url\f[R] you can set a different base url for static +files, eg for better caching or cookie-less serving on high performance +websites. +.PP +hledger-web also supports many of hledger\[aq]s general options (and the +hledger manual\[aq]s command line tips also apply here): +.SS General help options +.TP +\f[V]-h --help\f[R] +show general or COMMAND help +.TP +\f[V]--man\f[R] +show general or COMMAND user manual with man +.TP +\f[V]--info\f[R] +show general or COMMAND user manual with info +.TP +\f[V]--version\f[R] +show general or ADDONCMD version +.TP +\f[V]--debug[=N]\f[R] +show debug output (levels 1-9, default: 1) +.SS General input options .TP \f[V]-f FILE --file=FILE\f[R] use a different input file. @@ -150,8 +206,7 @@ assignments) .TP \f[V]-s --strict\f[R] do extra error checking (check that all posted accounts are declared) -.PP -hledger reporting options: +.SS General reporting options .TP \f[V]-b --begin=DATE\f[R] include postings/txns on or after this date (will be adjusted to @@ -267,66 +322,6 @@ When a reporting option appears more than once in the command line, the last one takes precedence. .PP Some reporting options can also be written as query arguments. -.PP -hledger help options: -.TP -\f[V]-h --help\f[R] -show general or COMMAND help -.TP -\f[V]--man\f[R] -show general or COMMAND user manual with man -.TP -\f[V]--info\f[R] -show general or COMMAND user manual with info -.TP -\f[V]--version\f[R] -show general or ADDONCMD version -.TP -\f[V]--debug[=N]\f[R] -show debug output (levels 1-9, default: 1) -.PP -A \[at]FILE argument will be expanded to the contents of FILE, which -should contain one command line option/argument per line. -(To prevent this, insert a \f[V]--\f[R] argument before.) -.PP -By default the server listens on IP address 127.0.0.1, accessible only -to local requests. -You can use \f[V]--host\f[R] to change this, eg \f[V]--host 0.0.0.0\f[R] -to listen on all configured addresses. -.PP -Similarly, use \f[V]--port\f[R] to set a TCP port other than 5000, eg if -you are running multiple hledger-web instances. -.PP -Both of these options are ignored when \f[V]--socket\f[R] is used. -In this case, it creates an \f[V]AF_UNIX\f[R] socket file at the -supplied path and uses that for communication. -This is an alternative way of running multiple hledger-web instances -behind a reverse proxy that handles authentication for different users. -The path can be derived in a predictable way, eg by using the username -within the path. -As an example, \f[V]nginx\f[R] as reverse proxy can use the variable -\f[V]$remote_user\f[R] to derive a path from the username used in a HTTP -basic authentication. -The following \f[V]proxy_pass\f[R] directive allows access to all -\f[V]hledger-web\f[R] instances that created a socket in -\f[V]/tmp/hledger/\f[R]: -.IP -.nf -\f[C] - proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; -\f[R] -.fi -.PP -You can use \f[V]--base-url\f[R] to change the protocol, hostname, port -and path that appear in hyperlinks, useful eg for integrating -hledger-web within a larger website. -The default is \f[V]http://HOST:PORT/\f[R] using the server\[aq]s -configured host address and TCP port (or \f[V]http://HOST\f[R] if PORT -is 80). -.PP -With \f[V]--file-url\f[R] you can set a different base url for static -files, eg for better caching or cookie-less serving on high performance -websites. .SH PERMISSIONS .PP By default, hledger-web allows anyone who can reach it to view the diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 3ed4083d9..d25b9666b 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -81,8 +81,7 @@ Command-line options and arguments may be used to set an initial filter on the data. These filter options are not shown in the web UI, but it will be applied in addition to any search query entered there. - Note: if invoking hledger-web as a hledger subcommand, write '--' -before options, as shown in the synopsis above. + hledger-web provides the following options: '--serve' @@ -126,7 +125,72 @@ before options, as shown in the synopsis above. run hledger-web's tests and exit. hspec test runner args may follow a -, eg: hledger-web -test - -help - hledger input options: + By default the server listens on IP address 127.0.0.1, accessible +only to local requests. You can use '--host' to change this, eg '--host +0.0.0.0' to listen on all configured addresses. + + Similarly, use '--port' to set a TCP port other than 5000, eg if you +are running multiple hledger-web instances. + + Both of these options are ignored when '--socket' is used. In this +case, it creates an 'AF_UNIX' socket file at the supplied path and uses +that for communication. This is an alternative way of running multiple +hledger-web instances behind a reverse proxy that handles authentication +for different users. The path can be derived in a predictable way, eg +by using the username within the path. As an example, 'nginx' as +reverse proxy can use the variable '$remote_user' to derive a path from +the username used in a HTTP basic authentication. The following +'proxy_pass' directive allows access to all 'hledger-web' instances that +created a socket in '/tmp/hledger/': + + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; + + You can use '--base-url' to change the protocol, hostname, port and +path that appear in hyperlinks, useful eg for integrating hledger-web +within a larger website. The default is 'http://HOST:PORT/' using the +server's configured host address and TCP port (or 'http://HOST' if PORT +is 80). + + With '--file-url' you can set a different base url for static files, +eg for better caching or cookie-less serving on high performance +websites. + + hledger-web also supports many of hledger's general options (and the +hledger manual's command line tips also apply here): + +* Menu: + +* General help options:: +* General input options:: +* General reporting options:: + + +File: hledger-web.info, Node: General help options, Next: General input options, Up: OPTIONS + +1.1 General help options +======================== + +'-h --help' + + show general or COMMAND help +'--man' + + show general or COMMAND user manual with man +'--info' + + show general or COMMAND user manual with info +'--version' + + show general or ADDONCMD version +'--debug[=N]' + + show debug output (levels 1-9, default: 1) + + +File: hledger-web.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: OPTIONS + +1.2 General input options +========================= '-f FILE --file=FILE' @@ -156,7 +220,11 @@ before options, as shown in the synopsis above. do extra error checking (check that all posted accounts are declared) - hledger reporting options: + +File: hledger-web.info, Node: General reporting options, Prev: General input options, Up: OPTIONS + +1.3 General reporting options +============================= '-b --begin=DATE' @@ -273,58 +341,6 @@ the last one takes precedence. Some reporting options can also be written as query arguments. - hledger help options: - -'-h --help' - - show general or COMMAND help -'--man' - - show general or COMMAND user manual with man -'--info' - - show general or COMMAND user manual with info -'--version' - - show general or ADDONCMD version -'--debug[=N]' - - show debug output (levels 1-9, default: 1) - - A @FILE argument will be expanded to the contents of FILE, which -should contain one command line option/argument per line. (To prevent -this, insert a '--' argument before.) - - By default the server listens on IP address 127.0.0.1, accessible -only to local requests. You can use '--host' to change this, eg '--host -0.0.0.0' to listen on all configured addresses. - - Similarly, use '--port' to set a TCP port other than 5000, eg if you -are running multiple hledger-web instances. - - Both of these options are ignored when '--socket' is used. In this -case, it creates an 'AF_UNIX' socket file at the supplied path and uses -that for communication. This is an alternative way of running multiple -hledger-web instances behind a reverse proxy that handles authentication -for different users. The path can be derived in a predictable way, eg -by using the username within the path. As an example, 'nginx' as -reverse proxy can use the variable '$remote_user' to derive a path from -the username used in a HTTP basic authentication. The following -'proxy_pass' directive allows access to all 'hledger-web' instances that -created a socket in '/tmp/hledger/': - - proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; - - You can use '--base-url' to change the protocol, hostname, port and -path that appear in hyperlinks, useful eg for integrating hledger-web -within a larger website. The default is 'http://HOST:PORT/' using the -server's configured host address and TCP port (or 'http://HOST' if PORT -is 80). - - With '--file-url' you can set a different base url for static files, -eg for better caching or cookie-less serving on high performance -websites. -  File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top @@ -634,22 +650,28 @@ Tag Table: Node: Top225 Node: OPTIONS2702 Ref: #options2807 -Node: PERMISSIONS10607 -Ref: #permissions10746 -Node: EDITING UPLOADING DOWNLOADING11958 -Ref: #editing-uploading-downloading12139 -Node: RELOADING12973 -Ref: #reloading13107 -Node: JSON API13540 -Ref: #json-api13655 -Node: DEBUG OUTPUT19143 -Ref: #debug-output19268 -Node: Debug output19295 -Ref: #debug-output-119396 -Node: ENVIRONMENT19813 -Ref: #environment19932 -Node: BUGS20049 -Ref: #bugs20133 +Node: General help options6118 +Ref: #general-help-options6268 +Node: General input options6550 +Ref: #general-input-options6736 +Node: General reporting options7438 +Ref: #general-reporting-options7603 +Node: PERMISSIONS10993 +Ref: #permissions11132 +Node: EDITING UPLOADING DOWNLOADING12344 +Ref: #editing-uploading-downloading12525 +Node: RELOADING13359 +Ref: #reloading13493 +Node: JSON API13926 +Ref: #json-api14041 +Node: DEBUG OUTPUT19529 +Ref: #debug-output19654 +Node: Debug output19681 +Ref: #debug-output-119782 +Node: ENVIRONMENT20199 +Ref: #environment20318 +Node: BUGS20435 +Ref: #bugs20519  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 2fcb6fa40..0347e4d3e 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -60,14 +60,13 @@ OPTIONS on the data. These filter options are not shown in the web UI, but it will be applied in addition to any search query entered there. - Note: if invoking hledger-web as a hledger subcommand, write -- before - options, as shown in the synopsis above. + 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 + like --serve, but serve only the JSON web API, without the server-side web UI --host=IPADDR @@ -77,34 +76,78 @@ OPTIONS 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- + 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 + 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 + normally serves static files itself, but if you wanted to serve + them from another server for efficiency, you would set the url with this. --capabilities=CAP[,CAP..] - enable the view, add, and/or manage capabilities (default: + enable the view, add, and/or manage capabilities (default: view,add) --capabilities-header=HTTPHEADER - read capabilities to enable from a HTTP header, like X-Sand- + read capabilities to enable from a HTTP header, like X-Sand- storm-Permissions (default: disabled) - --test run hledger-web's tests and exit. hspec test runner args may + --test run hledger-web's tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help - hledger input options: + By default the server listens on IP address 127.0.0.1, accessible only + to local requests. You can use --host to change this, eg --host + 0.0.0.0 to listen on all configured addresses. + Similarly, use --port to set a TCP port other than 5000, eg if you are + running multiple hledger-web instances. + + Both of these options are ignored when --socket is used. In this case, + it creates an AF_UNIX socket file at the supplied path and uses that + for communication. This is an alternative way of running multiple + hledger-web instances behind a reverse proxy that handles authentica- + tion for different users. The path can be derived in a predictable + way, eg by using the username within the path. As an example, nginx as + reverse proxy can use the variable $remote_user to derive a path from + the username used in a HTTP basic authentication. The following + proxy_pass directive allows access to all hledger-web instances that + created a socket in /tmp/hledger/: + + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; + + You can use --base-url to change the protocol, hostname, port and path + that appear in hyperlinks, useful eg for integrating hledger-web within + a larger website. The default is http://HOST:PORT/ using the server's + configured host address and TCP port (or http://HOST if PORT is 80). + + With --file-url you can set a different base url for static files, eg + for better caching or cookie-less serving on high performance websites. + + hledger-web also supports many of hledger's general options (and the + hledger manual's command line tips also apply here): + + General help options + -h --help + show general or COMMAND help + + --man show general or COMMAND user manual with man + + --info show general or COMMAND user manual with info + + --version + show general or ADDONCMD version + + --debug[=N] + show debug output (levels 1-9, default: 1) + + General input options -f FILE --file=FILE use a different input file. For stdin, use - (default: $LEDGER_FILE or $HOME/.hledger.journal) @@ -132,8 +175,7 @@ OPTIONS do extra error checking (check that all posted accounts are de- clared) - hledger reporting options: - + General reporting options -b --begin=DATE include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval) @@ -248,53 +290,6 @@ OPTIONS Some reporting options can also be written as query arguments. - hledger help options: - - -h --help - show general or COMMAND help - - --man show general or COMMAND user manual with man - - --info show general or COMMAND user manual with info - - --version - show general or ADDONCMD version - - --debug[=N] - show debug output (levels 1-9, default: 1) - - A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, - insert a -- argument before.) - - By default the server listens on IP address 127.0.0.1, accessible only - to local requests. You can use --host to change this, eg --host - 0.0.0.0 to listen on all configured addresses. - - Similarly, use --port to set a TCP port other than 5000, eg if you are - running multiple hledger-web instances. - - Both of these options are ignored when --socket is used. In this case, - it creates an AF_UNIX socket file at the supplied path and uses that - for communication. This is an alternative way of running multiple - hledger-web instances behind a reverse proxy that handles authentica- - tion for different users. The path can be derived in a predictable - way, eg by using the username within the path. As an example, nginx as - reverse proxy can use the variable $remote_user to derive a path from - the username used in a HTTP basic authentication. The following - proxy_pass directive allows access to all hledger-web instances that - created a socket in /tmp/hledger/: - - proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; - - You can use --base-url to change the protocol, hostname, port and path - that appear in hyperlinks, useful eg for integrating hledger-web within - a larger website. The default is http://HOST:PORT/ using the server's - configured host address and TCP port (or http://HOST if PORT is 80). - - With --file-url you can set a different base url for static files, eg - for better caching or cookie-less serving on high performance websites. - PERMISSIONS 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. diff --git a/hledger/hledger.1 b/hledger/hledger.1 index a979cd2ac..388ef1825 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -130,63 +130,19 @@ Files are most often in hledger\[aq]s journal format, with the \f[V].journal\f[R] file extension (\f[V].hledger\f[R] or \f[V].j\f[R] also work); these files describe transactions, like an accounting general journal. -Some other supported file formats are discussed below. .PP -When no \f[V]-f\f[R] option is given, hledger looks for the file -specified by the \f[V]LEDGER_FILE\f[R] environment variable; if this is -not set, it uses \f[V].hledger.journal\f[R] in your home directory. +When no file is specified, hledger looks for \f[V].hledger.journal\f[R] +in your home directory. .PP -Most people prefer to keep financial files in a dedicated folder, +But most people prefer to keep financial files in a dedicated folder, perhaps with version control. -Also, starting a new journal file per year is common (it\[aq]s not +Also, starting a new journal file each year is common (it\[aq]s not required, but helps keep things fast and organised). -So we usually set \f[V]LEDGER_FILE\f[R], to something like +So we usually configure a different journal file, by setting the +\f[V]LEDGER_FILE\f[R] environment variable, to something like \f[V]\[ti]/finance/2023.journal\f[R]. -.SS Setting LEDGER_FILE -.PP -How to set \f[V]LEDGER_FILE\f[R] permanently depends on your platform: -.PP -On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: -.IP -.nf -\f[C] -$ mkdir -p \[ti]/finance -$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[ga] >> \[ti]/.profile -$ source \[ti]/.profile -\f[R] -.fi -.PP -When correctly configured, in a new terminal window -\f[V]env | grep LEDGER_FILE\f[R] will show your file, and so will -\f[V]hledger files\f[R]. -.PP -On mac, this additional step might be helpful for GUI applications (like -Emacs started from the dock): add an entry to -\f[V]\[ti]/.MacOSX/environment.plist\f[R] like -.IP -.nf -\f[C] -{ - \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq] -} -\f[R] -.fi -.PP -and then run \f[V]killall Dock\f[R] in a terminal window (or restart the -machine). -.PP -On Windows, see https://www.java.com/en/download/help/path.html, or try -running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): -.IP -.nf -\f[C] -> CD -> MKDIR finance -> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq] -\f[R] -.fi +For more about how to do that on your system, see Common tasks > Setting +LEDGER_FILE. .SS Data formats .PP Usually the data file is in hledger\[aq]s journal format, but it can be @@ -314,33 +270,67 @@ Are all commodity conversions declared explicitly ? .PP You can use the check command to run individual checks -- the ones listed above and some more. -.SH Environment +.SH Commands .PP -Environment variables which affect hledger: +hledger provides various subcommands for getting things done. +Most of these commands do not change the journal file; they just read it +and output a report. +A few commands assist with adding data and file management. .PP -\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger -commands (\f[V]register\f[R]) will format their output to this width. -If not set, they will try to use the available terminal width. +To show the commands list, run \f[V]hledger\f[R] with no arguments. +The commands are described in detail in PART 4: COMMANDS, below. .PP -\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified -with \f[V]-f/--file\f[R]. -Default: \f[V]$HOME/.hledger.journal\f[R]. +To use a particular command, run +\f[V]hledger CMD [CMDOPTS] [CMDARGS]\f[R], +.IP \[bu] 2 +CMD is the full command name, or its standard abbreviation shown in the +commands list, or any unambiguous prefix of the name. +.IP \[bu] 2 +CMDOPTS are command-specific options, if any. +Command-specific options must be written after the command name. +Eg: \f[V]hledger print -x\f[R]. +.IP \[bu] 2 +CMDARGS are additional arguments to the command, if any. +Most hledger commands accept arguments representing a query, to limit +the data in some way. +Eg: \f[V]hledger reg assets:checking\f[R]. .PP -\f[B]NO_COLOR\f[R] If this environment variable is set (with any value), -hledger will not use ANSI color codes in terminal output, unless -overridden by an explicit \f[V]--color/--colour\f[R] option. +To list a command\[aq]s options, arguments, and documentation in the +terminal, run \f[V]hledger CMD -h\f[R]. +Eg: \f[V]hledger bal -h\f[R]. +.SS Add-on commands +.PP +In addition to the built-in commands, you can install \f[I]add-on +commands\f[R]: programs or scripts named \[dq]hledger-SOMETHING\[dq], +which will also appear in hledger\[aq]s commands list. +If you used the hledger-install script, you will have several add-ons +installed already. +Some more can be found in hledger\[aq]s bin/ directory, documented at +https://hledger.org/scripts.html. +.PP +More precisely, add-on commands are programs or scripts in your +shell\[aq]s PATH, whose name starts with \[dq]hledger-\[dq] and ends +with no extension or a recognised extension (\[dq].bat\[dq], +\[dq].com\[dq], \[dq].exe\[dq], \[dq].hs\[dq], \[dq].js\[dq], +\[dq].lhs\[dq], \[dq].lua\[dq], \[dq].php\[dq], \[dq].pl\[dq], +\[dq].py\[dq], \[dq].rb\[dq], \[dq].rkt\[dq], or \[dq].sh\[dq]), and (on +unix and mac) which has executable permission for the current user. +.PP +You can run add-on commands using hledger, much like built-in commands: +\f[V]hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]\f[R]. +But note the double hyphen argument, required before add-on-specific +options. +Eg: \f[V]hledger ui -- --watch\f[R] or \f[V]hledger web -- --serve\f[R]. +If this causes difficulty, you can always run the add-on directly, +without using \f[V]hledger\f[R]: \f[V]hledger-ui --watch\f[R] or +\f[V]hledger-web --serve\f[R]. .SH Options .PP -Here is a list of flags and options common to most hledger commands, and -some useful details about hledger command line parsing. -But if you are new to hledger, feel free to skim/skip ahead to the -Commands. -.SS General options -.PP -To see general usage help, including general options which are supported -by most hledger commands, run \f[V]hledger -h\f[R]. -.PP -General help options: +Run \f[V]hledger -h\f[R] to see general command line help, and general +options which are common to most hledger commands. +These options can be written anywhere on the command line. +They can be grouped into help, input, and reporting options: +.SS General help options .TP \f[V]-h --help\f[R] show general or COMMAND help @@ -356,8 +346,7 @@ show general or ADDONCMD version .TP \f[V]--debug[=N]\f[R] show debug output (levels 1-9, default: 1) -.PP -General input options: +.SS General input options .TP \f[V]-f FILE --file=FILE\f[R] use a different input file. @@ -385,8 +374,7 @@ assignments) .TP \f[V]-s --strict\f[R] do extra error checking (check that all posted accounts are declared) -.PP -General reporting options: +.SS General reporting options .TP \f[V]-b --begin=DATE\f[R] include postings/txns on or after this date (will be adjusted to @@ -502,6 +490,11 @@ When a reporting option appears more than once in the command line, the last one takes precedence. .PP Some reporting options can also be written as query arguments. +.SH Command line tips +.PP +Here are some details useful to know about for hledger command lines +(and elsewhere). +Feel free to skip this section until you need it. .SS Option repetition .PP If options are repeated in a command line, hledger will generally use @@ -511,74 +504,6 @@ Some of the boolean flags will toggle if repeated; these include: \f[V]-%/--percent\f[R], \f[V]-E/--empty\f[R], \f[V]-N/--no-total\f[R], \f[V]-T/--row-total\f[R], \f[V]-A/--average\f[R], and \f[V]-S/--sort-amount\f[R]. -.SS Command options -.PP -To see options for a particular command, including command-specific -options, run: \f[V]hledger COMMAND -h\f[R]. -.PP -Command-specific options must be written after the command name, eg: -\f[V]hledger print -x\f[R]. -.PP -Additionally, if the command is an add-on, you may need to put its -options after a double-hyphen, eg: \f[V]hledger ui -- --watch\f[R]. -Or, you can run the add-on executable directly: -\f[V]hledger-ui --watch\f[R]. -.SS Command arguments -.PP -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. -.PP -You can save a set of command line options/arguments in a file, and then -reuse them by writing \f[V]\[at]FILENAME\f[R] as a command line -argument. -Eg: \f[V]hledger bal \[at]foo.args\f[R]. -(To prevent this, eg if you have an argument that begins with a literal -\f[V]\[at]\f[R], precede it with \f[V]--\f[R], eg: -\f[V]hledger bal -- \[at]ARG\f[R]). -.PP -Inside the argument file, each line should contain just one option or -argument. -Avoid the use of spaces, except inside quotes (or you\[aq]ll see a -confusing error). -Between a flag and its argument, use = (or nothing). -Bad: -.IP -.nf -\f[C] -assets depth:2 --X USD -\f[R] -.fi -.PP -Good: -.IP -.nf -\f[C] -assets -depth:2 --X=USD -\f[R] -.fi -.PP -For special characters (see below), use one less level of quoting than -you would at the command prompt. -Bad: -.IP -.nf -\f[C] --X\[dq]$\[dq] -\f[R] -.fi -.PP -Good: -.IP -.nf -\f[C] --X$ -\f[R] -.fi -.PP -See also: Save frequently used options. .SS Special characters .SS Single escaping (shell metacharacters) .PP @@ -794,70 +719,54 @@ Eg to search for amounts with the dollar sign in hledger-web, write On the command line, some metacharacters like \f[V]$\f[R] have a special meaning to the shell and so must be escaped at least once more. See Special characters. -.SH Commands +.SS Argument files .PP -hledger provides a number of built-in subcommands (described below). -Most of these read your data without changing it, and display a report. -A few assist with data entry and management. +You can save a set of command line options and arguments in a file, and +then reuse them by writing \f[V]\[at]FILENAME\f[R] as a command line +argument. +Eg: \f[V]hledger bal \[at]foo.args\f[R]. .PP -Run \f[V]hledger\f[R] with no arguments to list the commands available, -and \f[V]hledger CMD\f[R] to run a command. -CMD can be the full command name, or its standard abbreviation shown in -the commands list, or any unambiguous prefix of the name. -Eg: \f[V]hledger bal\f[R]. -.SS Add-on commands -.PP -Add-on commands are extra subcommands provided by programs or scripts in -your PATH -.IP \[bu] 2 -whose name starts with \f[V]hledger-\f[R] -.IP \[bu] 2 -whose name ends with a recognised file extension: -\f[V].bat\f[R],\f[V].com\f[R],\f[V].exe\f[R], -\f[V].hs\f[R],\f[V].lhs\f[R],\f[V].pl\f[R],\f[V].py\f[R],\f[V].rb\f[R],\f[V].rkt\f[R],\f[V].sh\f[R] -or none -.IP \[bu] 2 -and (on unix, mac) which are executable by the current user. -.PP -Addons can be written in any language, but haskell scripts or programs -have a big advantage: they can use hledger\[aq]s library code, for -command-line options, parsing and reporting. -.PP -Several add-on commands are installed by the hledger-install script. -See https://hledger.org/scripts.html for more details. -.PP -Note in a hledger command line, add-on command flags must have a double -dash (\f[V]--\f[R]) preceding them. -Eg you must write: +Inside the argument file, each line should contain just one option or +argument. +Also, don\[aq]t use spaces except inside quotes (or you\[aq]ll see a +confusing error). +Ie, write = (or nothing) between a flag and its argument. +Eg, bad: .IP .nf \f[C] -$ hledger web -- --serve +assets -X USD \f[R] .fi .PP -and not: +Good: .IP .nf \f[C] -$ hledger web --serve +assets +-X=USD \f[R] .fi .PP -(because the \f[V]--serve\f[R] flag belongs to \f[V]hledger-web\f[R], -not \f[V]hledger\f[R]). -.PP -The \f[V]-h/--help\f[R] and \f[V]--version\f[R] flags don\[aq]t require -\f[V]--\f[R]. -.PP -If you have any trouble with this, remember you can always run the -add-on program directly, eg: +For the special characters mentioned above, use one less level of +quoting than you would at the command prompt. +Eg, bad: .IP .nf \f[C] -$ hledger-web --serve +-X\[dq]$\[dq] \f[R] .fi +.PP +Good: +.IP +.nf +\f[C] +-X$ +\f[R] +.fi +.PP +See also: Save frequently used options. .SH Output .SS Output destination .PP @@ -1182,6 +1091,21 @@ stderr, eg: hledger bal --debug=3 2>hledger.log \f[R] .fi +.SH Environment +.PP +These environment variables affect hledger: +.PP +\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger +commands (\f[V]register\f[R]) will format their output to this width. +If not set, they will try to use the available terminal width. +.PP +\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified +with \f[V]-f/--file\f[R]. +Default: \f[V]$HOME/.hledger.journal\f[R]. +.PP +\f[B]NO_COLOR\f[R] If this environment variable is set (with any value), +hledger will not use ANSI color codes in terminal output, unless +overridden by an explicit \f[V]--color/--colour\f[R] option. .SH PART 2: DATA FORMATS .PP .SH Journal @@ -2965,7 +2889,7 @@ Including the aliases doesn\[aq]t work either: \f[C] include a.aliases -2020-01-01 ; not affected by a.aliases +2023-01-01 ; not affected by a.aliases foo 1 bar \f[R] @@ -2979,7 +2903,7 @@ of your top-most file, like this: alias foo=Foo alias bar=Bar -2020-01-01 ; affected by aliases above +2023-01-01 ; affected by aliases above foo 1 bar @@ -3214,7 +3138,7 @@ including directories, but this can be done, eg: .PP The path may also be prefixed to force a specific file format, overriding the file extension (as described in hledger.1 -> Input -files): \f[V]include timedot:\[ti]/notes/2020*.md\f[R]. +files): \f[V]include timedot:\[ti]/notes/2023*.md\f[R]. .SS \f[V]P\f[R] directive .PP The \f[V]P\f[R] directive declares a market price, which is a conversion @@ -3326,8 +3250,8 @@ cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it\[aq]s a bit inconsistent with the above.) -Eg: \f[V]\[ti] every 10th day of month from 2020/01\f[R], which is -equivalent to \f[V]\[ti] every 10th day of month from 2020/01/01\f[R], +Eg: \f[V]\[ti] every 10th day of month from 2023/01\f[R], which is +equivalent to \f[V]\[ti] every 10th day of month from 2023/01/01\f[R], will be adjusted to start on 2019/12/10. .SS Periodic rule syntax .PP @@ -3381,10 +3305,10 @@ example: .IP .nf \f[C] -; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2020\[dq] +; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2023\[dq] ; || ; vv -\[ti] every 2 months in 2020, we will review +\[ti] every 2 months in 2023, we will review assets:bank:checking $1500 income:acme inc \f[R] @@ -4679,7 +4603,7 @@ So for example, when reading an SSV file, if the original record was: .IP .nf \f[C] -2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000 +2023-01-01; \[dq]Acme, Inc.\[dq]; 1,000 \f[R] .fi .PP @@ -4687,7 +4611,7 @@ the regex would see, and try to match, this modified record text: .IP .nf \f[C] -2020-01-01,Acme, Inc., 1,000 +2023-01-01,Acme, Inc., 1,000 \f[R] .fi .PP @@ -4757,7 +4681,7 @@ Example: if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, -2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out +2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out \f[R] .fi .SS \f[V]balance-type\f[R] @@ -5129,7 +5053,7 @@ field(s): .IP .nf \f[C] -2020-01-01,foo,$123.00 +2023-01-01,foo,$123.00 \f[R] .fi .PP @@ -5145,7 +5069,7 @@ fields date,description,amount .IP .nf \f[C] -2020-01-01 foo +2023-01-01 foo expenses:unknown $123.00 income:unknown $-123.00 \f[R] @@ -5155,7 +5079,7 @@ If the currency is provided as a separate CSV field: .IP .nf \f[C] -2020-01-01,foo,USD,123.00 +2023-01-01,foo,USD,123.00 \f[R] .fi .PP @@ -5171,7 +5095,7 @@ fields date,description,currency,amount .IP .nf \f[C] -2020-01-01 foo +2023-01-01 foo expenses:unknown USD123.00 income:unknown USD-123.00 \f[R] @@ -5190,7 +5114,7 @@ amount %amt %cur .IP .nf \f[C] -2020-01-01 foo +2023-01-01 foo expenses:unknown 123.00 USD income:unknown -123.00 USD \f[R] @@ -5835,7 +5759,7 @@ biz:research 1 .nf \f[C] * Time log -** 2020-01-01 +** 2023-01-01 *** adm:time . *** adm:finance . \f[R] @@ -5843,9 +5767,9 @@ biz:research 1 .IP .nf \f[C] -* 2020 Work Diary +* 2023 Work Diary ** Q1 -*** 2020-02-29 +*** 2023-02-29 **** DONE 0700 yoga **** UNPLANNED @@ -6474,7 +6398,7 @@ Regular expressions are also supported: Add a query type prefix to match other parts of the data: .RS 2 .PP -\f[V]date:202012- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R] +\f[V]date:202312- desc:amazon cur:USD amt:\[dq]>100\[dq] status:\f[R] .RE .IP \[bu] 2 Add a \f[V]not:\f[R] prefix to negate a term: @@ -6683,7 +6607,7 @@ above) .PP Some queries can also be expressed as command-line options: \f[V]depth:2\f[R] is equivalent to \f[V]--depth 2\f[R], -\f[V]date:2020\f[R] is equivalent to \f[V]-p 2020\f[R], etc. +\f[V]date:2023\f[R] is equivalent to \f[V]-p 2023\f[R], etc. When you mix command options and query arguments, generally the resulting query is their intersection. .SS Queries and valuation @@ -11608,7 +11532,7 @@ Or, specify an existing journal file with -f or LEDGER_FILE. .fi .PP You can override this by setting the \f[V]LEDGER_FILE\f[R] environment -variable. +variable (see below). It\[aq]s a good practice to keep this important file under version control, and to start a new file each year. So you could do something like this: @@ -11619,11 +11543,11 @@ $ mkdir \[ti]/finance $ cd \[ti]/finance $ git init Initialized empty Git repository in /Users/simon/finance/.git/ -$ touch 2020.journal -$ echo \[dq]export LEDGER_FILE=$HOME/finance/2020.journal\[dq] >> \[ti]/.bashrc -$ source \[ti]/.bashrc +$ touch 2023.journal +$ echo \[dq]export LEDGER_FILE=$HOME/finance/2023.journal\[dq] >> \[ti]/.profile +$ source \[ti]/.profile $ hledger stats -Main file : /Users/simon/finance/2020.journal +Main file : /Users/simon/finance/2023.journal Included files : Transactions span : to (0 days) Last transaction : none @@ -11636,6 +11560,50 @@ Commodities : 0 () Market prices : 0 () \f[R] .fi +.SS Setting LEDGER_FILE +.PP +How to set \f[V]LEDGER_FILE\f[R] permanently depends on your setup: +.PP +On unix and mac, running these commands in the terminal will work for +many people; adapt as needed: +.IP +.nf +\f[C] +$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[ga] >> \[ti]/.profile +$ source \[ti]/.profile +\f[R] +.fi +.PP +When correctly configured, in a new terminal window +\f[V]env | grep LEDGER_FILE\f[R] will show your file, and so will +\f[V]hledger files\f[R]. +.PP +On mac, this additional step might be helpful for GUI applications (like +Emacs started from the dock): add an entry to +\f[V]\[ti]/.MacOSX/environment.plist\f[R] like +.IP +.nf +\f[C] +{ + \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq] +} +\f[R] +.fi +.PP +and then run \f[V]killall Dock\f[R] in a terminal window (or restart the +machine). +.PP +On Windows, see https://www.java.com/en/download/help/path.html, or try +running these commands in a powershell window (let us know if it +persists across a reboot, and if you need to be an Administrator): +.IP +.nf +\f[C] +> CD +> MKDIR finance +> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq] +\f[R] +.fi .SS Setting opening balances .PP Pick a starting date for which you can look up the balances of some @@ -11658,7 +11626,7 @@ like this: .IP .nf \f[C] -2020-01-01 * opening balances +2023-01-01 * opening balances assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 @@ -11687,7 +11655,7 @@ record a similar transaction: .nf \f[C] $ hledger add -Adding transactions to journal file /Users/simon/finance/2020.journal +Adding transactions to journal file /Users/simon/finance/2023.journal Any command line arguments will be used as defaults. Use tab key to complete, readline keys to edit, enter to accept defaults. An optional (CODE) may follow transaction dates. @@ -11695,7 +11663,7 @@ An optional ; COMMENT may follow descriptions or amounts. If you make a mistake, enter < at any prompt to go one step backward. To end a transaction, enter . when prompted. To quit, enter . at a date prompt or press control-d or control-c. -Date [2020-02-07]: 2020-01-01 +Date [2023-02-07]: 2023-01-01 Description: * opening balances Account 1: assets:bank:checking Amount 1: $1000 @@ -11708,7 +11676,7 @@ Amount 4 [$-3100]: $-50 Account 5: equity:opening/closing balances Amount 5 [$-3050]: Account 6 (or . or enter to finish this transaction): . -2020-01-01 * opening balances +2023-01-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 @@ -11718,7 +11686,7 @@ Account 6 (or . or enter to finish this transaction): . Save this transaction to the journal ? [y]: Saved. Starting the next transaction (. or ctrl-D/ctrl-C to quit) -Date [2020-01-01]: . +Date [2023-01-01]: . \f[R] .fi .RE @@ -11729,7 +11697,7 @@ Eg: .IP .nf \f[C] -$ git commit -m \[aq]initial balances\[aq] 2020.journal +$ git commit -m \[aq]initial balances\[aq] 2023.journal \f[R] .fi .SS Recording transactions @@ -11744,15 +11712,15 @@ hledger.org for more ideas: .IP .nf \f[C] -2020/1/10 * gift received +2023/1/10 * gift received assets:cash $20 income:gifts -2020.1.12 * farmers market +2023.1.12 * farmers market expenses:food $13 assets:cash -2020-01-15 paycheck +2023-01-15 paycheck income:salary assets:bank:checking $1000 \f[R] @@ -11784,7 +11752,7 @@ $2, it could be: .IP .nf \f[C] -2020-01-16 * adjust cash +2023-01-16 * adjust cash assets:cash $-2 = $105 expenses:misc \f[R] @@ -11813,14 +11781,14 @@ After reconciling, it could be a good time to mark the reconciled transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want to track that, by adding the \f[V]*\f[R] marker. Eg in the paycheck transaction above, insert \f[V]*\f[R] between -\f[V]2020-01-15\f[R] and \f[V]paycheck\f[R] +\f[V]2023-01-15\f[R] and \f[V]paycheck\f[R] .PP If you\[aq]re using version control, this can be another good time to commit: .IP .nf \f[C] -$ git commit -m \[aq]txns\[aq] 2020.journal +$ git commit -m \[aq]txns\[aq] 2023.journal \f[R] .fi .SS Reporting @@ -11832,26 +11800,26 @@ Show all transactions: .nf \f[C] $ hledger print -2020-01-01 * opening balances +2023-01-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 liabilities:creditcard $-50 equity:opening/closing balances $-3050 -2020-01-10 * gift received +2023-01-10 * gift received assets:cash $20 income:gifts -2020-01-12 * farmers market +2023-01-12 * farmers market expenses:food $13 assets:cash -2020-01-15 * paycheck +2023-01-15 * paycheck income:salary assets:bank:checking $1000 -2020-01-16 * adjust cash +2023-01-16 * adjust cash assets:cash $-2 = $105 expenses:misc \f[R] @@ -11923,9 +11891,9 @@ balance sheet: .nf \f[C] $ hledger bs -2 -Balance Sheet 2020-01-16 +Balance Sheet 2023-01-16 - || 2020-01-16 + || 2023-01-16 ========================++============ Assets || ------------------------++------------ @@ -11952,9 +11920,9 @@ Show income and expense totals, formatted as an income statement: .nf \f[C] hledger is -Income Statement 2020-01-01-2020-01-16 +Income Statement 2023-01-01-2023-01-16 - || 2020-01-01-2020-01-16 + || 2023-01-01-2023-01-16 ===============++======================= Revenues || ---------------++----------------------- @@ -11981,10 +11949,10 @@ Show transactions affecting your wallet, with running total: .nf \f[C] $ hledger register cash -2020-01-01 opening balances assets:cash $100 $100 -2020-01-10 gift received assets:cash $20 $120 -2020-01-12 farmers market assets:cash $-13 $107 -2020-01-16 adjust cash assets:cash $-2 $105 +2023-01-01 opening balances assets:cash $100 $100 +2023-01-10 gift received assets:cash $20 $120 +2023-01-12 farmers market assets:cash $-13 $107 +2023-01-16 adjust cash assets:cash $-2 $105 \f[R] .fi .PP @@ -11994,8 +11962,8 @@ Show weekly posting counts as a bar chart: \f[C] $ hledger activity -W 2019-12-30 ***** -2020-01-06 **** -2020-01-13 **** +2023-01-06 **** +2023-01-13 **** \f[R] .fi .SS Migrating to a new file diff --git a/hledger/hledger.info b/hledger/hledger.info index fd27f4459..f579d7c41 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -82,10 +82,11 @@ file" and "Setting opening balances" sections in PART 5: COMMON TASKS. * PART 1 USER INTERFACE:: * Input:: -* Environment:: -* Options:: * Commands:: +* Options:: +* Command line tips:: * Output:: +* Environment:: * PART 2 DATA FORMATS:: * Journal:: * CSV:: @@ -112,7 +113,7 @@ File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: ************************  -File: hledger.info, Node: Input, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top +File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top 2 Input ******* @@ -124,68 +125,30 @@ $ hledger -f FILE print Files are most often in hledger's journal format, with the '.journal' file extension ('.hledger' or '.j' also work); these files describe -transactions, like an accounting general journal. Some other supported -file formats are discussed below. +transactions, like an accounting general journal. - When no '-f' option is given, hledger looks for the file specified by -the 'LEDGER_FILE' environment variable; if this is not set, it uses -'.hledger.journal' in your home directory. + When no file is specified, hledger looks for '.hledger.journal' in +your home directory. - Most people prefer to keep financial files in a dedicated folder, -perhaps with version control. Also, starting a new journal file per + But most people prefer to keep financial files in a dedicated folder, +perhaps with version control. Also, starting a new journal file each year is common (it's not required, but helps keep things fast and -organised). So we usually set 'LEDGER_FILE', to something like -'~/finance/2023.journal'. +organised). So we usually configure a different journal file, by +setting the 'LEDGER_FILE' environment variable, to something like +'~/finance/2023.journal'. For more about how to do that on your system, +see Common tasks > Setting LEDGER_FILE. * Menu: -* Setting LEDGER_FILE:: * Data formats:: * Standard input:: * Multiple files:: * Strict mode::  -File: hledger.info, Node: Setting LEDGER_FILE, Next: Data formats, Up: Input +File: hledger.info, Node: Data formats, Next: Standard input, Up: Input -2.1 Setting LEDGER_FILE -======================= - -How to set 'LEDGER_FILE' permanently depends on your platform: - - On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: - -$ mkdir -p ~/finance -$ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile -$ source ~/.profile - - When correctly configured, in a new terminal window 'env | grep -LEDGER_FILE' will show your file, and so will 'hledger files'. - - On mac, this additional step might be helpful for GUI applications -(like Emacs started from the dock): add an entry to -'~/.MacOSX/environment.plist' like - -{ - "LEDGER_FILE" : "~/finance/2023.journal" -} - - and then run 'killall Dock' in a terminal window (or restart the -machine). - - On Windows, see https://www.java.com/en/download/help/path.html, or -try running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): - -> CD -> MKDIR finance -> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - -File: hledger.info, Node: Data formats, Next: Standard input, Prev: Setting LEDGER_FILE, Up: Input - -2.2 Data formats +2.1 Data formats ================ Usually the data file is in hledger's journal format, but it can be in @@ -222,7 +185,7 @@ $ hledger -f csv:/some/csv-file.dat stats  File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input -2.3 Standard input +2.2 Standard input ================== The file name '-' means standard input: @@ -237,7 +200,7 @@ $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-  File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input -2.4 Multiple files +2.3 Multiple files ================== You can specify multiple '-f' options, to read multiple files as one big @@ -256,7 +219,7 @@ a.journal b.journal | hledger -f- CMD'.  File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input -2.5 Strict mode +2.4 Strict mode =============== hledger checks input files for valid data. By default, the most @@ -279,54 +242,88 @@ without a lot of declarations: listed above and some more.  -File: hledger.info, Node: Environment, Next: Options, Prev: Input, Up: Top +File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top -3 Environment -************* +3 Commands +********** -Environment variables which affect hledger: +hledger provides various subcommands for getting things done. Most of +these commands do not change the journal file; they just read it and +output a report. A few commands assist with adding data and file +management. - *COLUMNS* This is normally set by your terminal; some hledger -commands ('register') will format their output to this width. If not -set, they will try to use the available terminal width. + To show the commands list, run 'hledger' with no arguments. The +commands are described in detail in PART 4: COMMANDS, below. - *LEDGER_FILE* The main journal file to use when not specified with -'-f/--file'. Default: '$HOME/.hledger.journal'. + To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', - *NO_COLOR* If this environment variable is set (with any value), -hledger will not use ANSI color codes in terminal output, unless -overridden by an explicit '--color/--colour' option. + * CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + * CMDOPTS are command-specific options, if any. Command-specific + options must be written after the command name. Eg: 'hledger print + -x'. + + * CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit + the data in some way. Eg: 'hledger reg assets:checking'. + + To list a command's options, arguments, and documentation in the +terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. + +* Menu: + +* Add-on commands::  -File: hledger.info, Node: Options, Next: Commands, Prev: Environment, Up: Top +File: hledger.info, Node: Add-on commands, Up: Commands + +3.1 Add-on commands +=================== + +In addition to the built-in commands, you can install _add-on commands_: +programs or scripts named "hledger-SOMETHING", which will also appear in +hledger's commands list. If you used the hledger-install script, you +will have several add-ons installed already. Some more can be found in +hledger's bin/ directory, documented at +https://hledger.org/scripts.html. + + More precisely, add-on commands are programs or scripts in your +shell's PATH, whose name starts with "hledger-" and ends with no +extension or a recognised extension (".bat", ".com", ".exe", ".hs", +".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), +and (on unix and mac) which has executable permission for the current +user. + + You can run add-on commands using hledger, much like built-in +commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'. But note +the double hyphen argument, required before add-on-specific options. +Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'. If this causes +difficulty, you can always run the add-on directly, without using +'hledger': 'hledger-ui --watch' or 'hledger-web --serve'. + + +File: hledger.info, Node: Options, Next: Command line tips, Prev: Commands, Up: Top 4 Options ********* -Here is a list of flags and options common to most hledger commands, and -some useful details about hledger command line parsing. But if you are -new to hledger, feel free to skim/skip ahead to the Commands. +Run 'hledger -h' to see general command line help, and general options +which are common to most hledger commands. These options can be written +anywhere on the command line. They can be grouped into help, input, and +reporting options: * Menu: -* General options:: -* Option repetition:: -* Command options:: -* Command arguments:: -* Special characters:: -* Unicode characters:: -* Regular expressions:: +* General help options:: +* General input options:: +* General reporting options::  -File: hledger.info, Node: General options, Next: Option repetition, Up: Options +File: hledger.info, Node: General help options, Next: General input options, Up: Options -4.1 General options -=================== - -To see general usage help, including general options which are supported -by most hledger commands, run 'hledger -h'. - - General help options: +4.1 General help options +======================== '-h --help' @@ -344,7 +341,11 @@ by most hledger commands, run 'hledger -h'. show debug output (levels 1-9, default: 1) - General input options: + +File: hledger.info, Node: General input options, Next: General reporting options, Prev: General help options, Up: Options + +4.2 General input options +========================= '-f FILE --file=FILE' @@ -374,7 +375,11 @@ by most hledger commands, run 'hledger -h'. do extra error checking (check that all posted accounts are declared) - General reporting options: + +File: hledger.info, Node: General reporting options, Prev: General input options, Up: Options + +4.3 General reporting options +============================= '-b --begin=DATE' @@ -492,9 +497,26 @@ the last one takes precedence. Some reporting options can also be written as query arguments.  -File: hledger.info, Node: Option repetition, Next: Command options, Prev: General options, Up: Options +File: hledger.info, Node: Command line tips, Next: Output, Prev: Options, Up: Top -4.2 Option repetition +5 Command line tips +******************* + +Here are some details useful to know about for hledger command lines +(and elsewhere). Feel free to skip this section until you need it. + +* Menu: + +* Option repetition:: +* Special characters:: +* Unicode characters:: +* Regular expressions:: +* Argument files:: + + +File: hledger.info, Node: Option repetition, Next: Special characters, Up: Command line tips + +5.1 Option repetition ===================== If options are repeated in a command line, hledger will generally use @@ -504,65 +526,9 @@ if repeated; these include: '--invert', '--transpose', '-r/--related', '-A/--average', and '-S/--sort-amount'.  -File: hledger.info, Node: Command options, Next: Command arguments, Prev: Option repetition, Up: Options +File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Option repetition, Up: Command line tips -4.3 Command options -=================== - -To see options for a particular command, including command-specific -options, run: 'hledger COMMAND -h'. - - Command-specific options must be written after the command name, eg: -'hledger print -x'. - - Additionally, if the command is an add-on, you may need to put its -options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can -run the add-on executable directly: 'hledger-ui --watch'. - - -File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options - -4.4 Command arguments -===================== - -Most hledger commands accept arguments after the command name, which are -often a query, filtering the data in some way. - - You can save a set of command line options/arguments in a file, and -then reuse them by writing '@FILENAME' as a command line argument. Eg: -'hledger bal @foo.args'. (To prevent this, eg if you have an argument -that begins with a literal '@', precede it with '--', eg: 'hledger bal --- @ARG'). - - Inside the argument file, each line should contain just one option or -argument. Avoid the use of spaces, except inside quotes (or you'll see -a confusing error). Between a flag and its argument, use = (or -nothing). Bad: - -assets depth:2 --X USD - - Good: - -assets -depth:2 --X=USD - - For special characters (see below), use one less level of quoting -than you would at the command prompt. Bad: - --X"$" - - Good: - --X$ - - See also: Save frequently used options. - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options - -4.5 Special characters +5.2 Special characters ====================== * Menu: @@ -575,7 +541,7 @@ File: hledger.info, Node: Special characters, Next: Unicode characters, Prev:  File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters -4.5.1 Single escaping (shell metacharacters) +5.2.1 Single escaping (shell metacharacters) -------------------------------------------- In shell command lines, characters significant to your shell - such as @@ -597,7 +563,7 @@ PowerShell treats both single and double quotes as quotes.  File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters -4.5.2 Double escaping (regular expression metacharacters) +5.2.2 Double escaping (regular expression metacharacters) --------------------------------------------------------- Characters significant in regular expressions (described below) - such @@ -617,7 +583,7 @@ $ hledger balance cur:\\$  File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters -4.5.3 Triple escaping (for add-on commands) +5.2.3 Triple escaping (for add-on commands) ------------------------------------------- When you use hledger to run an external add-on command (described @@ -647,7 +613,7 @@ $ hledger-ui cur:\\$  File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters -4.5.4 Less escaping +5.2.4 Less escaping ------------------- Options and arguments are sometimes used in places other than the shell @@ -660,9 +626,9 @@ use one less level of escaping. Those places include: * GHCI's prompt (used by developers).  -File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options +File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Command line tips -4.6 Unicode characters +5.3 Unicode characters ====================== hledger is expected to handle non-ascii characters correctly: @@ -699,9 +665,9 @@ hledger is expected to handle non-ascii characters correctly: terminal, and vice versa. (See eg #961).  -File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options +File: hledger.info, Node: Regular expressions, Next: Argument files, Prev: Unicode characters, Up: Command line tips -4.7 Regular expressions +5.4 Regular expressions ======================= hledger uses regular expressions in a number of places: @@ -744,66 +710,40 @@ they support: See Special characters.  -File: hledger.info, Node: Commands, Next: Output, Prev: Options, Up: Top +File: hledger.info, Node: Argument files, Prev: Regular expressions, Up: Command line tips -5 Commands -********** +5.5 Argument files +================== -hledger provides a number of built-in subcommands (described below). -Most of these read your data without changing it, and display a report. -A few assist with data entry and management. +You can save a set of command line options and arguments in a file, and +then reuse them by writing '@FILENAME' as a command line argument. Eg: +'hledger bal @foo.args'. - Run 'hledger' with no arguments to list the commands available, and -'hledger CMD' to run a command. CMD can be the full command name, or -its standard abbreviation shown in the commands list, or any unambiguous -prefix of the name. Eg: 'hledger bal'. + Inside the argument file, each line should contain just one option or +argument. Also, don't use spaces except inside quotes (or you'll see a +confusing error). Ie, write = (or nothing) between a flag and its +argument. Eg, bad: -* Menu: +assets -X USD -* Add-on commands:: + Good: + +assets +-X=USD + + For the special characters mentioned above, use one less level of +quoting than you would at the command prompt. Eg, bad: + +-X"$" + + Good: + +-X$ + + See also: Save frequently used options.  -File: hledger.info, Node: Add-on commands, Up: Commands - -5.1 Add-on commands -=================== - -Add-on commands are extra subcommands provided by programs or scripts in -your PATH - - * whose name starts with 'hledger-' - * whose name ends with a recognised file extension: - '.bat','.com','.exe', '.hs','.lhs','.pl','.py','.rb','.rkt','.sh' - or none - * and (on unix, mac) which are executable by the current user. - - Addons can be written in any language, but haskell scripts or -programs have a big advantage: they can use hledger's library code, for -command-line options, parsing and reporting. - - Several add-on commands are installed by the hledger-install script. -See https://hledger.org/scripts.html for more details. - - Note in a hledger command line, add-on command flags must have a -double dash ('--') preceding them. Eg you must write: - -$ hledger web -- --serve - - and not: - -$ hledger web --serve - - (because the '--serve' flag belongs to 'hledger-web', not 'hledger'). - - The '-h/--help' and '--version' flags don't require '--'. - - If you have any trouble with this, remember you can always run the -add-on program directly, eg: - -$ hledger-web --serve - - -File: hledger.info, Node: Output, Next: PART 2 DATA FORMATS, Prev: Commands, Up: Top +File: hledger.info, Node: Output, Next: Environment, Prev: Command line tips, Up: Top 6 Output ******** @@ -1038,15 +978,34 @@ a log file instead, you can usually redirect stderr, eg: hledger bal --debug=3 2>hledger.log  -File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Output, Up: Top +File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top -7 PART 2: DATA FORMATS +7 Environment +************* + +These environment variables affect hledger: + + *COLUMNS* This is normally set by your terminal; some hledger +commands ('register') will format their output to this width. If not +set, they will try to use the available terminal width. + + *LEDGER_FILE* The main journal file to use when not specified with +'-f/--file'. Default: '$HOME/.hledger.journal'. + + *NO_COLOR* If this environment variable is set (with any value), +hledger will not use ANSI color codes in terminal output, unless +overridden by an explicit '--color/--colour' option. + + +File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top + +8 PART 2: DATA FORMATS **********************  File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top -8 Journal +9 Journal ********* hledger's default file format, representing a General Journal. Here's a @@ -1086,7 +1045,7 @@ cheatsheet/mini-tutorial, or you can skip ahead to About journal format.  File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal -8.1 Journal cheatsheet +9.1 Journal cheatsheet ====================== # Here is the main syntax of hledger's journal format @@ -1180,7 +1139,7 @@ P 2022-01-01 AAAA $1.40  File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal -8.2 About journal format +9.2 About journal format ======================== hledger's usual data source is a plain text file containing journal @@ -1218,7 +1177,7 @@ rules and auto posting rules as directives).  File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal -8.3 Comments +9.3 Comments ============ Lines in the journal will be ignored if they begin with a hash ('#') or @@ -1248,7 +1207,7 @@ comments, and Account comments below.  File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal -8.4 Transactions +9.4 Transactions ================ Transactions are the main unit of information in a journal file. They @@ -1277,7 +1236,7 @@ optional fields, separated by spaces:  File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal -8.5 Dates +9.5 Dates ========= * Menu: @@ -1288,7 +1247,7 @@ File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journ  File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates -8.5.1 Simple dates +9.5.1 Simple dates ------------------ Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or @@ -1304,7 +1263,7 @@ dates documented in the hledger manual.)  File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates -8.5.2 Posting dates +9.5.2 Posting dates ------------------- You can give individual postings a different date from their parent @@ -1332,7 +1291,7 @@ a 'date:' tag with no value is not allowed.  File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal -8.6 Status +9.6 Status ========== Transactions, or individual postings within a transaction, can have a @@ -1382,7 +1341,7 @@ your finances.  File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal -8.7 Code +9.7 Code ======== After the status mark, but before the description, you can optionally @@ -1393,7 +1352,7 @@ or reference number.  File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal -8.8 Description +9.8 Description =============== A transaction's description is the rest of the line following the date @@ -1409,7 +1368,7 @@ comments.  File: hledger.info, Node: Payee and note, Up: Description -8.8.1 Payee and note +9.8.1 Payee and note -------------------- You can optionally include a '|' (pipe) character in descriptions to @@ -1421,7 +1380,7 @@ precise querying and pivoting by payee or by note.  File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal -8.9 Transaction comments +9.9 Transaction comments ======================== Text following ';', after a transaction description, and/or on indented @@ -1437,7 +1396,7 @@ tags, which are not ignored.  File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal -8.10 Postings +9.10 Postings ============= A posting is an addition of some amount to, or removal of some amount @@ -1465,7 +1424,7 @@ the amount, the amount will be considered part of the account name.  File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal -8.11 Account names +9.11 Account names ================== Accounts are the main way of categorising things in hledger. As in @@ -1516,7 +1475,7 @@ aliases.  File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal -8.12 Amounts +9.12 Amounts ============ After the account name, there is usually an amount. (Important: between @@ -1565,7 +1524,7 @@ EUR 1E3  File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts -8.12.1 Decimal marks, digit group marks +9.12.1 Decimal marks, digit group marks --------------------------------------- A _decimal mark_ can be written as a period or a comma: @@ -1601,7 +1560,7 @@ directives will also work. These are described below.  File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts -8.12.2 Commodity +9.12.2 Commodity ---------------- Amounts in hledger have both a "quantity", which is a signed decimal @@ -1627,7 +1586,7 @@ these are the 'Amount' and 'MixedAmount' types.)  File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts -8.12.3 Directives influencing number parsing and display +9.12.3 Directives influencing number parsing and display -------------------------------------------------------- You can add 'decimal-mark' and 'commodity' directives to the journal, to @@ -1646,7 +1605,7 @@ commodity 1 000 000.9455  File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts -8.12.4 Commodity display style +9.12.4 Commodity display style ------------------------------ For the amounts in each commodity, hledger chooses a consistent display @@ -1703,7 +1662,7 @@ line option.  File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts -8.12.5 Rounding +9.12.5 Rounding --------------- Amounts are stored internally as decimal numbers with up to 255 decimal @@ -1715,7 +1674,7 @@ places is "0").  File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal -8.13 Costs +9.13 Costs ========== After a posting amount, you can note its cost (when buying) or selling @@ -1773,7 +1732,7 @@ not required to be. This can be a little confusing, see discussion at  File: hledger.info, Node: Other cost/lot notations, Up: Costs -8.13.1 Other cost/lot notations +9.13.1 Other cost/lot notations ------------------------------- A slight digression for Ledger and Beancount users. Ledger has a number @@ -1843,7 +1802,7 @@ but ignores it.  File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal -8.14 Balance assertions +9.14 Balance assertions ======================= hledger supports Ledger-style balance assertions in journal files. @@ -1882,7 +1841,7 @@ does not disable balance assignments, described below).  File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions -8.14.1 Assertions and ordering +9.14.1 Assertions and ordering ------------------------------ hledger sorts an account's postings and assertions first by date and @@ -1901,7 +1860,7 @@ can assert intra-day balances.  File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions -8.14.2 Assertions and multiple included files +9.14.2 Assertions and multiple included files --------------------------------------------- Multiple files included with the 'include' directive are processed as if @@ -1917,7 +1876,7 @@ balance on that day, you'll need to put the assertion in the right file  File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions -8.14.3 Assertions and multiple -f files +9.14.3 Assertions and multiple -f files --------------------------------------- Unlike 'include', when multiple files are specified on the command line @@ -1931,7 +1890,7 @@ problems in earlier files to disrupt valid assertions in later files.  File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions -8.14.4 Assertions and commodities +9.14.4 Assertions and commodities --------------------------------- The asserted balance must be a simple single-commodity amount, and in @@ -1979,7 +1938,7 @@ commodity into its own subaccount:  File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions -8.14.5 Assertions and prices +9.14.5 Assertions and prices ---------------------------- Balance assertions ignore costs, and should normally be written without @@ -1997,7 +1956,7 @@ _assignments_ do use them (see below).  File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions -8.14.6 Assertions and subaccounts +9.14.6 Assertions and subaccounts --------------------------------- The balance assertions above ('=' and '==') do not count the balance @@ -2014,7 +1973,7 @@ eg:  File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions -8.14.7 Assertions and virtual postings +9.14.7 Assertions and virtual postings -------------------------------------- Balance assertions always consider both real and virtual postings; they @@ -2023,7 +1982,7 @@ are not affected by the '--real/-R' flag or 'real:' query.  File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions -8.14.8 Assertions and auto postings +9.14.8 Assertions and auto postings ----------------------------------- Balance assertions _are_ affected by the '--auto' flag, which generates @@ -2042,7 +2001,7 @@ these. So to avoid making fragile assertions, either:  File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions -8.14.9 Assertions and precision +9.14.9 Assertions and precision ------------------------------- Balance assertions compare the exactly calculated amounts, which are not @@ -2053,7 +2012,7 @@ assertion failure messages show exact amounts.  File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal -8.15 Posting comments +9.15 Posting comments ===================== Text following ';', at the end of a posting line, and/or on indented @@ -2070,7 +2029,7 @@ tags, which are not ignored.  File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal -8.16 Tags +9.16 Tags ========= Tags are a way to add extra labels or labelled data to transactions, @@ -2107,7 +2066,7 @@ tag name with a 'tag:NAMEREGEX' query.  File: hledger.info, Node: Tag values, Up: Tags -8.16.1 Tag values +9.16.1 Tag values ----------------- Tags can have a value, which is any text after the colon up until a @@ -2129,7 +2088,7 @@ match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query.  File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal -8.17 Directives +9.17 Directives =============== Besides transactions, there is something else you can put in a 'journal' @@ -2169,7 +2128,7 @@ Declare market prices 'P'  File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives -8.17.1 Directives and multiple files +9.17.1 Directives and multiple files ------------------------------------ Directives vary in their scope, ie which journal entries and which input @@ -2189,7 +2148,7 @@ directives in your files.  File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives -8.17.2 Directive effects +9.17.2 Directive effects ------------------------ Here are all hledger's directives, with their effects and scope @@ -2250,7 +2209,7 @@ directives*  File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal -8.18 'account' directive +9.18 'account' directive ======================== 'account' directives can be used to declare accounts (ie, the places @@ -2293,7 +2252,7 @@ account (assets:bank:checking)  File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive -8.18.1 Account comments +9.18.1 Account comments ----------------------- Text following *two or more spaces* and ';' at the end of an account @@ -2311,7 +2270,7 @@ account assets:bank:checking ; same-line comment, at least 2 spaces before th  File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive -8.18.2 Account subdirectives +9.18.2 Account subdirectives ---------------------------- Ledger-style indented subdirectives are also accepted, but currently @@ -2323,7 +2282,7 @@ account assets:bank:checking  File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive -8.18.3 Account error checking +9.18.3 Account error checking ----------------------------- By default, accounts need not be declared; they come into existence when @@ -2351,7 +2310,7 @@ been declared by an account directive. Some notes:  File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive -8.18.4 Account display order +9.18.4 Account display order ---------------------------- The order in which account directives are written influences the order @@ -2395,7 +2354,7 @@ means:  File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive -8.18.5 Account types +9.18.5 Account types -------------------- hledger knows that accounts come in several types: assets, liabilities, @@ -2481,7 +2440,7 @@ account equity:conversion ; type: V  File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal -8.19 'alias' directive +9.19 'alias' directive ====================== You can define account alias rules which rewrite your account names, or @@ -2518,7 +2477,7 @@ more on this below.  File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive -8.19.1 Basic aliases +9.19.1 Basic aliases -------------------- To set an account alias, use the 'alias' directive in your journal file. @@ -2542,7 +2501,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive -8.19.2 Regex aliases +9.19.2 Regex aliases -------------------- There is also a more powerful variant that uses a regular expression, @@ -2576,7 +2535,7 @@ of option argument), so it can contain trailing whitespace.  File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive -8.19.3 Combining aliases +9.19.3 Combining aliases ------------------------ You can define as many aliases as you like, using journal directives @@ -2613,7 +2572,7 @@ which aliases are being applied when.  File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive -8.19.4 Aliases and multiple files +9.19.4 Aliases and multiple files --------------------------------- As explained at Directives and multiple files, 'alias' directives do not @@ -2626,7 +2585,7 @@ Including the aliases doesn't work either: include a.aliases -2020-01-01 ; not affected by a.aliases +2023-01-01 ; not affected by a.aliases foo 1 bar @@ -2636,7 +2595,7 @@ start of your top-most file, like this: alias foo=Foo alias bar=Bar -2020-01-01 ; affected by aliases above +2023-01-01 ; affected by aliases above foo 1 bar @@ -2645,7 +2604,7 @@ include c.journal ; also affected  File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive -8.19.5 'end aliases' directive +9.19.5 'end aliases' directive ------------------------------ You can clear (forget) all currently defined aliases (seen in the @@ -2656,7 +2615,7 @@ end aliases  File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive -8.19.6 Aliases can generate bad account names +9.19.6 Aliases can generate bad account names --------------------------------------------- Be aware that account aliases can produce malformed account names, which @@ -2687,7 +2646,7 @@ $ hledger print --alias old="new USD" | hledger -f- print  File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive -8.19.7 Aliases and account types +9.19.7 Aliases and account types -------------------------------- If an account with a type declaration (see Declaring accounts > Account @@ -2711,7 +2670,7 @@ $ hledger accounts --alias assets=bassetts type:a  File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal -8.20 'commodity' directive +9.20 'commodity' directive ========================== You can use 'commodity' directives to declare your commodities. In fact @@ -2789,7 +2748,7 @@ style can still be overridden by supplying a command line option.  File: hledger.info, Node: Commodity error checking, Up: commodity directive -8.20.1 Commodity error checking +9.20.1 Commodity error checking ------------------------------- In strict mode, enabled with the '-s'/'--strict' flag, hledger will @@ -2805,7 +2764,7 @@ are always allowed to have no commodity symbol.  File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal -8.21 'decimal-mark' directive +9.21 'decimal-mark' directive ============================= You can use a 'decimal-mark' directive - usually one per file, at the @@ -2825,7 +2784,7 @@ thousands separators).  File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal -8.22 'include' directive +9.22 'include' directive ======================== You can pull in the content of additional files by writing an include @@ -2851,12 +2810,12 @@ this can be done, eg: 'include */**/*.journal'. The path may also be prefixed to force a specific file format, overriding the file extension (as described in hledger.1 -> Input -files): 'include timedot:~/notes/2020*.md'. +files): 'include timedot:~/notes/2023*.md'.  File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal -8.23 'P' directive +9.23 'P' directive ================== The 'P' directive declares a market price, which is a conversion rate @@ -2886,7 +2845,7 @@ amount values in another commodity. See Valuation.  File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal -8.24 'payee' directive +9.24 'payee' directive ====================== 'payee PAYEE NAME' @@ -2903,7 +2862,7 @@ payee Whole Foods  File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal -8.25 'tag' directive +9.25 'tag' directive ==================== 'tag TAGNAME' @@ -2923,7 +2882,7 @@ declare and check your tags .  File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal -8.26 Periodic transactions +9.26 Periodic transactions ========================== The '~' directive declares recurring transactions. Such directives @@ -2952,8 +2911,8 @@ read this whole section, or at least these tips: expanded to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th - day of month from 2020/01', which is equivalent to '~ every 10th - day of month from 2020/01/01', will be adjusted to start on + day of month from 2023/01', which is equivalent to '~ every 10th + day of month from 2023/01/01', will be adjusted to start on 2019/12/10. * Menu: @@ -2965,7 +2924,7 @@ read this whole section, or at least these tips:  File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions -8.26.1 Periodic rule syntax +9.26.1 Periodic rule syntax --------------------------- A periodic transaction rule looks like a normal journal entry, with the @@ -2990,7 +2949,7 @@ dates).  File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions -8.26.2 Periodic rules and relative dates +9.26.2 Periodic rules and relative dates ---------------------------------------- Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', @@ -3009,7 +2968,7 @@ dates.  File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions -8.26.3 Two spaces between period expression and description! +9.26.3 Two spaces between period expression and description! ------------------------------------------------------------ If the period expression is followed by a transaction description, these @@ -3017,10 +2976,10 @@ must be separated by *two or more spaces*. This helps hledger know where the period expression ends, so that descriptions can not accidentally alter their meaning, as in this example: -; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020" +; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" ; || ; vv -~ every 2 months in 2020, we will review +~ every 2 months in 2023, we will review assets:bank:checking $1500 income:acme inc @@ -3034,7 +2993,7 @@ accidentally alter their meaning, as in this example:  File: hledger.info, Node: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal -8.27 Auto postings +9.27 Auto postings ================== The '=' directive declares a rule for generating temporary extra @@ -3117,7 +3076,7 @@ $ hledger print --auto  File: hledger.info, Node: Auto postings and multiple files, Up: Auto postings -8.27.1 Auto postings and multiple files +9.27.1 Auto postings and multiple files --------------------------------------- An auto posting rule can affect any transaction in the current file, or @@ -3134,7 +3093,7 @@ sibling files (when multiple '-f'/'--file' are used - see #1212).  File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files -8.27.1.1 Auto postings and dates +9.27.1.1 Auto postings and dates ................................ A posting date (or secondary date) in the matched posting, or (taking @@ -3144,7 +3103,7 @@ used in the generated posting.  File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings and multiple files -8.27.1.2 Auto postings and transaction balancing / inferred +9.27.1.2 Auto postings and transaction balancing / inferred ........................................................... amounts / balance assertions Currently, auto postings are added: @@ -3164,7 +3123,7 @@ infer amounts.  File: hledger.info, Node: Auto posting tags, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings and multiple files -8.27.1.3 Auto posting tags +9.27.1.3 Auto posting tags .......................... Automated postings will have some extra tags: @@ -3186,7 +3145,7 @@ will have these tags added:  File: hledger.info, Node: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings and multiple files -8.27.1.4 Auto postings on forecast transactions only +9.27.1.4 Auto postings on forecast transactions only .................................................... Tip: you can can make auto postings that will apply to forecast @@ -3197,7 +3156,7 @@ generating new journal entries to be saved in the journal.  File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal -8.28 Other syntax +9.28 Other syntax ================= hledger journal format supports quite a few other features, mainly to @@ -3223,7 +3182,7 @@ you decide if you want to use them.  File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax -8.28.1 Balance assignments +9.28.1 Balance assignments -------------------------- Ledger-style balance assignments are also supported. These are like @@ -3265,7 +3224,7 @@ trustworthy in an audit.  File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments -8.28.1.1 Balance assignments and prices +9.28.1.1 Balance assignments and prices ....................................... A cost in a balance assignment will cause the calculated amount to have @@ -3281,7 +3240,7 @@ $ hledger print --explicit  File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax -8.28.2 Bracketed posting dates +9.28.2 Bracketed posting dates ------------------------------ For setting posting dates and secondary posting dates, Ledger's @@ -3298,7 +3257,7 @@ syntax.  File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax -8.28.3 'D' directive +9.28.3 'D' directive -------------------- 'D AMOUNT' @@ -3344,7 +3303,7 @@ Ledger's 'D'.  File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax -8.28.4 'apply account' directive +9.28.4 'apply account' directive -------------------------------- This directive sets a default parent account, which will be prepended to @@ -3380,7 +3339,7 @@ portable, and less trustworthy in an audit.  File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax -8.28.5 'Y' directive +9.28.5 'Y' directive -------------------- 'Y YEAR' @@ -3418,7 +3377,7 @@ date.  File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax -8.28.6 Secondary dates +9.28.6 Secondary dates ---------------------- A secondary date is written after the primary date, following an equals @@ -3440,7 +3399,7 @@ better.  File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax -8.28.7 Star comments +9.28.7 Star comments -------------------- Lines beginning with '*' (star/asterisk) are also comment lines. This @@ -3457,7 +3416,7 @@ losing ledger mode's features.  File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax -8.28.8 Valuation expressions +9.28.8 Valuation expressions ---------------------------- Ledger allows a valuation function or value to be written in double @@ -3466,7 +3425,7 @@ parentheses after an amount. hledger ignores these.  File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax -8.28.9 Virtual postings +9.28.9 Virtual postings ----------------------- A posting with parentheses around the account name is called a _virtual @@ -3505,7 +3464,7 @@ and less trustworthy in an audit.  File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax -8.28.10 Other Ledger directives +9.28.10 Other Ledger directives ------------------------------- These other Ledger directives are currently accepted but ignored. This @@ -3536,8 +3495,8 @@ hledger/Ledger syntax comparison.  File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top -9 CSV -***** +10 CSV +****** hledger can read CSV files (Character Separated Value - usually comma, semicolon, or tab) containing dated records, automatically converting @@ -3607,8 +3566,8 @@ https://github.com/simonmichael/hledger/tree/master/examples/csv.  File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV -9.1 CSV rules cheatsheet -======================== +10.1 CSV rules cheatsheet +========================= The following kinds of rule can appear in the rules file, in any order. (Blank lines and lines beginning with '#' or ';' or '*' are ignored.) @@ -3647,8 +3606,8 @@ evaluated.  File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV -9.2 'source' -============ +10.2 'source' +============= If you tell hledger to read a csv file with '-f foo.csv', it will look for rules in 'foo.csv.rules'. Or, you can tell it to read the rules @@ -3677,8 +3636,8 @@ source Checking1*.csv  File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV -9.3 'separator' -=============== +10.3 'separator' +================ You can use the 'separator' rule to read other kinds of character-separated data. The argument is any single separator @@ -3702,8 +3661,8 @@ inferred automatically, and you won't need this rule.  File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV -9.4 'skip' -========== +10.4 'skip' +=========== skip N @@ -3721,8 +3680,8 @@ required to be valid CSV.  File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV -9.5 'date-format' -================= +10.5 'date-format' +================== date-format DATEFMT @@ -3750,8 +3709,8 @@ date-format %-m/%-d/%Y %l:%M %p some other junk  File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV -9.6 'timezone' -============== +10.6 'timezone' +=============== timezone TIMEZONE @@ -3779,8 +3738,8 @@ For others, use numeric format: +HHMM or -HHMM.  File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV -9.7 'newest-first' -================== +10.7 'newest-first' +=================== hledger tries to ensure that the generated transactions will be ordered chronologically, including intra-day transactions. Usually it can @@ -3802,8 +3761,8 @@ newest-first  File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV -9.8 'intra-day-reversed' -======================== +10.8 'intra-day-reversed' +========================= CSV records for each day are sometimes ordered in reverse compared to the overall date order. Eg, here dates are newest first, but the @@ -3823,8 +3782,8 @@ intra-day-reversed  File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV -9.9 'decimal-mark' -================== +10.9 'decimal-mark' +=================== decimal-mark . @@ -3841,8 +3800,8 @@ misparsed numbers.  File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV -9.10 'fields' list -================== +10.10 'fields' list +=================== fields FIELDNAME1, FIELDNAME2, ... @@ -3886,8 +3845,8 @@ field (and generating a balance assertion).  File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV -9.11 Field assignment -===================== +10.11 Field assignment +====================== HLEDGERFIELD FIELDVALUE @@ -3920,8 +3879,8 @@ comment note: %somefield - %anotherfield, date: %1  File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV -9.12 Field names -================ +10.12 Field names +================= Note the two kinds of field names mentioned here, and used only in hledger CSV rules files: @@ -3969,48 +3928,48 @@ happens when you assign values to them:  File: hledger.info, Node: date field, Next: date2 field, Up: Field names -9.12.1 date field ------------------ +10.12.1 date field +------------------ Assigning to 'date' sets the transaction date.  File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names -9.12.2 date2 field ------------------- +10.12.2 date2 field +------------------- 'date2' sets the transaction's secondary date, if any.  File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names -9.12.3 status field -------------------- +10.12.3 status field +-------------------- 'status' sets the transaction's status, if any.  File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names -9.12.4 code field ------------------ +10.12.4 code field +------------------ 'code' sets the transaction's code, if any.  File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names -9.12.5 description field ------------------------- +10.12.5 description field +------------------------- 'description' sets the transaction's description, if any.  File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names -9.12.6 comment field --------------------- +10.12.6 comment field +--------------------- 'comment' sets the transaction's comment, if any. @@ -4024,8 +3983,8 @@ code. A comment starting with '\n' will begin on a new line.  File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names -9.12.7 account field --------------------- +10.12.7 account field +--------------------- Assigning to 'accountN', where N is 1 to 99, sets the account name of the Nth posting, and causes that posting to be generated. @@ -4042,8 +4001,8 @@ or "income:unknown").  File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names -9.12.8 amount field -------------------- +10.12.8 amount field +-------------------- Amount setting can get a bit complex. Assigning to 'amount' is sufficient for simple transactions, but there are four field name @@ -4115,8 +4074,8 @@ to 'amount'; if you don't want that, call it something else, like  File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names -9.12.9 currency field ---------------------- +10.12.9 currency field +---------------------- 'currency' sets a currency symbol, to be prepended to all postings' amounts. You can use this if the CSV amounts do not have a currency @@ -4128,8 +4087,8 @@ amount.  File: hledger.info, Node: balance field, Prev: currency field, Up: Field names -9.12.10 balance field ---------------------- +10.12.10 balance field +---------------------- 'balanceN' sets a balance assertion amount (or if the posting amount is left empty, a balance assignment) on posting N. @@ -4145,8 +4104,8 @@ equivalent to 'balance1'.  File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV -9.13 'if' block -=============== +10.13 'if' block +================ Rules can be applied conditionally, depending on patterns in the CSV data. This allows flexibility; in particular, it is how you can @@ -4200,8 +4159,8 @@ if ,,,,  File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV -9.14 Matchers -============= +10.14 Matchers +============== There are two kinds: @@ -4227,11 +4186,11 @@ converted to commas, and enclosing double quotes (but not enclosing whitespace) are removed. So for example, when reading an SSV file, if the original record was: -2020-01-01; "Acme, Inc."; 1,000 +2023-01-01; "Acme, Inc."; 1,000 the regex would see, and try to match, this modified record text: -2020-01-01,Acme, Inc., 1,000 +2023-01-01,Acme, Inc., 1,000 When an if block has multiple matchers, they are combined as follows: @@ -4244,8 +4203,8 @@ the original record was:  File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV -9.15 'if' table -=============== +10.15 'if' table +================ "if tables" are an alternative to if blocks; they can express many matchers and field assignments in a more compact tabular format, like @@ -4290,13 +4249,13 @@ if MATCHERC if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, -2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out +2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out  File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV -9.16 'balance-type' -=================== +10.16 'balance-type' +==================== Balance assertions generated by assigning to balanceN are of the simple '=' type by default, which is a single-commodity, subaccount-excluding @@ -4318,8 +4277,8 @@ balance-type ==*  File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV -9.17 'include' -============== +10.17 'include' +=============== include RULESFILE @@ -4341,8 +4300,8 @@ include categorisation.rules  File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV -9.18 Working with CSV -===================== +10.18 Working with CSV +====================== Some tips: @@ -4367,8 +4326,8 @@ Some tips:  File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV -9.18.1 Rapid feedback ---------------------- +10.18.1 Rapid feedback +---------------------- It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from eradman.com/entrproject: @@ -4383,8 +4342,8 @@ output.  File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV -9.18.2 Valid CSV ----------------- +10.18.2 Valid CSV +----------------- Note that hledger will only accept valid CSV conforming to RFC 4180, and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab @@ -4404,8 +4363,8 @@ permissive CSV parser like python's csv lib.  File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV -9.18.3 File Extension ---------------------- +10.18.3 File Extension +---------------------- To help hledger choose the CSV file reader and show the right error messages (and choose the right field separator character by default), @@ -4424,8 +4383,8 @@ rule if needed.  File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV -9.18.4 Reading CSV from standard input --------------------------------------- +10.18.4 Reading CSV from standard input +--------------------------------------- You'll need the file format prefix when reading CSV from stdin also, since hledger assumes journal format by default. Eg: @@ -4435,8 +4394,8 @@ $ cat foo.dat | hledger -f ssv:- print  File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV -9.18.5 Reading multiple CSV files ---------------------------------- +10.18.5 Reading multiple CSV files +---------------------------------- If you use multiple '-f' options to read multiple CSV files at once, hledger will look for a correspondingly-named rules file for each CSV @@ -4446,8 +4405,8 @@ used for all the CSV files.  File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV -9.18.6 Reading files specified by rule --------------------------------------- +10.18.6 Reading files specified by rule +--------------------------------------- Instead of specifying a CSV file in the command line, you can specify a rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will @@ -4475,8 +4434,8 @@ most recent.  File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV -9.18.7 Valid transactions -------------------------- +10.18.7 Valid transactions +-------------------------- After reading a CSV file, hledger post-processes and validates the generated journal entries as it would for a journal file - balancing @@ -4494,8 +4453,8 @@ $ hledger -f file.csv print | hledger -f- print  File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV -9.18.8 Deduplicating, importing -------------------------------- +10.18.8 Deduplicating, importing +-------------------------------- When you download a CSV file periodically, eg to get your latest bank transactions, the new file may overlap with the old one, containing some @@ -4524,8 +4483,8 @@ CSV data. See:  File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV -9.18.9 Setting amounts ----------------------- +10.18.9 Setting amounts +----------------------- Continuing from amount field above, here are more tips on handling various amount-setting situations: @@ -4591,8 +4550,8 @@ various amount-setting situations:  File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV -9.18.10 Amount signs --------------------- +10.18.10 Amount signs +--------------------- There is some special handling making it easier to parse and to reverse amount signs. (This only works for whole amounts, not for cost amounts @@ -4621,26 +4580,26 @@ its absolute value, ie discard its sign.  File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV -9.18.11 Setting currency/commodity ----------------------------------- +10.18.11 Setting currency/commodity +----------------------------------- If the currency/commodity symbol is included in the CSV's amount field(s): -2020-01-01,foo,$123.00 +2023-01-01,foo,$123.00 you don't have to do anything special for the commodity symbol, it will be assigned as part of the amount. Eg: fields date,description,amount -2020-01-01 foo +2023-01-01 foo expenses:unknown $123.00 income:unknown $-123.00 If the currency is provided as a separate CSV field: -2020-01-01,foo,USD,123.00 +2023-01-01,foo,USD,123.00 You can assign that to the 'currency' pseudo-field, which has the special effect of prepending itself to every amount in the transaction @@ -4648,7 +4607,7 @@ special effect of prepending itself to every amount in the transaction fields date,description,currency,amount -2020-01-01 foo +2023-01-01 foo expenses:unknown USD123.00 income:unknown USD-123.00 @@ -4659,7 +4618,7 @@ a space: fields date,description,cur,amt amount %amt %cur -2020-01-01 foo +2023-01-01 foo expenses:unknown 123.00 USD income:unknown -123.00 USD @@ -4669,8 +4628,8 @@ that would trigger the prepending effect, which we don't want here.  File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV -9.18.12 Amount decimal places ------------------------------ +10.18.12 Amount decimal places +------------------------------ Like amounts in a journal file, the amounts generated by CSV rules like 'amount1' influence commodity display styles, such as the number of @@ -4682,8 +4641,8 @@ style (because we don't yet reliably know their commodity).  File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV -9.18.13 Referencing other fields --------------------------------- +10.18.13 Referencing other fields +--------------------------------- In field assignments, you can interpolate only CSV fields, not hledger fields. In the example below, there's both a CSV field and a hledger @@ -4719,8 +4678,8 @@ if something  File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV -9.18.14 How CSV rules are evaluated ------------------------------------ +10.18.14 How CSV rules are evaluated +------------------------------------ Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -4760,8 +4719,8 @@ command the user specified.  File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV -9.18.15 Well factored rules ---------------------------- +10.18.15 Well factored rules +---------------------------- Some things than can help reduce duplication and complexity in rules files: @@ -4776,8 +4735,8 @@ files:  File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV -9.19 CSV rules examples -======================= +10.19 CSV rules examples +======================== * Menu: @@ -4789,8 +4748,8 @@ File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV  File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples -9.19.1 Bank of Ireland ----------------------- +10.19.1 Bank of Ireland +----------------------- Here's a CSV with two amount fields (Debit and Credit), and a balance field, which we can use to add balance assertions, which is not @@ -4842,8 +4801,8 @@ imported into a journal file.  File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples -9.19.2 Coinbase ---------------- +10.19.2 Coinbase +---------------- A simple example with some CSV from Coinbase. The spot price is recorded using cost notation. The legacy 'amount' field name @@ -4869,8 +4828,8 @@ $ hledger print -f coinbase.csv  File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples -9.19.3 Amazon -------------- +10.19.3 Amazon +-------------- Here we convert amazon.com order history, and use an if block to generate a third posting if there's a fee. (In practice you'd probably @@ -4927,8 +4886,8 @@ $ hledger -f amazon-orders.csv print  File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples -9.19.4 Paypal -------------- +10.19.4 Paypal +-------------- Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: @@ -5081,7 +5040,7 @@ $ hledger -f paypal-custom.csv print  File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top -10 Timeclock +11 Timeclock ************ The time logging format of timeclock.el, as read by hledger. @@ -5136,7 +5095,7 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa  File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top -11 Timedot +12 Timedot ********** 'timedot' format is hledger's human-friendly time logging format. @@ -5231,13 +5190,13 @@ fos:hledger 3 biz:research 1 * Time log -** 2020-01-01 +** 2023-01-01 *** adm:time . *** adm:finance . -* 2020 Work Diary +* 2023 Work Diary ** Q1 -*** 2020-02-29 +*** 2023-02-29 **** DONE 0700 yoga **** UNPLANNED @@ -5293,13 +5252,13 @@ $ hledger -f a.timedot --alias /\\./=: bal --tree  File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top -12 PART 3: REPORTING CONCEPTS +13 PART 3: REPORTING CONCEPTS *****************************  File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top -13 Time periods +14 Time periods *************** * Menu: @@ -5313,7 +5272,7 @@ File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING C  File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods -13.1 Report start & end date +14.1 Report start & end date ============================ By default, most hledger reports will show the full span of time @@ -5358,7 +5317,7 @@ thismonth'  File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods -13.2 Smart dates +14.2 Smart dates ================ hledger's user interfaces accept a "smart date" syntax for added @@ -5407,7 +5366,7 @@ periodic transaction rules, which are not affected by '--today'.)  File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods -13.3 Report intervals +14.3 Report intervals ===================== A report interval can be specified so that reports like register, @@ -5429,7 +5388,7 @@ described below.  File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods -13.4 Date adjustment +14.4 Date adjustment ==================== When there is a report interval (other than daily), report start/end @@ -5453,7 +5412,7 @@ period headings.  File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods -13.5 Period expressions +14.5 Period expressions ======================= The '-p/--period' option specifies a period expression, which is a @@ -5513,7 +5472,7 @@ date:  File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions -13.5.1 Period expressions with a report interval +14.5.1 Period expressions with a report interval ------------------------------------------------ A period expression can also begin with a report interval, separated @@ -5526,7 +5485,7 @@ from the start/end dates (if any) by a space or the word 'in':  File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions -13.5.2 More complex report intervals +14.5.2 More complex report intervals ------------------------------------ Some more complex intervals can be specified within period expressions, @@ -5589,7 +5548,7 @@ $ hledger register checking -p "every 3rd day of week"  File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions -13.5.3 Multiple weekday intervals +14.5.3 Multiple weekday intervals --------------------------------- This special form is also supported: @@ -5617,7 +5576,7 @@ weekendday"'  File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top -14 Depth +15 Depth ******** With the '--depth NUM' option (short form: '-NUM'), reports will show @@ -5629,7 +5588,7 @@ equivalent.  File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top -15 Queries +16 Queries ********** One of hledger's strengths is being able to quickly report on a precise @@ -5652,7 +5611,7 @@ arguments to restrict their scope. The syntax is as follows: * Add a query type prefix to match other parts of the data: - 'date:202012- desc:amazon cur:USD amt:">100" status:' + 'date:202312- desc:amazon cur:USD amt:">100" status:' * Add a 'not:' prefix to negate a term: @@ -5670,7 +5629,7 @@ arguments to restrict their scope. The syntax is as follows:  File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries -15.1 Query types +16.1 Query types ================ Here are the types of query term available. Remember these can also be @@ -5759,7 +5718,7 @@ hledger-web to show the transaction register for an account.)  File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries -15.2 Combining query terms +16.2 Combining query terms ========================== When given multiple space-separated query terms, most commands select @@ -5803,18 +5762,18 @@ OR, and NOT, where NOT is different syntax for 'not:'.  File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries -15.3 Queries and command options +16.3 Queries and command options ================================ Some queries can also be expressed as command-line options: 'depth:2' is -equivalent to '--depth 2', 'date:2020' is equivalent to '-p 2020', etc. +equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. When you mix command options and query arguments, generally the resulting query is their intersection.  File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries -15.4 Queries and valuation +16.4 Queries and valuation ========================== When amounts are converted to other commodities in cost or value @@ -5825,7 +5784,7 @@ reversed, see #1625).  File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries -15.5 Querying with account aliases +16.5 Querying with account aliases ================================== When account names are rewritten with '--alias' or 'alias', note that @@ -5834,7 +5793,7 @@ When account names are rewritten with '--alias' or 'alias', note that  File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries -15.6 Querying with cost or value +16.6 Querying with cost or value ================================ When amounts are converted to other commodities in cost or value @@ -5846,7 +5805,7 @@ the discussion at #1625.  File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top -16 Pivoting +17 Pivoting *********** Normally, hledger groups and sums amounts within each account. The @@ -5898,7 +5857,7 @@ $ hledger balance --pivot member acct:.  File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top -17 Generating data +18 Generating data ****************** hledger has several features for generating data, such as: @@ -5937,7 +5896,7 @@ prefix), so eg you could match generated transactions with  File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top -18 Forecasting +19 Forecasting ************** Forecasting, or speculative future reporting, can be useful for @@ -5960,7 +5919,7 @@ when you want to see them.  File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting -18.1 -forecast +19.1 -forecast ============== There is another way: with the '--forecast' option, hledger can generate @@ -5985,7 +5944,7 @@ that the '=' is required.  File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting -18.2 Inspecting forecast transactions +19.2 Inspecting forecast transactions ===================================== 'print' is the best command for inspecting and troubleshooting forecast @@ -6029,7 +5988,7 @@ reproducible.)  File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting -18.3 Forecast reports +19.3 Forecast reports ===================== Forecast transactions affect all reports, as you would expect. Eg: @@ -6054,7 +6013,7 @@ Balance changes in 2023-05-01..2023-09-30:  File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting -18.4 Forecast tags +19.4 Forecast tags ================== Forecast transactions generated by -forecast have a hidden tag, @@ -6070,7 +6029,7 @@ rule was responsible.  File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting -18.5 Forecast period, in detail +19.5 Forecast period, in detail =============================== Forecast start/end dates are chosen so as to do something useful by @@ -6101,7 +6060,7 @@ default in almost all situations, while also being flexible. Here are  File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting -18.6 Forecast troubleshooting +19.6 Forecast troubleshooting ============================= When -forecast is not doing what you expect, one of these tips should @@ -6129,7 +6088,7 @@ help:  File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top -19 Budgeting +20 Budgeting ************ With the balance command's '--budget' report, each periodic transaction @@ -6146,7 +6105,7 @@ bal -M --budget --forecast ...'  File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top -20 Cost reporting +21 Cost reporting ***************** This section is about recording the cost of things, in transactions @@ -6182,7 +6141,7 @@ currency, or a stock purchase or sale. First, a quick glossary:  File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting -20.1 -B: Convert to cost +21.1 -B: Convert to cost ======================== As discussed in JOURNAL > Costs, when recording a transaction you can @@ -6226,7 +6185,7 @@ equation and tends to causes a non-zero total in balance reports.  File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting -20.2 Equity conversion postings +21.2 Equity conversion postings =============================== By contrast, conventional double entry bookkeeping (DEB) uses a @@ -6254,7 +6213,7 @@ not-so-clear transaction balancing error message.  File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting -20.3 Inferring equity postings from cost +21.3 Inferring equity postings from cost ======================================== With '--infer-equity', hledger detects transactions written with PTA @@ -6282,7 +6241,7 @@ entries for sharing with non-PTA-users.  File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting -20.4 Inferring cost from equity postings +21.4 Inferring cost from equity postings ======================================== The reverse operation is possible using '--infer-costs', which detects @@ -6339,7 +6298,7 @@ mixture of both notations in your journal.  File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting -20.5 When to infer cost/equity +21.5 When to infer cost/equity ============================== Inferring equity postings or costs is still fairly new, so not enabled @@ -6355,7 +6314,7 @@ suggestions to try, experience reports welcome:  File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting -20.6 How to record conversions +21.6 How to record conversions ============================== Essentially there are four ways to record a conversion transaction in @@ -6371,7 +6330,7 @@ hledger. Here are all of them, with pros and cons.  File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions -20.6.1 Conversion with implicit cost +21.6.1 Conversion with implicit cost ------------------------------------ Let's assume 100 EUR is converted to 120 USD. You can just record the @@ -6406,7 +6365,7 @@ check balancednoautoconversion', or '-s/--strict'.  File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions -20.6.2 Conversion with explicit cost +21.6.2 Conversion with explicit cost ------------------------------------ You can add the conversion rate using @ notation: @@ -6432,7 +6391,7 @@ error otherwise.  File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions -20.6.3 Conversion with equity postings +21.6.3 Conversion with equity postings -------------------------------------- In strict double entry bookkeeping, the above transaction is not @@ -6464,7 +6423,7 @@ each commodity, using an equity account:  File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions -20.6.4 Conversion with equity postings and explicit cost +21.6.4 Conversion with equity postings and explicit cost -------------------------------------------------------- Here both equity postings and @ notation are used together. @@ -6490,7 +6449,7 @@ Here both equity postings and @ notation are used together.  File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting -20.7 Cost tips +21.7 Cost tips ============== * Recording the cost/conversion rate explicitly is good because it @@ -6510,7 +6469,7 @@ File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cos  File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top -21 Valuation +22 Valuation ************ Instead of reporting amounts in their original commodity, hledger can @@ -6537,7 +6496,7 @@ and '-X COMMODITY' options, and often one of these is all you need:  File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation -21.1 -V: Value +22.1 -V: Value ============== The '-V/--market' flag converts amounts to market value in their default @@ -6547,7 +6506,7 @@ _valuation date(s)_, if any. More on these in a minute.  File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation -21.2 -X: Value in specified commodity +22.2 -X: Value in specified commodity ===================================== The '-X/--exchange=COMM' option is like '-V', except you tell it which @@ -6557,7 +6516,7 @@ that.  File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation -21.3 Valuation date +22.3 Valuation date =================== Since market prices can change from day to day, market value reports @@ -6574,7 +6533,7 @@ of the period, by default.  File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation -21.4 Finding market price +22.4 Finding market price ========================= To convert a commodity A to its market value in another commodity B, @@ -6608,7 +6567,7 @@ converted.  File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation -21.5 -infer-market-prices: market prices from transactions +22.5 -infer-market-prices: market prices from transactions ========================================================== Normally, market value in hledger is fully controlled by, and requires, @@ -6694,7 +6653,7 @@ P 2022-01-03 B A -1.0  File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation -21.6 Valuation commodity +22.6 Valuation commodity ======================== *When you specify a valuation commodity ('-X COMM' or '--value @@ -6733,7 +6692,7 @@ converted.  File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation -21.7 Simple valuation examples +22.7 Simple valuation examples ============================== Here are some quick examples of '-V': @@ -6768,7 +6727,7 @@ $ hledger -f t.j bal -N euros -V  File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation -21.8 -value: Flexible valuation +22.8 -value: Flexible valuation =============================== '-V' and '-X' are special cases of the more general '--value' option: @@ -6810,7 +6769,7 @@ this commodity, deducing market prices as described above.  File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation -21.9 More valuation examples +22.9 More valuation examples ============================ Here are some examples showing the effect of '--value', as seen with @@ -6924,7 +6883,7 @@ $ hledger print -X A  File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation -21.10 Interaction of valuation and queries +22.10 Interaction of valuation and queries ========================================== When matching postings based on queries in the presence of valuation, @@ -6945,7 +6904,7 @@ the following happens.  File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation -21.11 Effect of valuation on reports +22.11 Effect of valuation on reports ==================================== Here is a reference for how valuation is supposed to affect each part of @@ -7094,7 +7053,7 @@ _report interval_  File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top -22 PART 4: COMMANDS +23 PART 4: COMMANDS ******************* * Menu: @@ -7133,7 +7092,7 @@ File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: V  File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS -22.1 Commands overview +23.1 Commands overview ====================== Here are the built-in commands: @@ -7152,7 +7111,7 @@ Here are the built-in commands:  File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview -22.1.1 DATA ENTRY +23.1.1 DATA ENTRY ----------------- These data entry commands are the only ones which can modify your @@ -7164,7 +7123,7 @@ journal file.  File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview -22.1.2 DATA CREATION +23.1.2 DATA CREATION -------------------- * close - generate balance-zeroing/restoring transactions @@ -7173,7 +7132,7 @@ File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA EN  File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview -22.1.3 DATA MANAGEMENT +23.1.3 DATA MANAGEMENT ---------------------- * check - check for various kinds of error in the data @@ -7182,7 +7141,7 @@ File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DAT  File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview -22.1.4 REPORTS, FINANCIAL +23.1.4 REPORTS, FINANCIAL ------------------------- * aregister (areg) - show transactions in a particular account @@ -7194,7 +7153,7 @@ File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: D  File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview -22.1.5 REPORTS, VERSATILE +23.1.5 REPORTS, VERSATILE ------------------------- * balance (bal) - show balance changes, end balances, budgets, @@ -7207,7 +7166,7 @@ File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPOR  File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview -22.1.6 REPORTS, BASIC +23.1.6 REPORTS, BASIC --------------------- * accounts - show account names @@ -7226,7 +7185,7 @@ File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE,  File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview -22.1.7 HELP +23.1.7 HELP ----------- * help - show the hledger manual with info/man/pager @@ -7235,7 +7194,7 @@ File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Comm  File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview -22.1.8 ADD-ONS +23.1.8 ADD-ONS -------------- And here are some typical add-on commands. Some of these are installed @@ -7255,7 +7214,7 @@ hledger's commands list:  File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS -22.2 accounts +23.2 accounts ============= Show account names. @@ -7312,7 +7271,7 @@ $ hledger check accounts  File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS -22.3 activity +23.3 activity ============= Show an ascii barchart of posting counts per interval. @@ -7332,7 +7291,7 @@ $ hledger activity --quarterly  File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS -22.4 add +23.4 add ======== Prompt for transactions and add them to the journal. Any arguments will @@ -7402,7 +7361,7 @@ file path ends with a period, as that would cause problems (#1056).  File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS -22.5 aregister +23.5 aregister ============== (areg) @@ -7477,7 +7436,7 @@ options. The output formats supported are 'txt', 'csv', and 'json'.  File: hledger.info, Node: aregister and custom posting dates, Up: aregister -22.5.1 aregister and custom posting dates +23.5.1 aregister and custom posting dates ----------------------------------------- Transactions whose date is outside the report period can still be shown, @@ -7493,7 +7452,7 @@ it's probably best to assume the running balance is wrong.  File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS -22.6 balance +23.6 balance ============ (bal) @@ -7532,7 +7491,7 @@ more control, then use 'balance'.  File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance -22.6.1 balance features +23.6.1 balance features ----------------------- Here's a quick overview of the 'balance' command's features, followed by @@ -7595,7 +7554,7 @@ in the transactions of the postings which would normally be shown.  File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance -22.6.2 Simple balance report +23.6.2 Simple balance report ---------------------------- With no arguments, 'balance' shows a list of all accounts and their @@ -7644,7 +7603,7 @@ $ hledger -f examples/sample.journal bal -E  File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance -22.6.3 Balance report line format +23.6.3 Balance report line format --------------------------------- For single-period balance reports displayed in the terminal (only), you @@ -7707,7 +7666,7 @@ may be needed to get pleasing results.  File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance -22.6.4 Filtered balance report +23.6.4 Filtered balance report ------------------------------ You can show fewer accounts, a different time period, totals from @@ -7722,7 +7681,7 @@ $ hledger -f examples/sample.journal bal --cleared assets date:200806  File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance -22.6.5 List or tree mode +23.6.5 List or tree mode ------------------------ By default, or with '-l/--flat', accounts are shown as a flat list with @@ -7765,7 +7724,7 @@ $ hledger -f examples/sample.journal balance  File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance -22.6.6 Depth limiting +23.6.6 Depth limiting --------------------- With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: @@ -7787,7 +7746,7 @@ $ hledger -f examples/sample.journal balance -1  File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance -22.6.7 Dropping top-level accounts +23.6.7 Dropping top-level accounts ---------------------------------- You can also hide one or more top-level account name parts, using @@ -7803,7 +7762,7 @@ $ hledger -f examples/sample.journal bal expenses --drop 1  File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance -22.6.8 Showing declared accounts +23.6.8 Showing declared accounts -------------------------------- With '--declared', accounts which have been declared with an account @@ -7821,7 +7780,7 @@ accounts yet.  File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance -22.6.9 Sorting by amount +23.6.9 Sorting by amount ------------------------ With '-S/--sort-amount', accounts with the largest (most positive) @@ -7839,7 +7798,7 @@ which flip the sign automatically. Eg: 'hledger incomestatement -MAS').  File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance -22.6.10 Percentages +23.6.10 Percentages ------------------- With '-%/--percent', balance reports show each account's value expressed @@ -7862,7 +7821,7 @@ $ hledger bal -% cur:€  File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance -22.6.11 Multi-period balance report +23.6.11 Multi-period balance report ----------------------------------- With a report interval (set by the '-D/--daily', '-W/--weekly', @@ -7917,7 +7876,7 @@ viewing in the terminal. Here are some ways to handle that:  File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance -22.6.12 Balance change, end balance +23.6.12 Balance change, end balance ----------------------------------- It's important to be clear on the meaning of the numbers shown in @@ -7954,7 +7913,7 @@ historical end balances:  File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance -22.6.13 Balance report types +23.6.13 Balance report types ---------------------------- The balance command is quite flexible; here is the full detail on how to @@ -7977,7 +7936,7 @@ experimentation to get familiar with all the report modes.  File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types -22.6.13.1 Calculation type +23.6.13.1 Calculation type .......................... The basic calculation to perform for each table cell. It is one of: @@ -7995,7 +7954,7 @@ The basic calculation to perform for each table cell. It is one of:  File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types -22.6.13.2 Accumulation type +23.6.13.2 Accumulation type ........................... How amounts should accumulate across report periods. Another way to say @@ -8020,7 +7979,7 @@ calculation. It is one of:  File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types -22.6.13.3 Valuation type +23.6.13.3 Valuation type ........................ Which kind of value or cost conversion should be applied, if any, before @@ -8051,7 +8010,7 @@ displaying the report. It is one of:  File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types -22.6.13.4 Combining balance report types +23.6.13.4 Combining balance report types ........................................ Most combinations of these options should produce reasonable reports, @@ -8090,7 +8049,7 @@ Accumulation:v YYYY-MM-DD  File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance -22.6.14 Budget report +23.6.14 Budget report --------------------- The '--budget' report type activates extra columns showing any budget @@ -8225,7 +8184,7 @@ currencies, '--layout bare' or '--layout tall' can help.  File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report -22.6.14.1 Budget report start date +23.6.14.1 Budget report start date .................................. This might be a bug, but for now: when making budget reports, it's a @@ -8269,7 +8228,7 @@ Budget performance in 2020-01-01..2020-01-15:  File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report -22.6.14.2 Budgets and subaccounts +23.6.14.2 Budgets and subaccounts ................................. You can add budgets to any account in your account hierarchy. If you @@ -8357,7 +8316,7 @@ Budget performance in 2019/01:  File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report -22.6.14.3 Selecting budget goals +23.6.14.3 Selecting budget goals ................................ The budget report evaluates periodic transaction rules to generate @@ -8383,7 +8342,7 @@ select from multiple budgets defined in your journal.  File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report -22.6.14.4 Budget vs forecast +23.6.14.4 Budget vs forecast ............................ 'hledger --forecast ...' and 'hledger balance --budget ...' are separate @@ -8431,7 +8390,7 @@ time if you want. Here are some differences between them, as of hledger  File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance -22.6.15 Data layout +23.6.15 Data layout ------------------- The '--layout' option affects how balance reports show multi-commodity @@ -8566,7 +8525,7 @@ tidy Y  File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance -22.6.16 Useful balance reports +23.6.16 Useful balance reports ------------------------------ Some frequently used 'balance' options/reports are: @@ -8606,7 +8565,7 @@ Some frequently used 'balance' options/reports are:  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS -22.7 balancesheet +23.7 balancesheet ================= (bs) @@ -8655,7 +8614,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS -22.8 balancesheetequity +23.8 balancesheetequity ======================= (bse) @@ -8709,7 +8668,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS -22.9 cashflow +23.9 cashflow ============= (cf) @@ -8762,7 +8721,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS -22.10 check +23.10 check =========== Check for various kinds of errors in your data. @@ -8795,7 +8754,7 @@ run these checks, providing instant feedback as you edit the journal.  File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check -22.10.1 Basic checks +23.10.1 Basic checks -------------------- These checks are always run automatically, by (almost) all hledger @@ -8814,7 +8773,7 @@ commands, including 'check':  File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check -22.10.2 Strict checks +23.10.2 Strict checks --------------------- These additional checks are run when the '-s'/'--strict' (strict mode) @@ -8832,7 +8791,7 @@ flag is used. Or, they can be run by giving their names as arguments to  File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check -22.10.3 Other checks +23.10.3 Other checks -------------------- These checks can be run only by giving their names as arguments to @@ -8853,7 +8812,7 @@ therefore optional:  File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check -22.10.4 Custom checks +23.10.4 Custom checks --------------------- A few more checks are are available as separate add-on commands, in @@ -8871,7 +8830,7 @@ See: Cookbook -> Scripting.  File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check -22.10.5 More about specific checks +23.10.5 More about specific checks ---------------------------------- 'hledger check recentassertions' will complain if any balance-asserted @@ -8889,7 +8848,7 @@ assertions against real-world balances.  File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS -22.11 close +23.11 close =========== (equity) @@ -8972,7 +8931,7 @@ report period will be the closing date; eg '-e 2022' means "close on  File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Up: close -22.11.1 close and balance assertions +23.11.1 close and balance assertions ------------------------------------ Balance assertions will be generated, verifying that the accounts have @@ -9010,7 +8969,7 @@ single-day transactions:  File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close -22.11.2 Example: retain earnings +23.11.2 Example: retain earnings -------------------------------- Record 2022's revenues/expenses as retained earnings on 2022-12-31, @@ -9027,7 +8986,7 @@ $ hledger -f 2022.journal is not:desc:'retain earnings'  File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close -22.11.3 Example: migrate balances to a new file +23.11.3 Example: migrate balances to a new file ----------------------------------------------- Close assets/liabilities/equity on 2022-12-31 and re-open them on @@ -9047,7 +9006,7 @@ $ hledger -f 2022.journal bs not:desc:'closing balances'  File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close -22.11.4 Example: excluding closing/opening transactions +23.11.4 Example: excluding closing/opening transactions ------------------------------------------------------- When combining many files for multi-year reports, the closing/opening @@ -9097,7 +9056,7 @@ $ hledger -f all.journal bs -e2023 not:tag:clopen=2023  File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS -22.12 codes +23.12 codes =========== List the codes seen in transactions, in the order parsed. @@ -9145,7 +9104,7 @@ $ hledger codes -E  File: hledger.info, Node: commodities, Next: demo, Prev: codes, Up: PART 4 COMMANDS -22.13 commodities +23.13 commodities ================= List all commodity/currency symbols used or declared in the journal. @@ -9153,7 +9112,7 @@ List all commodity/currency symbols used or declared in the journal.  File: hledger.info, Node: demo, Next: descriptions, Prev: commodities, Up: PART 4 COMMANDS -22.14 demo +23.14 demo ========== Play demos of hledger usage in the terminal, if asciinema is installed. @@ -9180,7 +9139,7 @@ $ hledger demo install -- -s5 -i.5 # play the install demo at 5x speed,  File: hledger.info, Node: descriptions, Next: diff, Prev: demo, Up: PART 4 COMMANDS -22.15 descriptions +23.15 descriptions ================== List the unique descriptions that appear in transactions. @@ -9199,7 +9158,7 @@ Person A  File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS -22.16 diff +23.16 diff ========== Compares a particular account's transactions in two input files. It @@ -9233,7 +9192,7 @@ These transactions are in the second file only:  File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS -22.17 files +23.17 files =========== List all files included in the journal. With a REGEX argument, only @@ -9242,7 +9201,7 @@ file names matching the regular expression (case sensitive) are shown.  File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS -22.18 help +23.18 help ========== Show the hledger user manual in the terminal, with 'info', 'man', or a @@ -9277,7 +9236,7 @@ $ hledger help -m journal # show it with man, even if info is installed  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS -22.19 import +23.19 import ============ Read new transactions added to each FILE since last run, and add them to @@ -9309,7 +9268,7 @@ most common import source, and these docs focus on that case.  File: hledger.info, Node: Deduplication, Next: Import testing, Up: import -22.19.1 Deduplication +23.19.1 Deduplication --------------------- As a convenience 'import' does _deduplication_ while reading @@ -9353,7 +9312,7 @@ certain date.  File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import -22.19.2 Import testing +23.19.2 Import testing ---------------------- With '--dry-run', the transactions that will be imported are printed to @@ -9378,7 +9337,7 @@ import.  File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import -22.19.3 Importing balance assignments +23.19.3 Importing balance assignments ------------------------------------- Entries added by import will have their posting amounts made explicit @@ -9397,7 +9356,7 @@ please test it and send a pull request.)  File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import -22.19.4 Commodity display styles +23.19.4 Commodity display styles -------------------------------- Imported amounts will be formatted according to the canonical commodity @@ -9406,7 +9365,7 @@ styles (declared or inferred) in the main journal file.  File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS -22.20 incomestatement +23.20 incomestatement ===================== (is) @@ -9456,7 +9415,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS -22.21 notes +23.21 notes =========== List the unique notes that appear in transactions. @@ -9475,7 +9434,7 @@ Snacks  File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS -22.22 payees +23.22 payees ============ List the unique payee/payer names that appear in transactions. @@ -9500,7 +9459,7 @@ Person A  File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS -22.23 prices +23.23 prices ============ Print market price directives from the journal. With @@ -9512,7 +9471,7 @@ displayed with their full precision.  File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS -22.24 print +23.24 print =========== Show transaction journal entries, sorted by date. @@ -9636,7 +9595,7 @@ $ hledger print -Ocsv  File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS -22.25 register +23.25 register ============== (reg) @@ -9746,7 +9705,7 @@ no posting will be shown and the program exit code will be non-zero.  File: hledger.info, Node: Custom register output, Up: register -22.25.1 Custom register output +23.25.1 Custom register output ------------------------------ register uses the full terminal width by default, except on windows. @@ -9778,7 +9737,7 @@ options The output formats supported are 'txt', 'csv', and  File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS -22.26 rewrite +23.26 rewrite ============= Print all transactions, rewriting the postings of matched transactions. @@ -9831,7 +9790,7 @@ commodity.  File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite -22.26.1 Re-write rules in a file +23.26.1 Re-write rules in a file -------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -9869,7 +9828,7 @@ postings.  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite -22.26.2 Diff output format +23.26.2 Diff output format -------------------------- To use this tool for batch modification of your journal files you may @@ -9910,7 +9869,7 @@ output from 'hledger print'.  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite -22.26.3 rewrite vs. print -auto +23.26.3 rewrite vs. print -auto ------------------------------- This command predates print -auto, and currently does much the same @@ -9930,7 +9889,7 @@ thing, but with these differences:  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: PART 4 COMMANDS -22.27 roi +23.27 roi ========= Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on @@ -9978,7 +9937,7 @@ display, regardless of the length of reporting interval.  File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi -22.27.1 Spaces and special characters in '--inv' and +23.27.1 Spaces and special characters in '--inv' and ---------------------------------------------------- '--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries @@ -9997,7 +9956,7 @@ $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'  File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi -22.27.2 Semantics of '--inv' and '--pnl' +23.27.2 Semantics of '--inv' and '--pnl' ---------------------------------------- Query supplied to '--inv' has to match all transactions that are related @@ -10051,7 +10010,7 @@ postings in the example below would be classifed as:  File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi -22.27.3 IRR and TWR explained +23.27.3 IRR and TWR explained ----------------------------- "ROI" stands for "return on investment". Traditionally this was @@ -10118,7 +10077,7 @@ your investment.  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS -22.28 stats +23.28 stats =========== Show journal and performance statistics. @@ -10158,7 +10117,7 @@ Throughput : 8342 txns/s  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS -22.29 tags +23.29 tags ========== List the tags used in the journal, or their values. @@ -10188,7 +10147,7 @@ transactions also acquire tags from their postings.  File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS -22.30 test +23.30 test ========== Run built-in unit tests. @@ -10214,7 +10173,7 @@ $ hledger test -- -pData.Amount --color=never  File: hledger.info, Node: PART 5 COMMON TASKS, Next: BUGS, Prev: PART 4 COMMANDS, Up: Top -23 PART 5: COMMON TASKS +24 PART 5: COMMON TASKS *********************** Here are some quick examples of how to do some basic tasks with hledger. @@ -10224,6 +10183,7 @@ Here are some quick examples of how to do some basic tasks with hledger. * Getting help:: * Constructing command lines:: * Starting a journal file:: +* Setting LEDGER_FILE:: * Setting opening balances:: * Recording transactions:: * Reconciling:: @@ -10233,7 +10193,7 @@ Here are some quick examples of how to do some basic tasks with hledger.  File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS -23.1 Getting help +24.1 Getting help ================= Here's how to list commands and view options and command docs: @@ -10256,7 +10216,7 @@ can be found at https://hledger.org/support.  File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS -23.2 Constructing command lines +24.2 Constructing command lines =============================== hledger has a flexible command line interface. We strive to keep it @@ -10274,9 +10234,9 @@ described in OPTIONS, here are some tips that might help: '--debug=2'.  -File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS +File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: PART 5 COMMON TASKS -23.3 Starting a journal file +24.3 Starting a journal file ============================ hledger looks for your accounting data in a journal file, @@ -10288,19 +10248,19 @@ Please create it first, eg with "hledger add" or a text editor. Or, specify an existing journal file with -f or LEDGER_FILE. You can override this by setting the 'LEDGER_FILE' environment -variable. It's a good practice to keep this important file under -version control, and to start a new file each year. So you could do -something like this: +variable (see below). It's a good practice to keep this important file +under version control, and to start a new file each year. So you could +do something like this: $ mkdir ~/finance $ cd ~/finance $ git init Initialized empty Git repository in /Users/simon/finance/.git/ -$ touch 2020.journal -$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc -$ source ~/.bashrc +$ touch 2023.journal +$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile +$ source ~/.profile $ hledger stats -Main file : /Users/simon/finance/2020.journal +Main file : /Users/simon/finance/2023.journal Included files : Transactions span : to (0 days) Last transaction : none @@ -10313,9 +10273,45 @@ Commodities : 0 () Market prices : 0 ()  -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS +File: hledger.info, Node: Setting LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: PART 5 COMMON TASKS -23.4 Setting opening balances +24.4 Setting LEDGER_FILE +======================== + +How to set 'LEDGER_FILE' permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for +many people; adapt as needed: + +$ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile +$ source ~/.profile + + When correctly configured, in a new terminal window 'env | grep +LEDGER_FILE' will show your file, and so will 'hledger files'. + + On mac, this additional step might be helpful for GUI applications +(like Emacs started from the dock): add an entry to +'~/.MacOSX/environment.plist' like + +{ + "LEDGER_FILE" : "~/finance/2023.journal" +} + + and then run 'killall Dock' in a terminal window (or restart the +machine). + + On Windows, see https://www.java.com/en/download/help/path.html, or +try running these commands in a powershell window (let us know if it +persists across a reboot, and if you need to be an Administrator): + +> CD +> MKDIR finance +> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: PART 5 COMMON TASKS + +24.5 Setting opening balances ============================= Pick a starting date for which you can look up the balances of some @@ -10334,7 +10330,7 @@ balances on this date. Here are two ways to do it: * The first way: open the journal in any text editor and save an entry like this: - 2020-01-01 * opening balances + 2023-01-01 * opening balances assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 @@ -10357,7 +10353,7 @@ balances on this date. Here are two ways to do it: a similar transaction: $ hledger add - Adding transactions to journal file /Users/simon/finance/2020.journal + Adding transactions to journal file /Users/simon/finance/2023.journal Any command line arguments will be used as defaults. Use tab key to complete, readline keys to edit, enter to accept defaults. An optional (CODE) may follow transaction dates. @@ -10365,7 +10361,7 @@ balances on this date. Here are two ways to do it: If you make a mistake, enter < at any prompt to go one step backward. To end a transaction, enter . when prompted. To quit, enter . at a date prompt or press control-d or control-c. - Date [2020-02-07]: 2020-01-01 + Date [2023-02-07]: 2023-01-01 Description: * opening balances Account 1: assets:bank:checking Amount 1: $1000 @@ -10378,7 +10374,7 @@ balances on this date. Here are two ways to do it: Account 5: equity:opening/closing balances Amount 5 [$-3050]: Account 6 (or . or enter to finish this transaction): . - 2020-01-01 * opening balances + 2023-01-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 @@ -10388,17 +10384,17 @@ balances on this date. Here are two ways to do it: Save this transaction to the journal ? [y]: Saved. Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2020-01-01]: . + Date [2023-01-01]: . If you're using version control, this could be a good time to commit the journal. Eg: -$ git commit -m 'initial balances' 2020.journal +$ git commit -m 'initial balances' 2023.journal  File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS -23.5 Recording transactions +24.6 Recording transactions =========================== As you spend or receive money, you can record these transactions using @@ -10409,22 +10405,22 @@ convert CSV data downloaded from your bank. Here are some simple transactions, see the hledger_journal(5) manual and hledger.org for more ideas: -2020/1/10 * gift received +2023/1/10 * gift received assets:cash $20 income:gifts -2020.1.12 * farmers market +2023.1.12 * farmers market expenses:food $13 assets:cash -2020-01-15 paycheck +2023-01-15 paycheck income:salary assets:bank:checking $1000  File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS -23.6 Reconciling +24.7 Reconciling ================ Periodically you should reconcile - compare your hledger-reported @@ -10446,7 +10442,7 @@ discrepancies. adjustment transaction. Eg if you have $105 after the above, and can't explain the missing $2, it could be: - 2020-01-16 * adjust cash + 2023-01-16 * adjust cash assets:cash $-2 = $105 expenses:misc @@ -10469,17 +10465,17 @@ live-updating register while you edit the journal: 'hledger-ui --watch After reconciling, it could be a good time to mark the reconciled transactions' status as "cleared and confirmed", if you want to track that, by adding the '*' marker. Eg in the paycheck transaction above, -insert '*' between '2020-01-15' and 'paycheck' +insert '*' between '2023-01-15' and 'paycheck' If you're using version control, this can be another good time to commit: -$ git commit -m 'txns' 2020.journal +$ git commit -m 'txns' 2023.journal  File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS -23.7 Reporting +24.8 Reporting ============== Here are some basic reports. @@ -10487,26 +10483,26 @@ Here are some basic reports. Show all transactions: $ hledger print -2020-01-01 * opening balances +2023-01-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 liabilities:creditcard $-50 equity:opening/closing balances $-3050 -2020-01-10 * gift received +2023-01-10 * gift received assets:cash $20 income:gifts -2020-01-12 * farmers market +2023-01-12 * farmers market expenses:food $13 assets:cash -2020-01-15 * paycheck +2023-01-15 * paycheck income:salary assets:bank:checking $1000 -2020-01-16 * adjust cash +2023-01-16 * adjust cash assets:cash $-2 = $105 expenses:misc @@ -10562,9 +10558,9 @@ $ hledger bal assets liabilities -2 balance sheet: $ hledger bs -2 -Balance Sheet 2020-01-16 +Balance Sheet 2023-01-16 - || 2020-01-16 + || 2023-01-16 ========================++============ Assets || ------------------------++------------ @@ -10587,9 +10583,9 @@ for a full balance sheet with equity.) Show income and expense totals, formatted as an income statement: hledger is -Income Statement 2020-01-01-2020-01-16 +Income Statement 2023-01-01-2023-01-16 - || 2020-01-01-2020-01-16 + || 2023-01-01-2023-01-16 ===============++======================= Revenues || ---------------++----------------------- @@ -10612,22 +10608,22 @@ Income Statement 2020-01-01-2020-01-16 Show transactions affecting your wallet, with running total: $ hledger register cash -2020-01-01 opening balances assets:cash $100 $100 -2020-01-10 gift received assets:cash $20 $120 -2020-01-12 farmers market assets:cash $-13 $107 -2020-01-16 adjust cash assets:cash $-2 $105 +2023-01-01 opening balances assets:cash $100 $100 +2023-01-10 gift received assets:cash $20 $120 +2023-01-12 farmers market assets:cash $-13 $107 +2023-01-16 adjust cash assets:cash $-2 $105 Show weekly posting counts as a bar chart: $ hledger activity -W 2019-12-30 ***** -2020-01-06 **** -2020-01-13 **** +2023-01-06 **** +2023-01-13 ****  File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS -23.8 Migrating to a new file +24.9 Migrating to a new file ============================ At the end of the year, you may want to continue your journal in a new @@ -10640,7 +10636,7 @@ close command.  File: hledger.info, Node: BUGS, Prev: PART 5 COMMON TASKS, Up: Top -24 BUGS +25 BUGS ******* We welcome bug reports in the hledger issue tracker (shortcut: @@ -10672,7 +10668,7 @@ Ledger.  File: hledger.info, Node: Troubleshooting, Up: BUGS -24.1 Troubleshooting +25.1 Troubleshooting ==================== Here are some common issues you might encounter when you run hledger, @@ -10723,636 +10719,640 @@ See hledger and Ledger for full details.  Tag Table: Node: Top210 -Node: PART 1 USER INTERFACE3780 -Ref: #part-1-user-interface3919 -Node: Input3919 -Ref: #input4032 -Node: Setting LEDGER_FILE4994 -Ref: #setting-ledger_file5126 -Node: Data formats6107 -Ref: #data-formats6248 -Node: Standard input7681 -Ref: #standard-input7821 -Node: Multiple files8048 -Ref: #multiple-files8187 -Node: Strict mode8785 -Ref: #strict-mode8895 -Node: Environment9619 -Ref: #environment9730 -Node: Options10274 -Ref: #options10380 -Node: General options10752 -Ref: #general-options10879 -Node: Option repetition15455 -Ref: #option-repetition15610 -Node: Command options15929 -Ref: #command-options16082 -Node: Command arguments16482 -Ref: #command-arguments16640 -Node: Special characters17520 -Ref: #special-characters17683 -Node: Single escaping shell metacharacters17846 -Ref: #single-escaping-shell-metacharacters18087 -Node: Double escaping regular expression metacharacters18690 -Ref: #double-escaping-regular-expression-metacharacters19001 -Node: Triple escaping for add-on commands19527 -Ref: #triple-escaping-for-add-on-commands19787 -Node: Less escaping20431 -Ref: #less-escaping20585 -Node: Unicode characters20909 -Ref: #unicode-characters21074 -Node: Regular expressions22486 -Ref: #regular-expressions22626 -Node: Commands24370 -Ref: #commands24473 -Node: Add-on commands24945 -Ref: #add-on-commands25047 -Node: Output26132 -Ref: #output26243 -Node: Output destination26370 -Ref: #output-destination26501 -Node: Output format26926 -Ref: #output-format27072 -Node: CSV output28610 -Ref: #csv-output28726 -Node: HTML output28829 -Ref: #html-output28967 -Node: JSON output29061 -Ref: #json-output29199 -Node: SQL output30121 -Ref: #sql-output30237 -Node: Commodity styles30972 -Ref: #commodity-styles31112 -Node: Colour31711 -Ref: #colour31829 -Node: Box-drawing32233 -Ref: #box-drawing32351 -Node: Paging32641 -Ref: #paging32755 -Node: Debug output33708 -Ref: #debug-output33814 -Node: PART 2 DATA FORMATS34477 -Ref: #part-2-data-formats34615 -Node: Journal34615 -Ref: #journal34724 -Node: Journal cheatsheet35381 -Ref: #journal-cheatsheet35520 -Node: About journal format39505 -Ref: #about-journal-format39665 -Node: Comments41281 -Ref: #comments41411 -Node: Transactions42227 -Ref: #transactions42350 -Node: Dates43364 -Ref: #dates43471 -Node: Simple dates43516 -Ref: #simple-dates43632 -Node: Posting dates44132 -Ref: #posting-dates44250 -Node: Status45219 -Ref: #status45320 -Node: Code47028 -Ref: #code47131 -Node: Description47363 -Ref: #description47494 -Node: Payee and note47814 -Ref: #payee-and-note47920 -Node: Transaction comments48255 -Ref: #transaction-comments48408 -Node: Postings48771 -Ref: #postings48904 -Node: Account names49899 -Ref: #account-names50029 -Node: Amounts51703 -Ref: #amounts51818 -Node: Decimal marks digit group marks52803 -Ref: #decimal-marks-digit-group-marks52978 -Node: Commodity53992 -Ref: #commodity54179 -Node: Directives influencing number parsing and display55131 -Ref: #directives-influencing-number-parsing-and-display55390 -Node: Commodity display style55842 -Ref: #commodity-display-style56048 -Node: Rounding58217 -Ref: #rounding58335 -Node: Costs58634 -Ref: #costs58750 -Node: Other cost/lot notations60948 -Ref: #other-costlot-notations61080 -Node: Balance assertions63669 -Ref: #balance-assertions63820 -Node: Assertions and ordering64903 -Ref: #assertions-and-ordering65092 -Node: Assertions and multiple included files65792 -Ref: #assertions-and-multiple-included-files66052 -Node: Assertions and multiple -f files66552 -Ref: #assertions-and-multiple--f-files66803 -Node: Assertions and commodities67200 -Ref: #assertions-and-commodities67422 -Node: Assertions and prices68602 -Ref: #assertions-and-prices68808 -Node: Assertions and subaccounts69235 -Ref: #assertions-and-subaccounts69456 -Node: Assertions and virtual postings69780 -Ref: #assertions-and-virtual-postings70018 -Node: Assertions and auto postings70150 -Ref: #assertions-and-auto-postings70380 -Node: Assertions and precision71025 -Ref: #assertions-and-precision71207 -Node: Posting comments71474 -Ref: #posting-comments71620 -Node: Tags71997 -Ref: #tags72111 -Node: Tag values73304 -Ref: #tag-values73393 -Node: Directives74152 -Ref: #directives74279 -Node: Directives and multiple files75609 -Ref: #directives-and-multiple-files75787 -Node: Directive effects76554 -Ref: #directive-effects76708 -Node: account directive79721 -Ref: #account-directive79877 -Node: Account comments81275 -Ref: #account-comments81425 -Node: Account subdirectives81933 -Ref: #account-subdirectives82124 -Node: Account error checking82266 -Ref: #account-error-checking82464 -Node: Account display order83653 -Ref: #account-display-order83841 -Node: Account types84942 -Ref: #account-types85083 -Node: alias directive88710 -Ref: #alias-directive88871 -Node: Basic aliases89921 -Ref: #basic-aliases90052 -Node: Regex aliases90796 -Ref: #regex-aliases90953 -Node: Combining aliases91843 -Ref: #combining-aliases92021 -Node: Aliases and multiple files93297 -Ref: #aliases-and-multiple-files93501 -Node: end aliases directive94080 -Ref: #end-aliases-directive94299 -Node: Aliases can generate bad account names94448 -Ref: #aliases-can-generate-bad-account-names94696 -Node: Aliases and account types95281 -Ref: #aliases-and-account-types95473 -Node: commodity directive96169 -Ref: #commodity-directive96343 -Node: Commodity error checking98917 -Ref: #commodity-error-checking99063 -Node: decimal-mark directive99578 -Ref: #decimal-mark-directive99760 -Node: include directive100157 -Ref: #include-directive100321 -Node: P directive101245 -Ref: #p-directive101390 -Node: payee directive102273 -Ref: #payee-directive102422 -Node: tag directive102738 -Ref: #tag-directive102893 -Node: Periodic transactions103361 -Ref: #periodic-transactions103526 -Node: Periodic rule syntax105232 -Ref: #periodic-rule-syntax105410 -Node: Periodic rules and relative dates106055 -Ref: #periodic-rules-and-relative-dates106321 -Node: Two spaces between period expression and description!106832 -Ref: #two-spaces-between-period-expression-and-description107109 -Node: Auto postings107793 -Ref: #auto-postings107941 -Node: Auto postings and multiple files110378 -Ref: #auto-postings-and-multiple-files110542 -Node: Auto postings and dates110943 -Ref: #auto-postings-and-dates111191 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions111366 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions111722 -Node: Auto posting tags112225 -Ref: #auto-posting-tags112507 -Node: Auto postings on forecast transactions only113143 -Ref: #auto-postings-on-forecast-transactions-only113389 -Node: Other syntax113636 -Ref: #other-syntax113752 -Node: Balance assignments114379 -Ref: #balance-assignments114535 -Node: Balance assignments and prices115865 -Ref: #balance-assignments-and-prices116033 -Node: Bracketed posting dates116244 -Ref: #bracketed-posting-dates116428 -Node: D directive116942 -Ref: #d-directive117110 -Node: apply account directive118710 -Ref: #apply-account-directive118890 -Node: Y directive119577 -Ref: #y-directive119737 -Node: Secondary dates120565 -Ref: #secondary-dates120719 -Node: Star comments121533 -Ref: #star-comments121693 -Node: Valuation expressions122225 -Ref: #valuation-expressions122402 -Node: Virtual postings122524 -Ref: #virtual-postings122701 -Node: Other Ledger directives124263 -Ref: #other-ledger-directives124426 -Node: CSV124992 -Ref: #csv125083 -Node: CSV rules cheatsheet127163 -Ref: #csv-rules-cheatsheet127290 -Node: source129088 -Ref: #source129209 -Node: separator130089 -Ref: #separator130200 -Node: skip130740 -Ref: #skip130846 -Node: date-format131390 -Ref: #date-format131509 -Node: timezone132233 -Ref: #timezone132354 -Node: newest-first133359 -Ref: #newest-first133495 -Node: intra-day-reversed134073 -Ref: #intra-day-reversed134225 -Node: decimal-mark134718 -Ref: #decimal-mark134857 -Node: fields list135196 -Ref: #fields-list135333 -Node: Field assignment137004 -Ref: #field-assignment137146 -Node: Field names138173 -Ref: #field-names138302 -Node: date field139505 -Ref: #date-field139621 -Node: date2 field139669 -Ref: #date2-field139808 -Node: status field139864 -Ref: #status-field140005 -Node: code field140054 -Ref: #code-field140197 -Node: description field140242 -Ref: #description-field140400 -Node: comment field140459 -Ref: #comment-field140612 -Node: account field140905 -Ref: #account-field141053 -Node: amount field141623 -Ref: #amount-field141770 -Node: currency field145146 -Ref: #currency-field145297 -Node: balance field145554 -Ref: #balance-field145684 -Node: if block146056 -Ref: #if-block146175 -Node: Matchers147583 -Ref: #matchers147695 -Node: if table149177 -Ref: #if-table149297 -Node: balance-type150719 -Ref: #balance-type150846 -Node: include151546 -Ref: #include151671 -Node: Working with CSV152115 -Ref: #working-with-csv152260 -Node: Rapid feedback152667 -Ref: #rapid-feedback152798 -Node: Valid CSV153250 -Ref: #valid-csv153394 -Node: File Extension154126 -Ref: #file-extension154297 -Node: Reading CSV from standard input154861 -Ref: #reading-csv-from-standard-input155083 -Node: Reading multiple CSV files155247 -Ref: #reading-multiple-csv-files155476 -Node: Reading files specified by rule155717 -Ref: #reading-files-specified-by-rule155943 -Node: Valid transactions157114 -Ref: #valid-transactions157311 -Node: Deduplicating importing157939 -Ref: #deduplicating-importing158132 -Node: Setting amounts159168 -Ref: #setting-amounts159337 -Node: Amount signs161802 -Ref: #amount-signs161970 -Node: Setting currency/commodity162867 -Ref: #setting-currencycommodity163069 -Node: Amount decimal places164243 -Ref: #amount-decimal-places164447 -Node: Referencing other fields164759 -Ref: #referencing-other-fields164970 -Node: How CSV rules are evaluated165867 -Ref: #how-csv-rules-are-evaluated166082 -Node: Well factored rules167535 -Ref: #well-factored-rules167701 -Node: CSV rules examples168025 -Ref: #csv-rules-examples168158 -Node: Bank of Ireland168223 -Ref: #bank-of-ireland168358 -Node: Coinbase169820 -Ref: #coinbase169956 -Node: Amazon171003 -Ref: #amazon171126 -Node: Paypal172845 -Ref: #paypal172951 -Node: Timeclock180595 -Ref: #timeclock180700 -Node: Timedot182878 -Ref: #timedot183001 -Node: PART 3 REPORTING CONCEPTS187870 -Ref: #part-3-reporting-concepts188034 -Node: Time periods188034 -Ref: #time-periods188168 -Node: Report start & end date188286 -Ref: #report-start-end-date188438 -Node: Smart dates190097 -Ref: #smart-dates190250 -Node: Report intervals192118 -Ref: #report-intervals192273 -Node: Date adjustment192691 -Ref: #date-adjustment192851 -Node: Period expressions193702 -Ref: #period-expressions193843 -Node: Period expressions with a report interval195607 -Ref: #period-expressions-with-a-report-interval195841 -Node: More complex report intervals196055 -Ref: #more-complex-report-intervals196300 -Node: Multiple weekday intervals198101 -Ref: #multiple-weekday-intervals198290 -Node: Depth199112 -Ref: #depth199214 -Node: Queries199510 -Ref: #queries199612 -Node: Query types200521 -Ref: #query-types200642 -Node: Combining query terms203816 -Ref: #combining-query-terms203993 -Node: Queries and command options205261 -Ref: #queries-and-command-options205460 -Node: Queries and valuation205709 -Ref: #queries-and-valuation205904 -Node: Querying with account aliases206133 -Ref: #querying-with-account-aliases206344 -Node: Querying with cost or value206474 -Ref: #querying-with-cost-or-value206651 -Node: Pivoting206952 -Ref: #pivoting207066 -Node: Generating data208524 -Ref: #generating-data208656 -Node: Forecasting210239 -Ref: #forecasting210364 -Node: --forecast210895 -Ref: #forecast211026 -Node: Inspecting forecast transactions212072 -Ref: #inspecting-forecast-transactions212274 -Node: Forecast reports213404 -Ref: #forecast-reports213577 -Node: Forecast tags214513 -Ref: #forecast-tags214673 -Node: Forecast period in detail215133 -Ref: #forecast-period-in-detail215327 -Node: Forecast troubleshooting216221 -Ref: #forecast-troubleshooting216389 -Node: Budgeting217292 -Ref: #budgeting217412 -Node: Cost reporting217849 -Ref: #cost-reporting217977 -Node: -B Convert to cost219084 -Ref: #b-convert-to-cost219240 -Node: Equity conversion postings220632 -Ref: #equity-conversion-postings220846 -Node: Inferring equity postings from cost221737 -Ref: #inferring-equity-postings-from-cost221986 -Node: Inferring cost from equity postings222797 -Ref: #inferring-cost-from-equity-postings223045 -Node: When to infer cost/equity224812 -Ref: #when-to-infer-costequity225030 -Node: How to record conversions225426 -Ref: #how-to-record-conversions225618 -Node: Conversion with implicit cost225909 -Ref: #conversion-with-implicit-cost226114 -Node: Conversion with explicit cost226991 -Ref: #conversion-with-explicit-cost227236 -Node: Conversion with equity postings227653 -Ref: #conversion-with-equity-postings227922 -Node: Conversion with equity postings and explicit cost228741 -Ref: #conversion-with-equity-postings-and-explicit-cost229008 -Node: Cost tips229470 -Ref: #cost-tips229596 -Node: Valuation230302 -Ref: #valuation230426 -Node: -V Value231200 -Ref: #v-value231326 -Node: -X Value in specified commodity231521 -Ref: #x-value-in-specified-commodity231716 -Node: Valuation date231865 -Ref: #valuation-date232036 -Node: Finding market price232473 -Ref: #finding-market-price232678 -Node: --infer-market-prices market prices from transactions233848 -Ref: #infer-market-prices-market-prices-from-transactions234124 -Node: Valuation commodity236880 -Ref: #valuation-commodity237093 -Node: Simple valuation examples238306 -Ref: #simple-valuation-examples238504 -Node: --value Flexible valuation239163 -Ref: #value-flexible-valuation239367 -Node: More valuation examples241011 -Ref: #more-valuation-examples241220 -Node: Interaction of valuation and queries243219 -Ref: #interaction-of-valuation-and-queries243460 -Node: Effect of valuation on reports243932 -Ref: #effect-of-valuation-on-reports244129 -Node: PART 4 COMMANDS251826 -Ref: #part-4-commands251969 -Node: Commands overview252348 -Ref: #commands-overview252482 -Node: DATA ENTRY252661 -Ref: #data-entry252785 -Node: DATA CREATION252984 -Ref: #data-creation253138 -Node: DATA MANAGEMENT253256 -Ref: #data-management253421 -Node: REPORTS FINANCIAL253542 -Ref: #reports-financial253717 -Node: REPORTS VERSATILE254022 -Ref: #reports-versatile254195 -Node: REPORTS BASIC254448 -Ref: #reports-basic254600 -Node: HELP255109 -Ref: #help255231 -Node: ADD-ONS255341 -Ref: #add-ons255447 -Node: accounts256026 -Ref: #accounts256159 -Node: activity258046 -Ref: #activity258165 -Node: add258539 -Ref: #add258649 -Node: aregister261460 -Ref: #aregister261581 -Node: aregister and custom posting dates264469 -Ref: #aregister-and-custom-posting-dates264635 -Node: balance265187 -Ref: #balance265313 -Node: balance features266288 -Ref: #balance-features266428 -Node: Simple balance report268387 -Ref: #simple-balance-report268572 -Node: Balance report line format270197 -Ref: #balance-report-line-format270399 -Node: Filtered balance report272557 -Ref: #filtered-balance-report272749 -Node: List or tree mode273076 -Ref: #list-or-tree-mode273244 -Node: Depth limiting274589 -Ref: #depth-limiting274755 -Node: Dropping top-level accounts275356 -Ref: #dropping-top-level-accounts275556 -Node: Showing declared accounts275866 -Ref: #showing-declared-accounts276065 -Node: Sorting by amount276596 -Ref: #sorting-by-amount276763 -Node: Percentages277433 -Ref: #percentages277592 -Node: Multi-period balance report278140 -Ref: #multi-period-balance-report278340 -Node: Balance change end balance280615 -Ref: #balance-change-end-balance280824 -Node: Balance report types282252 -Ref: #balance-report-types282433 -Node: Calculation type282931 -Ref: #calculation-type283086 -Node: Accumulation type283635 -Ref: #accumulation-type283815 -Node: Valuation type284717 -Ref: #valuation-type284905 -Node: Combining balance report types285900 -Ref: #combining-balance-report-types286094 -Node: Budget report287932 -Ref: #budget-report288084 -Node: Budget report start date293738 -Ref: #budget-report-start-date293916 -Node: Budgets and subaccounts295248 -Ref: #budgets-and-subaccounts295455 -Node: Selecting budget goals298895 -Ref: #selecting-budget-goals299094 -Node: Budget vs forecast300129 -Ref: #budget-vs-forecast300288 -Node: Data layout301918 -Ref: #data-layout302068 -Node: Useful balance reports309963 -Ref: #useful-balance-reports310113 -Node: balancesheet311198 -Ref: #balancesheet311343 -Node: balancesheetequity312663 -Ref: #balancesheetequity312821 -Node: cashflow314210 -Ref: #cashflow314341 -Node: check315769 -Ref: #check315883 -Node: Basic checks316685 -Ref: #basic-checks316805 -Node: Strict checks317325 -Ref: #strict-checks317468 -Node: Other checks317891 -Ref: #other-checks318033 -Node: Custom checks318596 -Ref: #custom-checks318753 -Node: More about specific checks319170 -Ref: #more-about-specific-checks319332 -Node: close320060 -Ref: #close320171 -Node: close and balance assertions323581 -Ref: #close-and-balance-assertions323759 -Node: Example retain earnings324910 -Ref: #example-retain-earnings325127 -Node: Example migrate balances to a new file325559 -Ref: #example-migrate-balances-to-a-new-file325824 -Node: Example excluding closing/opening transactions326400 -Ref: #example-excluding-closingopening-transactions326649 -Node: codes327867 -Ref: #codes327984 -Node: commodities328848 -Ref: #commodities328976 -Node: demo329046 -Ref: #demo329167 -Node: descriptions330011 -Ref: #descriptions330141 -Node: diff330432 -Ref: #diff330547 -Node: files331589 -Ref: #files331698 -Node: help331839 -Ref: #help-1331948 -Node: import333321 -Ref: #import333444 -Node: Deduplication334530 -Ref: #deduplication334655 -Node: Import testing336549 -Ref: #import-testing336714 -Node: Importing balance assignments337557 -Ref: #importing-balance-assignments337763 -Node: Commodity display styles338412 -Ref: #commodity-display-styles338585 -Node: incomestatement338714 -Ref: #incomestatement338856 -Node: notes340177 -Ref: #notes340299 -Node: payees340661 -Ref: #payees340776 -Node: prices341295 -Ref: #prices341410 -Node: print341708 -Ref: #print341823 -Node: register347161 -Ref: #register347283 -Node: Custom register output352314 -Ref: #custom-register-output352445 -Node: rewrite353782 -Ref: #rewrite353900 -Node: Re-write rules in a file355798 -Ref: #re-write-rules-in-a-file355961 -Node: Diff output format357110 -Ref: #diff-output-format357293 -Node: rewrite vs print --auto358385 -Ref: #rewrite-vs.-print---auto358545 -Node: roi359101 -Ref: #roi359208 -Node: Spaces and special characters in --inv and --pnl360929 -Ref: #spaces-and-special-characters-in---inv-and---pnl361169 -Node: Semantics of --inv and --pnl361657 -Ref: #semantics-of---inv-and---pnl361896 -Node: IRR and TWR explained363746 -Ref: #irr-and-twr-explained363906 -Node: stats366992 -Ref: #stats367100 -Node: tags368487 -Ref: #tags-1368594 -Node: test369603 -Ref: #test369696 -Node: PART 5 COMMON TASKS370438 -Ref: #part-5-common-tasks370584 -Node: Getting help370858 -Ref: #getting-help370999 -Node: Constructing command lines371759 -Ref: #constructing-command-lines371960 -Node: Starting a journal file372617 -Ref: #starting-a-journal-file372824 -Node: Setting opening balances374012 -Ref: #setting-opening-balances374217 -Node: Recording transactions377358 -Ref: #recording-transactions377547 -Node: Reconciling378103 -Ref: #reconciling378255 -Node: Reporting380512 -Ref: #reporting380661 -Node: Migrating to a new file384646 -Ref: #migrating-to-a-new-file384803 -Node: BUGS385102 -Ref: #bugs385192 -Node: Troubleshooting386071 -Ref: #troubleshooting386171 +Node: PART 1 USER INTERFACE3802 +Ref: #part-1-user-interface3941 +Node: Input3941 +Ref: #input4051 +Node: Data formats5000 +Ref: #data-formats5113 +Node: Standard input6546 +Ref: #standard-input6686 +Node: Multiple files6913 +Ref: #multiple-files7052 +Node: Strict mode7650 +Ref: #strict-mode7760 +Node: Commands8484 +Ref: #commands8586 +Node: Add-on commands9653 +Ref: #add-on-commands9755 +Node: Options10871 +Ref: #options10983 +Node: General help options11311 +Ref: #general-help-options11457 +Node: General input options11739 +Ref: #general-input-options11921 +Node: General reporting options12623 +Ref: #general-reporting-options12784 +Node: Command line tips16174 +Ref: #command-line-tips16304 +Node: Option repetition16563 +Ref: #option-repetition16707 +Node: Special characters17026 +Ref: #special-characters17199 +Node: Single escaping shell metacharacters17362 +Ref: #single-escaping-shell-metacharacters17603 +Node: Double escaping regular expression metacharacters18206 +Ref: #double-escaping-regular-expression-metacharacters18517 +Node: Triple escaping for add-on commands19043 +Ref: #triple-escaping-for-add-on-commands19303 +Node: Less escaping19947 +Ref: #less-escaping20101 +Node: Unicode characters20425 +Ref: #unicode-characters20600 +Node: Regular expressions22012 +Ref: #regular-expressions22185 +Node: Argument files23929 +Ref: #argument-files24065 +Node: Output24700 +Ref: #output24812 +Node: Output destination24939 +Ref: #output-destination25070 +Node: Output format25495 +Ref: #output-format25641 +Node: CSV output27179 +Ref: #csv-output27295 +Node: HTML output27398 +Ref: #html-output27536 +Node: JSON output27630 +Ref: #json-output27768 +Node: SQL output28690 +Ref: #sql-output28806 +Node: Commodity styles29541 +Ref: #commodity-styles29681 +Node: Colour30280 +Ref: #colour30398 +Node: Box-drawing30802 +Ref: #box-drawing30920 +Node: Paging31210 +Ref: #paging31324 +Node: Debug output32277 +Ref: #debug-output32383 +Node: Environment33046 +Ref: #environment33170 +Node: PART 2 DATA FORMATS33714 +Ref: #part-2-data-formats33857 +Node: Journal33857 +Ref: #journal33966 +Node: Journal cheatsheet34623 +Ref: #journal-cheatsheet34762 +Node: About journal format38747 +Ref: #about-journal-format38907 +Node: Comments40523 +Ref: #comments40653 +Node: Transactions41469 +Ref: #transactions41592 +Node: Dates42606 +Ref: #dates42713 +Node: Simple dates42758 +Ref: #simple-dates42874 +Node: Posting dates43374 +Ref: #posting-dates43492 +Node: Status44461 +Ref: #status44562 +Node: Code46270 +Ref: #code46373 +Node: Description46605 +Ref: #description46736 +Node: Payee and note47056 +Ref: #payee-and-note47162 +Node: Transaction comments47497 +Ref: #transaction-comments47650 +Node: Postings48013 +Ref: #postings48146 +Node: Account names49141 +Ref: #account-names49271 +Node: Amounts50945 +Ref: #amounts51060 +Node: Decimal marks digit group marks52045 +Ref: #decimal-marks-digit-group-marks52220 +Node: Commodity53234 +Ref: #commodity53421 +Node: Directives influencing number parsing and display54373 +Ref: #directives-influencing-number-parsing-and-display54632 +Node: Commodity display style55084 +Ref: #commodity-display-style55290 +Node: Rounding57459 +Ref: #rounding57577 +Node: Costs57876 +Ref: #costs57992 +Node: Other cost/lot notations60190 +Ref: #other-costlot-notations60322 +Node: Balance assertions62911 +Ref: #balance-assertions63062 +Node: Assertions and ordering64145 +Ref: #assertions-and-ordering64334 +Node: Assertions and multiple included files65034 +Ref: #assertions-and-multiple-included-files65294 +Node: Assertions and multiple -f files65794 +Ref: #assertions-and-multiple--f-files66045 +Node: Assertions and commodities66442 +Ref: #assertions-and-commodities66664 +Node: Assertions and prices67844 +Ref: #assertions-and-prices68050 +Node: Assertions and subaccounts68477 +Ref: #assertions-and-subaccounts68698 +Node: Assertions and virtual postings69022 +Ref: #assertions-and-virtual-postings69260 +Node: Assertions and auto postings69392 +Ref: #assertions-and-auto-postings69622 +Node: Assertions and precision70267 +Ref: #assertions-and-precision70449 +Node: Posting comments70716 +Ref: #posting-comments70862 +Node: Tags71239 +Ref: #tags71353 +Node: Tag values72546 +Ref: #tag-values72635 +Node: Directives73394 +Ref: #directives73521 +Node: Directives and multiple files74851 +Ref: #directives-and-multiple-files75029 +Node: Directive effects75796 +Ref: #directive-effects75950 +Node: account directive78963 +Ref: #account-directive79119 +Node: Account comments80517 +Ref: #account-comments80667 +Node: Account subdirectives81175 +Ref: #account-subdirectives81366 +Node: Account error checking81508 +Ref: #account-error-checking81706 +Node: Account display order82895 +Ref: #account-display-order83083 +Node: Account types84184 +Ref: #account-types84325 +Node: alias directive87952 +Ref: #alias-directive88113 +Node: Basic aliases89163 +Ref: #basic-aliases89294 +Node: Regex aliases90038 +Ref: #regex-aliases90195 +Node: Combining aliases91085 +Ref: #combining-aliases91263 +Node: Aliases and multiple files92539 +Ref: #aliases-and-multiple-files92743 +Node: end aliases directive93322 +Ref: #end-aliases-directive93541 +Node: Aliases can generate bad account names93690 +Ref: #aliases-can-generate-bad-account-names93938 +Node: Aliases and account types94523 +Ref: #aliases-and-account-types94715 +Node: commodity directive95411 +Ref: #commodity-directive95585 +Node: Commodity error checking98159 +Ref: #commodity-error-checking98305 +Node: decimal-mark directive98820 +Ref: #decimal-mark-directive99002 +Node: include directive99399 +Ref: #include-directive99563 +Node: P directive100487 +Ref: #p-directive100632 +Node: payee directive101515 +Ref: #payee-directive101664 +Node: tag directive101980 +Ref: #tag-directive102135 +Node: Periodic transactions102603 +Ref: #periodic-transactions102768 +Node: Periodic rule syntax104474 +Ref: #periodic-rule-syntax104652 +Node: Periodic rules and relative dates105297 +Ref: #periodic-rules-and-relative-dates105563 +Node: Two spaces between period expression and description!106074 +Ref: #two-spaces-between-period-expression-and-description106351 +Node: Auto postings107035 +Ref: #auto-postings107183 +Node: Auto postings and multiple files109620 +Ref: #auto-postings-and-multiple-files109784 +Node: Auto postings and dates110185 +Ref: #auto-postings-and-dates110433 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions110608 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions110964 +Node: Auto posting tags111467 +Ref: #auto-posting-tags111749 +Node: Auto postings on forecast transactions only112385 +Ref: #auto-postings-on-forecast-transactions-only112631 +Node: Other syntax112878 +Ref: #other-syntax112994 +Node: Balance assignments113621 +Ref: #balance-assignments113777 +Node: Balance assignments and prices115107 +Ref: #balance-assignments-and-prices115275 +Node: Bracketed posting dates115486 +Ref: #bracketed-posting-dates115670 +Node: D directive116184 +Ref: #d-directive116352 +Node: apply account directive117952 +Ref: #apply-account-directive118132 +Node: Y directive118819 +Ref: #y-directive118979 +Node: Secondary dates119807 +Ref: #secondary-dates119961 +Node: Star comments120775 +Ref: #star-comments120935 +Node: Valuation expressions121467 +Ref: #valuation-expressions121644 +Node: Virtual postings121766 +Ref: #virtual-postings121943 +Node: Other Ledger directives123505 +Ref: #other-ledger-directives123668 +Node: CSV124234 +Ref: #csv124327 +Node: CSV rules cheatsheet126407 +Ref: #csv-rules-cheatsheet126536 +Node: source128334 +Ref: #source128457 +Node: separator129337 +Ref: #separator129450 +Node: skip129990 +Ref: #skip130098 +Node: date-format130642 +Ref: #date-format130763 +Node: timezone131487 +Ref: #timezone131610 +Node: newest-first132615 +Ref: #newest-first132753 +Node: intra-day-reversed133331 +Ref: #intra-day-reversed133485 +Node: decimal-mark133978 +Ref: #decimal-mark134119 +Node: fields list134458 +Ref: #fields-list134597 +Node: Field assignment136268 +Ref: #field-assignment136412 +Node: Field names137439 +Ref: #field-names137570 +Node: date field138773 +Ref: #date-field138891 +Node: date2 field138939 +Ref: #date2-field139080 +Node: status field139136 +Ref: #status-field139279 +Node: code field139328 +Ref: #code-field139473 +Node: description field139518 +Ref: #description-field139678 +Node: comment field139737 +Ref: #comment-field139892 +Node: account field140185 +Ref: #account-field140335 +Node: amount field140905 +Ref: #amount-field141054 +Node: currency field144430 +Ref: #currency-field144583 +Node: balance field144840 +Ref: #balance-field144972 +Node: if block145344 +Ref: #if-block145465 +Node: Matchers146873 +Ref: #matchers146987 +Node: if table148469 +Ref: #if-table148591 +Node: balance-type150013 +Ref: #balance-type150142 +Node: include150842 +Ref: #include150969 +Node: Working with CSV151413 +Ref: #working-with-csv151560 +Node: Rapid feedback151967 +Ref: #rapid-feedback152100 +Node: Valid CSV152552 +Ref: #valid-csv152698 +Node: File Extension153430 +Ref: #file-extension153603 +Node: Reading CSV from standard input154167 +Ref: #reading-csv-from-standard-input154391 +Node: Reading multiple CSV files154555 +Ref: #reading-multiple-csv-files154786 +Node: Reading files specified by rule155027 +Ref: #reading-files-specified-by-rule155255 +Node: Valid transactions156426 +Ref: #valid-transactions156625 +Node: Deduplicating importing157253 +Ref: #deduplicating-importing157448 +Node: Setting amounts158484 +Ref: #setting-amounts158655 +Node: Amount signs161120 +Ref: #amount-signs161290 +Node: Setting currency/commodity162187 +Ref: #setting-currencycommodity162391 +Node: Amount decimal places163565 +Ref: #amount-decimal-places163771 +Node: Referencing other fields164083 +Ref: #referencing-other-fields164296 +Node: How CSV rules are evaluated165193 +Ref: #how-csv-rules-are-evaluated165410 +Node: Well factored rules166863 +Ref: #well-factored-rules167031 +Node: CSV rules examples167355 +Ref: #csv-rules-examples167490 +Node: Bank of Ireland167555 +Ref: #bank-of-ireland167692 +Node: Coinbase169154 +Ref: #coinbase169292 +Node: Amazon170339 +Ref: #amazon170464 +Node: Paypal172183 +Ref: #paypal172291 +Node: Timeclock179935 +Ref: #timeclock180040 +Node: Timedot182218 +Ref: #timedot182341 +Node: PART 3 REPORTING CONCEPTS187210 +Ref: #part-3-reporting-concepts187374 +Node: Time periods187374 +Ref: #time-periods187508 +Node: Report start & end date187626 +Ref: #report-start-end-date187778 +Node: Smart dates189437 +Ref: #smart-dates189590 +Node: Report intervals191458 +Ref: #report-intervals191613 +Node: Date adjustment192031 +Ref: #date-adjustment192191 +Node: Period expressions193042 +Ref: #period-expressions193183 +Node: Period expressions with a report interval194947 +Ref: #period-expressions-with-a-report-interval195181 +Node: More complex report intervals195395 +Ref: #more-complex-report-intervals195640 +Node: Multiple weekday intervals197441 +Ref: #multiple-weekday-intervals197630 +Node: Depth198452 +Ref: #depth198554 +Node: Queries198850 +Ref: #queries198952 +Node: Query types199861 +Ref: #query-types199982 +Node: Combining query terms203156 +Ref: #combining-query-terms203333 +Node: Queries and command options204601 +Ref: #queries-and-command-options204800 +Node: Queries and valuation205049 +Ref: #queries-and-valuation205244 +Node: Querying with account aliases205473 +Ref: #querying-with-account-aliases205684 +Node: Querying with cost or value205814 +Ref: #querying-with-cost-or-value205991 +Node: Pivoting206292 +Ref: #pivoting206406 +Node: Generating data207864 +Ref: #generating-data207996 +Node: Forecasting209579 +Ref: #forecasting209704 +Node: --forecast210235 +Ref: #forecast210366 +Node: Inspecting forecast transactions211412 +Ref: #inspecting-forecast-transactions211614 +Node: Forecast reports212744 +Ref: #forecast-reports212917 +Node: Forecast tags213853 +Ref: #forecast-tags214013 +Node: Forecast period in detail214473 +Ref: #forecast-period-in-detail214667 +Node: Forecast troubleshooting215561 +Ref: #forecast-troubleshooting215729 +Node: Budgeting216632 +Ref: #budgeting216752 +Node: Cost reporting217189 +Ref: #cost-reporting217317 +Node: -B Convert to cost218424 +Ref: #b-convert-to-cost218580 +Node: Equity conversion postings219972 +Ref: #equity-conversion-postings220186 +Node: Inferring equity postings from cost221077 +Ref: #inferring-equity-postings-from-cost221326 +Node: Inferring cost from equity postings222137 +Ref: #inferring-cost-from-equity-postings222385 +Node: When to infer cost/equity224152 +Ref: #when-to-infer-costequity224370 +Node: How to record conversions224766 +Ref: #how-to-record-conversions224958 +Node: Conversion with implicit cost225249 +Ref: #conversion-with-implicit-cost225454 +Node: Conversion with explicit cost226331 +Ref: #conversion-with-explicit-cost226576 +Node: Conversion with equity postings226993 +Ref: #conversion-with-equity-postings227262 +Node: Conversion with equity postings and explicit cost228081 +Ref: #conversion-with-equity-postings-and-explicit-cost228348 +Node: Cost tips228810 +Ref: #cost-tips228936 +Node: Valuation229642 +Ref: #valuation229766 +Node: -V Value230540 +Ref: #v-value230666 +Node: -X Value in specified commodity230861 +Ref: #x-value-in-specified-commodity231056 +Node: Valuation date231205 +Ref: #valuation-date231376 +Node: Finding market price231813 +Ref: #finding-market-price232018 +Node: --infer-market-prices market prices from transactions233188 +Ref: #infer-market-prices-market-prices-from-transactions233464 +Node: Valuation commodity236220 +Ref: #valuation-commodity236433 +Node: Simple valuation examples237646 +Ref: #simple-valuation-examples237844 +Node: --value Flexible valuation238503 +Ref: #value-flexible-valuation238707 +Node: More valuation examples240351 +Ref: #more-valuation-examples240560 +Node: Interaction of valuation and queries242559 +Ref: #interaction-of-valuation-and-queries242800 +Node: Effect of valuation on reports243272 +Ref: #effect-of-valuation-on-reports243469 +Node: PART 4 COMMANDS251166 +Ref: #part-4-commands251309 +Node: Commands overview251688 +Ref: #commands-overview251822 +Node: DATA ENTRY252001 +Ref: #data-entry252125 +Node: DATA CREATION252324 +Ref: #data-creation252478 +Node: DATA MANAGEMENT252596 +Ref: #data-management252761 +Node: REPORTS FINANCIAL252882 +Ref: #reports-financial253057 +Node: REPORTS VERSATILE253362 +Ref: #reports-versatile253535 +Node: REPORTS BASIC253788 +Ref: #reports-basic253940 +Node: HELP254449 +Ref: #help254571 +Node: ADD-ONS254681 +Ref: #add-ons254787 +Node: accounts255366 +Ref: #accounts255499 +Node: activity257386 +Ref: #activity257505 +Node: add257879 +Ref: #add257989 +Node: aregister260800 +Ref: #aregister260921 +Node: aregister and custom posting dates263809 +Ref: #aregister-and-custom-posting-dates263975 +Node: balance264527 +Ref: #balance264653 +Node: balance features265628 +Ref: #balance-features265768 +Node: Simple balance report267727 +Ref: #simple-balance-report267912 +Node: Balance report line format269537 +Ref: #balance-report-line-format269739 +Node: Filtered balance report271897 +Ref: #filtered-balance-report272089 +Node: List or tree mode272416 +Ref: #list-or-tree-mode272584 +Node: Depth limiting273929 +Ref: #depth-limiting274095 +Node: Dropping top-level accounts274696 +Ref: #dropping-top-level-accounts274896 +Node: Showing declared accounts275206 +Ref: #showing-declared-accounts275405 +Node: Sorting by amount275936 +Ref: #sorting-by-amount276103 +Node: Percentages276773 +Ref: #percentages276932 +Node: Multi-period balance report277480 +Ref: #multi-period-balance-report277680 +Node: Balance change end balance279955 +Ref: #balance-change-end-balance280164 +Node: Balance report types281592 +Ref: #balance-report-types281773 +Node: Calculation type282271 +Ref: #calculation-type282426 +Node: Accumulation type282975 +Ref: #accumulation-type283155 +Node: Valuation type284057 +Ref: #valuation-type284245 +Node: Combining balance report types285240 +Ref: #combining-balance-report-types285434 +Node: Budget report287272 +Ref: #budget-report287424 +Node: Budget report start date293078 +Ref: #budget-report-start-date293256 +Node: Budgets and subaccounts294588 +Ref: #budgets-and-subaccounts294795 +Node: Selecting budget goals298235 +Ref: #selecting-budget-goals298434 +Node: Budget vs forecast299469 +Ref: #budget-vs-forecast299628 +Node: Data layout301258 +Ref: #data-layout301408 +Node: Useful balance reports309303 +Ref: #useful-balance-reports309453 +Node: balancesheet310538 +Ref: #balancesheet310683 +Node: balancesheetequity312003 +Ref: #balancesheetequity312161 +Node: cashflow313550 +Ref: #cashflow313681 +Node: check315109 +Ref: #check315223 +Node: Basic checks316025 +Ref: #basic-checks316145 +Node: Strict checks316665 +Ref: #strict-checks316808 +Node: Other checks317231 +Ref: #other-checks317373 +Node: Custom checks317936 +Ref: #custom-checks318093 +Node: More about specific checks318510 +Ref: #more-about-specific-checks318672 +Node: close319400 +Ref: #close319511 +Node: close and balance assertions322921 +Ref: #close-and-balance-assertions323099 +Node: Example retain earnings324250 +Ref: #example-retain-earnings324467 +Node: Example migrate balances to a new file324899 +Ref: #example-migrate-balances-to-a-new-file325164 +Node: Example excluding closing/opening transactions325740 +Ref: #example-excluding-closingopening-transactions325989 +Node: codes327207 +Ref: #codes327324 +Node: commodities328188 +Ref: #commodities328316 +Node: demo328386 +Ref: #demo328507 +Node: descriptions329351 +Ref: #descriptions329481 +Node: diff329772 +Ref: #diff329887 +Node: files330929 +Ref: #files331038 +Node: help331179 +Ref: #help-1331288 +Node: import332661 +Ref: #import332784 +Node: Deduplication333870 +Ref: #deduplication333995 +Node: Import testing335889 +Ref: #import-testing336054 +Node: Importing balance assignments336897 +Ref: #importing-balance-assignments337103 +Node: Commodity display styles337752 +Ref: #commodity-display-styles337925 +Node: incomestatement338054 +Ref: #incomestatement338196 +Node: notes339517 +Ref: #notes339639 +Node: payees340001 +Ref: #payees340116 +Node: prices340635 +Ref: #prices340750 +Node: print341048 +Ref: #print341163 +Node: register346501 +Ref: #register346623 +Node: Custom register output351654 +Ref: #custom-register-output351785 +Node: rewrite353122 +Ref: #rewrite353240 +Node: Re-write rules in a file355138 +Ref: #re-write-rules-in-a-file355301 +Node: Diff output format356450 +Ref: #diff-output-format356633 +Node: rewrite vs print --auto357725 +Ref: #rewrite-vs.-print---auto357885 +Node: roi358441 +Ref: #roi358548 +Node: Spaces and special characters in --inv and --pnl360269 +Ref: #spaces-and-special-characters-in---inv-and---pnl360509 +Node: Semantics of --inv and --pnl360997 +Ref: #semantics-of---inv-and---pnl361236 +Node: IRR and TWR explained363086 +Ref: #irr-and-twr-explained363246 +Node: stats366332 +Ref: #stats366440 +Node: tags367827 +Ref: #tags-1367934 +Node: test368943 +Ref: #test369036 +Node: PART 5 COMMON TASKS369778 +Ref: #part-5-common-tasks369924 +Node: Getting help370222 +Ref: #getting-help370363 +Node: Constructing command lines371123 +Ref: #constructing-command-lines371324 +Node: Starting a journal file371981 +Ref: #starting-a-journal-file372183 +Node: Setting LEDGER_FILE373385 +Ref: #setting-ledger_file373577 +Node: Setting opening balances374534 +Ref: #setting-opening-balances374735 +Node: Recording transactions377876 +Ref: #recording-transactions378065 +Node: Reconciling378621 +Ref: #reconciling378773 +Node: Reporting381030 +Ref: #reporting381179 +Node: Migrating to a new file385164 +Ref: #migrating-to-a-new-file385321 +Node: BUGS385620 +Ref: #bugs385710 +Node: Troubleshooting386589 +Ref: #troubleshooting386689  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index ba4a1b9da..1c6c64bcb 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -82,77 +82,45 @@ Input Files are most often in hledger's journal format, with the .journal file extension (.hledger or .j also work); these files describe trans- - actions, like an accounting general journal. Some other supported file - formats are discussed below. + actions, like an accounting general journal. - When no -f option is given, hledger looks for the file specified by the - LEDGER_FILE environment variable; if this is not set, it uses - .hledger.journal in your home directory. + When no file is specified, hledger looks for .hledger.journal in your + home directory. - Most people prefer to keep financial files in a dedicated folder, per- - haps with version control. Also, starting a new journal file per year - is common (it's not required, but helps keep things fast and organ- - ised). So we usually set LEDGER_FILE, to something like ~/fi- - nance/2023.journal. - - Setting LEDGER_FILE - How to set LEDGER_FILE permanently depends on your platform: - - On unix and mac, running these commands in the terminal will work for - many people; adapt as needed: - - $ mkdir -p ~/finance - $ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile - $ source ~/.profile - - When correctly configured, in a new terminal window env | grep - LEDGER_FILE will show your file, and so will hledger files. - - On mac, this additional step might be helpful for GUI applications - (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- - ment.plist like - - { - "LEDGER_FILE" : "~/finance/2023.journal" - } - - and then run killall Dock in a terminal window (or restart the ma- - chine). - - On Windows, see https://www.java.com/en/download/help/path.html, or try - running these commands in a powershell window (let us know if it per- - sists across a reboot, and if you need to be an Administrator): - - > CD - > MKDIR finance - > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + But most people prefer to keep financial files in a dedicated folder, + perhaps with version control. Also, starting a new journal file each + year is common (it's not required, but helps keep things fast and or- + ganised). So we usually configure a different journal file, by setting + the LEDGER_FILE environment variable, to something like ~/fi- + nance/2023.journal. For more about how to do that on your system, see + Common tasks > Setting LEDGER_FILE. Data formats - Usually the data file is in hledger's journal format, but it can be in + Usually the data file is in hledger's journal format, but it can be in any of the supported file formats, which currently are: Reader: Reads: Used for file exten- sions: ----------------------------------------------------------------------------- - journal hledger journal files and some Ledger .journal .j .hledger + journal hledger journal files and some Ledger .journal .j .hledger journals, for transactions .ledger - time- timeclock files, for precise time log- .timeclock + time- timeclock files, for precise time log- .timeclock clock ging timedot timedot files, for approximate time .timedot logging - csv CSV/SSV/TSV/character-separated values, .csv .ssv .tsv + csv CSV/SSV/TSV/character-separated values, .csv .ssv .tsv for data import .csv.rules .ssv.rules .tsv.rules These formats are described in more detail below. - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a recognised file extension, so as to either read successfully or to show relevant error messages. - You can also force a specific reader/format by prefixing the file path + You can also force a specific reader/format by prefixing the file path with the format and a colon. Eg, to read a .dat file as csv format: $ hledger -f csv:/some/csv-file.dat stats @@ -168,23 +136,23 @@ Input $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- Multiple files - You can specify multiple -f options, to read multiple files as one big + You can specify multiple -f options, to read multiple files as one big journal. When doing this, note that certain features (described below) will be affected: - o Balance assertions will not see the effect of transactions in previ- - ous files. (Usually this doesn't matter as each file will set the + o Balance assertions will not see the effect of transactions in previ- + ous files. (Usually this doesn't matter as each file will set the corresponding opening balances.) o Some directives will not affect previous or subsequent files. - If needed, you can work around these by using a single parent file + If needed, you can work around these by using a single parent file which includes the others, or concatenating the files into one, eg: cat a.journal b.journal | hledger -f- CMD. Strict mode hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files + tant errors are detected, while still accepting easy journal files without a lot of declarations: o Are the input files parseable, with valid syntax ? @@ -195,7 +163,7 @@ Input With the -s/--strict flag, additional checks are performed: - o Are all accounts posted to, declared with an account directive ? + o Are all accounts posted to, declared with an account directive ? (Account error checking) o Are all commodities declared with a commodity directive ? (Commodity @@ -203,34 +171,61 @@ Input o Are all commodity conversions declared explicitly ? - You can use the check command to run individual checks -- the ones + You can use the check command to run individual checks -- the ones listed above and some more. -Environment - Environment variables which affect hledger: +Commands + hledger provides various subcommands for getting things done. Most of + these commands do not change the journal file; they just read it and + output a report. A few commands assist with adding data and file man- + agement. - COLUMNS This is normally set by your terminal; some hledger commands - (register) will format their output to this width. If not set, they - will try to use the available terminal width. + To show the commands list, run hledger with no arguments. The commands + are described in detail in PART 4: COMMANDS, below. - LEDGER_FILE The main journal file to use when not specified with - -f/--file. Default: $HOME/.hledger.journal. + To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], - NO_COLOR If this environment variable is set (with any value), hledger - will not use ANSI color codes in terminal output, unless overridden by - an explicit --color/--colour option. + o CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + o CMDOPTS are command-specific options, if any. Command-specific op- + tions must be written after the command name. Eg: hledger print -x. + + o CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit the + data in some way. Eg: hledger reg assets:checking. + + To list a command's options, arguments, and documentation in the termi- + nal, run hledger CMD -h. Eg: hledger bal -h. + + Add-on commands + In addition to the built-in commands, you can install add-on commands: + programs or scripts named "hledger-SOMETHING", which will also appear + in hledger's commands list. If you used the hledger-install script, + you will have several add-ons installed already. Some more can be + found in hledger's bin/ directory, documented at + https://hledger.org/scripts.html. + + More precisely, add-on commands are programs or scripts in your shell's + PATH, whose name starts with "hledger-" and ends with no extension or a + recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", + ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix + and mac) which has executable permission for the current user. + + You can run add-on commands using hledger, much like built-in commands: + hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double + hyphen argument, required before add-on-specific options. Eg: hledger + ui -- --watch or hledger web -- --serve. If this causes difficulty, + you can always run the add-on directly, without using hledger: hledger- + ui --watch or hledger-web --serve. Options - Here is a list of flags and options common to most hledger commands, - and some useful details about hledger command line parsing. But if you - are new to hledger, feel free to skim/skip ahead to the Commands. - - General options - To see general usage help, including general options which are sup- - ported by most hledger commands, run hledger -h. - - General help options: + Run hledger -h to see general command line help, and general options + which are common to most hledger commands. These options can be writ- + ten anywhere on the command line. They can be grouped into help, in- + put, and reporting options: + General help options -h --help show general or COMMAND help @@ -244,14 +239,13 @@ Options --debug[=N] show debug output (levels 1-9, default: 1) - General input options: - + General input options -f FILE --file=FILE use a different input file. For stdin, use - (default: $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 @@ -270,11 +264,10 @@ 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: - + General reporting options -b --begin=DATE include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval) @@ -299,7 +292,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 @@ -307,7 +300,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 @@ -326,21 +319,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 @@ -350,38 +343,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 @@ -389,6 +382,10 @@ Options Some reporting options can also be written as query arguments. +Command line tips + Here are some details useful to know about for hledger command lines + (and elsewhere). Feel free to skip this section until you need it. + Option repetition If options are repeated in a command line, hledger will generally use the last (right-most) occurence. Some of the boolean flags will toggle @@ -396,58 +393,12 @@ Options -%/--percent, -E/--empty, -N/--no-total, -T/--row-total, -A/--average, and -S/--sort-amount. - Command options - To see options for a particular command, including command-specific op- - tions, run: hledger COMMAND -h. - - Command-specific options must be written after the command name, eg: - hledger print -x. - - Additionally, if the command is an add-on, you may need to put its op- - tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can - run the add-on executable directly: hledger-ui --watch. - - Command arguments - Most hledger commands accept arguments after the command name, which - are often a query, filtering the data in some way. - - You can save a set of command line options/arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: - hledger bal @foo.args. (To prevent this, eg if you have an argument - that begins with a literal @, precede it with --, eg: hledger bal -- - @ARG). - - Inside the argument file, each line should contain just one option or - argument. Avoid the use of spaces, except inside quotes (or you'll see - a confusing error). Between a flag and its argument, use = (or noth- - ing). Bad: - - assets depth:2 - -X USD - - Good: - - assets - depth:2 - -X=USD - - For special characters (see below), use one less level of quoting than - you would at the command prompt. Bad: - - -X"$" - - Good: - - -X$ - - See also: Save frequently used options. - Special characters Single escaping (shell metacharacters) - In shell command lines, characters significant to your shell - such as - spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want - hledger to see them. This is done by enclosing them in single or dou- - ble quotes, or by writing a backslash before them. Eg to match an ac- + In shell command lines, characters significant to your shell - such as + spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want + hledger to see them. This is done by enclosing them in single or dou- + ble quotes, or by writing a backslash before them. Eg to match an ac- count name containing a space: $ hledger register 'credit card' @@ -456,17 +407,17 @@ Options $ hledger register credit\ card - Windows users should keep in mind that cmd treats single quote as a - regular character, so you should be using double quotes exclusively. + Windows users should keep in mind that cmd treats single quote as a + regular character, so you should be using double quotes exclusively. PowerShell treats both single and double quotes as quotes. Double escaping (regular expression metacharacters) - Characters significant in regular expressions (described below) - such - as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if - you don't want them to be interpreted by hledger's regular expression - engine. This is done by writing backslashes before them, but since - backslash is typically also a shell metacharacter, both shell-escaping - and regex-escaping will be needed. Eg to match a literal $ sign while + Characters significant in regular expressions (described below) - such + as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if + you don't want them to be interpreted by hledger's regular expression + engine. This is done by writing backslashes before them, but since + backslash is typically also a shell metacharacter, both shell-escaping + and regex-escaping will be needed. Eg to match a literal $ sign while using the bash shell: $ hledger balance cur:'\$' @@ -476,10 +427,10 @@ Options $ hledger balance cur:\\$ Triple escaping (for add-on commands) - When you use hledger to run an external add-on command (described be- + When you use hledger to run an external add-on command (described be- low), one level of shell-escaping is lost from any options or arguments - intended for by the add-on command, so those need an extra level of - shell-escaping. Eg to match a literal $ sign while using the bash + intended for by the add-on command, so those need an extra level of + shell-escaping. Eg to match a literal $ sign while using the bash shell and running an add-on command (ui): $ hledger ui cur:'\\$' @@ -495,14 +446,14 @@ Options double-escaped: \\$ triple-escaped: \\\\$ - Or, you can avoid the extra escaping by running the add-on executable + Or, you can avoid the extra escaping by running the add-on executable directly: $ hledger-ui cur:\\$ Less escaping Options and arguments are sometimes used in places other than the shell - command line, where shell-escaping is not needed, so there you should + command line, where shell-escaping is not needed, so there you should use one less level of escaping. Those places include: o an @argumentfile @@ -516,128 +467,110 @@ Options Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) - o they should be displayed correctly by all hledger tools, and on- + o they should be displayed correctly by all hledger tools, and on- screen alignment should be preserved. This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode o the terminal must be using a font which includes the required unicode glyphs - o the terminal should be configured to display wide characters as dou- + o the terminal should be configured to display wide characters as dou- ble width (for report alignment) - o on Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o on Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Regular expressions hledger uses regular expressions in a number of places: - o query terms, on the command line and in the hledger-web search form: + o query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX o CSV rules conditional blocks: if REGEX ... - o account alias directive and --alias option: alias /REGEX/ = REPLACE- + o account alias directive and --alias option: alias /REGEX/ = REPLACE- MENT, --alias /REGEX/=REPLACEMENT - hledger's regular expressions come from the regex-tdfa library. If - they're not doing what you expect, it's important to know exactly what + hledger's regular expressions come from the regex-tdfa library. If + they're not doing what you expect, it's important to know exactly what they support: 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing + 2. they are infix matching (they do not need to match the entire thing being matched) 3. they are POSIX ERE (extended regular expressions) 4. they also support GNU word boundaries (\b, \B, \<, \>) - 5. they do not support backreferences; if you write \1, it will match - the digit 1. Except when doing text replacement, eg in account - aliases, where backreferences can be used in the replacement string + 5. they do not support backreferences; if you write \1, it will match + the digit 1. Except when doing text replacement, eg in account + aliases, where backreferences can be used in the replacement string to reference capturing groups in the search regexp. - 6. they do not support mode modifiers ((?s)), character classes (\w, + 6. they do not support mode modifiers ((?s)), character classes (\w, \d), or anything else not mentioned above. Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. -Commands - hledger provides a number of built-in subcommands (described below). - Most of these read your data without changing it, and display a report. - A few assist with data entry and management. + Argument files + You can save a set of command line options and arguments in a file, and + then reuse them by writing @FILENAME as a command line argument. Eg: + hledger bal @foo.args. - Run hledger with no arguments to list the commands available, and - hledger CMD to run a command. CMD can be the full command name, or its - standard abbreviation shown in the commands list, or any unambiguous - prefix of the name. Eg: hledger bal. + Inside the argument file, each line should contain just one option or + argument. Also, don't use spaces except inside quotes (or you'll see a + confusing error). Ie, write = (or nothing) between a flag and its ar- + gument. Eg, bad: - Add-on commands - Add-on commands are extra subcommands provided by programs or scripts - in your PATH + assets -X USD - o whose name starts with hledger- + Good: - o whose name ends with a recognised file extension: .bat,.com,.exe, - .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none + assets + -X=USD - o and (on unix, mac) which are executable by the current user. + For the special characters mentioned above, use one less level of quot- + ing than you would at the command prompt. Eg, bad: - Addons can be written in any language, but haskell scripts or programs - have a big advantage: they can use hledger's library code, for command- - line options, parsing and reporting. + -X"$" - Several add-on commands are installed by the hledger-install script. - See https://hledger.org/scripts.html for more details. + Good: - Note in a hledger command line, add-on command flags must have a double - dash (--) preceding them. Eg you must write: + -X$ - $ hledger web -- --serve - - and not: - - $ hledger web --serve - - (because the --serve flag belongs to hledger-web, not hledger). - - The -h/--help and --version flags don't require --. - - If you have any trouble with this, remember you can always run the add- - on program directly, eg: - - $ hledger-web --serve + See also: Save frequently used options. Output Output destination @@ -646,15 +579,15 @@ Output $ hledger print > foo.txt - Some commands (print, register, stats, the balance commands) also pro- - vide the -o/--output-file option, which does the same thing without + Some commands (print, register, stats, the balance commands) also pro- + vide the -o/--output-file option, which does the same thing without needing the shell. Eg: $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) Output format - Some commands offer other kinds of output, not just text on the termi- + Some commands offer other kinds of output, not just text on the termi- nal. Here are those commands and the formats currently supported: - txt csv html json sql @@ -670,19 +603,19 @@ Output o 1 Also affected by the balance commands' --layout option. - o 2 balance does not support html output without a report interval or + o 2 balance does not support html output without a report interval or with --budget. The output format is selected by the -O/--output-format=FMT option: $ hledger print -O csv # print CSV on stdout - or by the filename extension of an output file specified with the + or by the filename extension of an output file specified with the -o/--output-file=FILE.FMT option: $ hledger balancesheet -o foo.csv # write CSV to foo.csv - The -O option can be combined with -o to override the file extension, + The -O option can be combined with -o to override the file extension, if needed: $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt @@ -690,7 +623,7 @@ Output Some notes about the various output formats: CSV output - o In CSV output, digit group marks (such as thousands separators) are + o In CSV output, digit group marks (such as thousands separators) are disabled automatically. HTML output @@ -700,79 +633,79 @@ Output JSON output o This is not yet much used; real-world feedback is welcome. - o Our JSON is rather large and verbose, since it is a faithful repre- - sentation of hledger's internal data types. To understand the JSON, - read the Haskell type definitions, which are mostly in + o Our JSON is rather large and verbose, since it is a faithful repre- + sentation of hledger's internal data types. To understand the JSON, + read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/master/hledger- lib/Hledger/Data/Types.hs. - o hledger represents quantities as Decimal values storing up to 255 - significant digits, eg for repeating decimals. Such numbers can + o hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can arise in practice (from automatically-calculated transaction prices), - and would break most JSON consumers. So in JSON, we show quantities + and would break most JSON consumers. So in JSON, we show quantities as simple Numbers with at most 10 decimal places. We don't limit the - number of integer digits, but that part is under your control. We - hope this approach will not cause problems in practice; if you find + number of integer digits, but that part is under your control. We + hope this approach will not cause problems in practice; if you find otherwise, please let us know. (Cf #1195) SQL output o This is not yet much used; real-world feedback is welcome. - o SQL output is expected to work at least with SQLite, MySQL and Post- + o SQL output is expected to work at least with SQLite, MySQL and Post- gres. - o For SQLite, it will be more useful if you modify the generated id + o For SQLite, it will be more useful if you modify the generated id field to be a PRIMARY KEY. Eg: $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - o SQL output is structured with the expectations that statements will - be executed in the empty database. If you already have tables cre- - ated via SQL output of hledger, you would probably want to either + o SQL output is structured with the expectations that statements will + be executed in the empty database. If you already have tables cre- + ated via SQL output of hledger, you would probably want to either clear tables of existing data (via delete or truncate SQL statements) or drop tables completely as otherwise your postings will be duped. Commodity styles - When displaying amounts, hledger infers a standard display style for + When displaying amounts, hledger infers a standard display style for each commodity/currency, as described below in Commodity display style. If needed, this can be overridden by a -c/--commodity-style option (ex- cept for cost amounts and amounts displayed by the print command, which - are always displayed with all decimal digits). For example, the fol- + are always displayed with all decimal digits). For example, the fol- lowing will force dollar amounts to be displayed as shown: $ hledger print -c '$1.000,0' This option can repeated to set the display style for multiple commodi- - ties/currencies. Its argument is as described in the commodity direc- + ties/currencies. Its argument is as described in the commodity direc- tive. Colour - In terminal output, some commands can produce colour when the terminal + In terminal output, some commands can produce colour when the terminal supports it: - o if the --color/--colour option is given a value of yes or always (or + o if the --color/--colour option is given a value of yes or always (or no or never), colour will (or will not) be used; - o otherwise, if the NO_COLOR environment variable is set, colour will + o otherwise, if the NO_COLOR environment variable is set, colour will not be used; - o otherwise, colour will be used if the output (terminal or file) sup- + o otherwise, colour will be used if the output (terminal or file) sup- ports it. Box-drawing - In terminal output, you can enable unicode box-drawing characters to + In terminal output, you can enable unicode box-drawing characters to render prettier tables: - o if the --pretty option is given a value of yes or always (or no or + o if the --pretty option is given a value of yes or always (or no or never), unicode characters will (or will not) be used; o otherwise, unicode characters will not be used. Paging - When showing long output in the terminal, hledger will try to use the - pager specified by the PAGER environment variable, or less, or more. - (A pager is a helper program that shows one page at a time rather than + When showing long output in the terminal, hledger will try to use the + pager specified by the PAGER environment variable, or less, or more. + (A pager is a helper program that shows one page at a time rather than scrolling everything off screen). Currently it does this only for help output, not for reports; specifically, @@ -782,27 +715,41 @@ Output o when viewing manuals with hledger help or hledger --man. - Note the pager is expected to handle ANSI codes, which hledger uses eg + Note the pager is expected to handle ANSI codes, which hledger uses eg for bold emphasis. For the common pager less (and its more compatibil- - ity mode), we add R to the LESS and MORE environment variables to make - this work. If you use a different pager, you might need to configure + ity mode), we add R to the LESS and MORE environment variables to make + this work. If you use a different pager, you might need to configure it similarly, to avoid seeing junk on screen (let us know). Otherwise, - you can set the NO_COLOR environment variable to 1 to disable all ANSI + you can set the NO_COLOR environment variable to 1 to disable all ANSI output (see Colour). Debug output We intend hledger to be relatively easy to troubleshoot, introspect and - develop. You can add --debug[=N] to any hledger command line to see - additional debug output. N ranges from 1 (least output, the default) - to 9 (maximum output). Typically you would start with 1 and increase - until you are seeing enough. Debug output goes to stderr, and is not + develop. You can add --debug[=N] to any hledger command line to see + additional debug output. N ranges from 1 (least output, the default) + to 9 (maximum output). Typically you would start with 1 and increase + until you are seeing enough. Debug output goes to stderr, and is not affected by -o/--output-file (unless you redirect stderr to stdout, eg: - 2>&1). It will be interleaved with normal output, which can help re- - veal when parts of the code are evaluated. To capture debug output in + 2>&1). It will be interleaved with normal output, which can help re- + veal when parts of the code are evaluated. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger bal --debug=3 2>hledger.log +Environment + These environment variables affect hledger: + + COLUMNS This is normally set by your terminal; some hledger commands + (register) will format their output to this width. If not set, they + will try to use the available terminal width. + + LEDGER_FILE The main journal file to use when not specified with + -f/--file. Default: $HOME/.hledger.journal. + + NO_COLOR If this environment variable is set (with any value), hledger + will not use ANSI color codes in terminal output, unless overridden by + an explicit --color/--colour option. + PART 2: DATA FORMATS Journal hledger's default file format, representing a General Journal. Here's @@ -1678,13 +1625,13 @@ Journal purpose directive -------------------------------------------------------------------------- READING DATA: - Rewrite account names alias Comment out sections of the file comment Declare file's decimal mark, to help decimal-mark parse amounts accurately Include other data files include GENERATING DATA: + Generate recurring transactions or bud- ~ get goals Generate extra postings on existing = @@ -1747,9 +1694,6 @@ Journal payee Declares a payee name, for checking all entries in all files. N P Declares the market price of a commodity on some date, for value N reports. - - - ~ Declares a periodic transaction rule that generates future N (tilde) transactions with --forecast and budget goals with balance --budget. @@ -1760,6 +1704,7 @@ Journal D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N there is no commodity directive for this commodity: its decimal mark, balancing precision, and display style, as above. + Y Sets a default year to use for any yearless dates, in following Y entries until end of current file. = Declares an auto posting rule that generates extra postings on partly @@ -2095,7 +2040,7 @@ Journal include a.aliases - 2020-01-01 ; not affected by a.aliases + 2023-01-01 ; not affected by a.aliases foo 1 bar @@ -2105,7 +2050,7 @@ Journal alias foo=Foo alias bar=Bar - 2020-01-01 ; affected by aliases above + 2023-01-01 ; affected by aliases above foo 1 bar @@ -2280,7 +2225,7 @@ Journal The path may also be prefixed to force a specific file format, overrid- ing the file extension (as described in hledger.1 -> Input files): in- - clude timedot:~/notes/2020*.md. + clude timedot:~/notes/2023*.md. P directive The P directive declares a market price, which is a conversion rate be- @@ -2367,8 +2312,8 @@ Journal to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit inconsistent with the above.) Eg: ~ every 10th day of month from - 2020/01, which is equivalent to ~ every 10th day of month from - 2020/01/01, will be adjusted to start on 2019/12/10. + 2023/01, which is equivalent to ~ every 10th day of month from + 2023/01/01, will be adjusted to start on 2019/12/10. Periodic rule syntax A periodic transaction rule looks like a normal journal entry, with the @@ -2410,10 +2355,10 @@ Journal where the period expression ends, so that descriptions can not acciden- tally alter their meaning, as in this example: - ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020" + ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" ; || ; vv - ~ every 2 months in 2020, we will review + ~ every 2 months in 2023, we will review assets:bank:checking $1500 income:acme inc @@ -2868,6 +2813,7 @@ CSV times newest-first improve txn order when: there are multiple records, newest first, all with the same date + intra-day-reversed improve txn order when: same-day txns are in opposite order to the overall file decimal-mark declare the decimal mark used in CSV amounts, @@ -3350,11 +3296,11 @@ CSV whitespace) are removed. So for example, when reading an SSV file, if the original record was: - 2020-01-01; "Acme, Inc."; 1,000 + 2023-01-01; "Acme, Inc."; 1,000 the regex would see, and try to match, this modified record text: - 2020-01-01,Acme, Inc., 1,000 + 2023-01-01,Acme, Inc., 1,000 When an if block has multiple matchers, they are combined as follows: @@ -3409,7 +3355,7 @@ CSV if,account2,comment atm transaction fee,expenses:business:banking,deductible? check it %description groceries,expenses:groceries, - 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out balance-type Balance assertions generated by assigning to balanceN are of the simple @@ -3656,20 +3602,20 @@ CSV If the currency/commodity symbol is included in the CSV's amount field(s): - 2020-01-01,foo,$123.00 + 2023-01-01,foo,$123.00 you don't have to do anything special for the commodity symbol, it will be assigned as part of the amount. Eg: fields date,description,amount - 2020-01-01 foo + 2023-01-01 foo expenses:unknown $123.00 income:unknown $-123.00 If the currency is provided as a separate CSV field: - 2020-01-01,foo,USD,123.00 + 2023-01-01,foo,USD,123.00 You can assign that to the currency pseudo-field, which has the special effect of prepending itself to every amount in the transaction (on the @@ -3677,7 +3623,7 @@ CSV fields date,description,currency,amount - 2020-01-01 foo + 2023-01-01 foo expenses:unknown USD123.00 income:unknown USD-123.00 @@ -3688,7 +3634,7 @@ CSV fields date,description,cur,amt amount %amt %cur - 2020-01-01 foo + 2023-01-01 foo expenses:unknown 123.00 USD income:unknown -123.00 USD @@ -4204,13 +4150,13 @@ Timedot biz:research 1 * Time log - ** 2020-01-01 + ** 2023-01-01 *** adm:time . *** adm:finance . - * 2020 Work Diary + * 2023 Work Diary ** Q1 - *** 2020-02-29 + *** 2023-02-29 **** DONE 0700 yoga **** UNPLANNED @@ -4322,7 +4268,6 @@ Time periods row - last/this/next -1, 0, 1 periods from the current period day/week/month/quar- ter/year @@ -4565,7 +4510,7 @@ Queries o Add a query type prefix to match other parts of the data: - date:202012- desc:amazon cur:USD amt:">100" status: + date:202312- desc:amazon cur:USD amt:">100" status: o Add a not: prefix to negate a term: @@ -4701,7 +4646,7 @@ Queries Queries and command options Some queries can also be expressed as command-line options: depth:2 is - equivalent to --depth 2, date:2020 is equivalent to -p 2020, etc. When + equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When you mix command options and query arguments, generally the resulting query is their intersection. @@ -5677,6 +5622,7 @@ Valuation (-H) with port or posting was made port or report journal journal interval start start + posting cost value at re- value at posting value at re- value at amounts port or date port or DATE/today journal end journal end @@ -5718,9 +5664,6 @@ Valuation fore report all postings respective post- all postings start before re- ing dates before re- port start port start - - - balance sums of same as sums of values of balance value at changes costs of --value=end postings in pe- change in DATE/today of (bal, is, postings in riod at respec- each period, sums of post- @@ -8503,20 +8446,20 @@ PART 5: COMMON TASKS Please create it first, eg with "hledger add" or a text editor. Or, specify an existing journal file with -f or LEDGER_FILE. - You can override this by setting the LEDGER_FILE environment variable. - It's a good practice to keep this important file under version control, - and to start a new file each year. So you could do something like - this: + You can override this by setting the LEDGER_FILE environment variable + (see below). It's a good practice to keep this important file under + version control, and to start a new file each year. So you could do + something like this: $ mkdir ~/finance $ cd ~/finance $ git init Initialized empty Git repository in /Users/simon/finance/.git/ - $ touch 2020.journal - $ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc - $ source ~/.bashrc + $ touch 2023.journal + $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile + $ source ~/.profile $ hledger stats - Main file : /Users/simon/finance/2020.journal + Main file : /Users/simon/finance/2023.journal Included files : Transactions span : to (0 days) Last transaction : none @@ -8528,47 +8471,78 @@ PART 5: COMMON TASKS Commodities : 0 () Market prices : 0 () + Setting LEDGER_FILE + How to set LEDGER_FILE permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for + many people; adapt as needed: + + $ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile + $ source ~/.profile + + When correctly configured, in a new terminal window env | grep + LEDGER_FILE will show your file, and so will hledger files. + + On mac, this additional step might be helpful for GUI applications + (like Emacs started from the dock): add an entry to ~/.MacOSX/environ- + ment.plist like + + { + "LEDGER_FILE" : "~/finance/2023.journal" + } + + and then run killall Dock in a terminal window (or restart the ma- + chine). + + On Windows, see https://www.java.com/en/download/help/path.html, or try + running these commands in a powershell window (let us know if it per- + sists across a reboot, and if you need to be an Administrator): + + > CD + > MKDIR finance + > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + Setting opening balances - Pick a starting date for which you can look up the balances of some - real-world assets (bank accounts, wallet..) and liabilities (credit + Pick a starting date for which you can look up the balances of some + real-world assets (bank accounts, wallet..) and liabilities (credit cards..). - To avoid a lot of data entry, you may want to start with just one or + To avoid a lot of data entry, you may want to start with just one or two accounts, like your checking account or cash wallet; and pick a re- - cent starting date, like today or the start of the week. You can al- - ways come back later and add more accounts and older transactions, eg + cent starting date, like today or the start of the week. You can al- + ways come back later and add more accounts and older transactions, eg going back to january 1st. - Add an opening balances transaction to the journal, declaring the bal- + Add an opening balances transaction to the journal, declaring the bal- ances on this date. Here are two ways to do it: - o The first way: open the journal in any text editor and save an entry + o The first way: open the journal in any text editor and save an entry like this: - 2020-01-01 * opening balances + 2023-01-01 * opening balances assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 liabilities:creditcard $-50 = $-50 equity:opening/closing balances - These are start-of-day balances, ie whatever was in the account at + These are start-of-day balances, ie whatever was in the account at the end of the previous day. - The * after the date is an optional status flag. Here it means + The * after the date is an optional status flag. Here it means "cleared & confirmed". - The currency symbols are optional, but usually a good idea as you'll + The currency symbols are optional, but usually a good idea as you'll be dealing with multiple currencies sooner or later. - The = amounts are optional balance assertions, providing extra error + The = amounts are optional balance assertions, providing extra error checking. - o The second way: run hledger add and follow the prompts to record a + o The second way: run hledger add and follow the prompts to record a similar transaction: $ hledger add - Adding transactions to journal file /Users/simon/finance/2020.journal + Adding transactions to journal file /Users/simon/finance/2023.journal Any command line arguments will be used as defaults. Use tab key to complete, readline keys to edit, enter to accept defaults. An optional (CODE) may follow transaction dates. @@ -8576,7 +8550,7 @@ PART 5: COMMON TASKS If you make a mistake, enter < at any prompt to go one step backward. To end a transaction, enter . when prompted. To quit, enter . at a date prompt or press control-d or control-c. - Date [2020-02-07]: 2020-01-01 + Date [2023-02-07]: 2023-01-01 Description: * opening balances Account 1: assets:bank:checking Amount 1: $1000 @@ -8589,7 +8563,7 @@ PART 5: COMMON TASKS Account 5: equity:opening/closing balances Amount 5 [$-3050]: Account 6 (or . or enter to finish this transaction): . - 2020-01-01 * opening balances + 2023-01-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 @@ -8599,83 +8573,83 @@ PART 5: COMMON TASKS Save this transaction to the journal ? [y]: Saved. Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2020-01-01]: . + Date [2023-01-01]: . - If you're using version control, this could be a good time to commit + If you're using version control, this could be a good time to commit the journal. Eg: - $ git commit -m 'initial balances' 2020.journal + $ git commit -m 'initial balances' 2023.journal Recording transactions - As you spend or receive money, you can record these transactions using - one of the methods above (text editor, hledger add) or by using the - hledger-iadd or hledger-web add-ons, or by using the import command to + As you spend or receive money, you can record these transactions using + one of the methods above (text editor, hledger add) or by using the + hledger-iadd or hledger-web add-ons, or by using the import command to convert CSV data downloaded from your bank. - Here are some simple transactions, see the hledger_journal(5) manual + Here are some simple transactions, see the hledger_journal(5) manual and hledger.org for more ideas: - 2020/1/10 * gift received + 2023/1/10 * gift received assets:cash $20 income:gifts - 2020.1.12 * farmers market + 2023.1.12 * farmers market expenses:food $13 assets:cash - 2020-01-15 paycheck + 2023-01-15 paycheck income:salary assets:bank:checking $1000 Reconciling - Periodically you should reconcile - compare your hledger-reported bal- - ances against external sources of truth, like bank statements or your - bank's website - to be sure that your ledger accurately represents the - real-world balances (and, that the real-world institutions have not - made a mistake!). This gets easy and fast with (1) practice and (2) - frequency. If you do it daily, it can take 2-10 minutes. If you let - it pile up, expect it to take longer as you hunt down errors and dis- + Periodically you should reconcile - compare your hledger-reported bal- + ances against external sources of truth, like bank statements or your + bank's website - to be sure that your ledger accurately represents the + real-world balances (and, that the real-world institutions have not + made a mistake!). This gets easy and fast with (1) practice and (2) + frequency. If you do it daily, it can take 2-10 minutes. If you let + it pile up, expect it to take longer as you hunt down errors and dis- crepancies. A typical workflow: - 1. Reconcile cash. Count what's in your wallet. Compare with what - hledger reports (hledger bal cash). If they are different, try to - remember the missing transaction, or look for the error in the al- - ready-recorded transactions. A register report can be helpful - (hledger reg cash). If you can't find the error, add an adjustment + 1. Reconcile cash. Count what's in your wallet. Compare with what + hledger reports (hledger bal cash). If they are different, try to + remember the missing transaction, or look for the error in the al- + ready-recorded transactions. A register report can be helpful + (hledger reg cash). If you can't find the error, add an adjustment transaction. Eg if you have $105 after the above, and can't explain the missing $2, it could be: - 2020-01-16 * adjust cash + 2023-01-16 * adjust cash assets:cash $-2 = $105 expenses:misc 2. Reconcile checking. Log in to your bank's website. Compare today's (cleared) balance with hledger's cleared balance (hledger bal check- - ing -C). If they are different, track down the error or record the - missing transaction(s) or add an adjustment transaction, similar to + ing -C). If they are different, track down the error or record the + missing transaction(s) or add an adjustment transaction, similar to the above. Unlike the cash case, you can usually compare the trans- - action history and running balance from your bank with the one re- - ported by hledger reg checking -C. This will be easier if you gen- - erally record transaction dates quite similar to your bank's clear- + action history and running balance from your bank with the one re- + ported by hledger reg checking -C. This will be easier if you gen- + erally record transaction dates quite similar to your bank's clear- ing dates. 3. Repeat for other asset/liability accounts. - Tip: instead of the register command, use hledger-ui to see a live-up- + Tip: instead of the register command, use hledger-ui to see a live-up- dating register while you edit the journal: hledger-ui --watch --regis- ter checking -C - After reconciling, it could be a good time to mark the reconciled - transactions' status as "cleared and confirmed", if you want to track - that, by adding the * marker. Eg in the paycheck transaction above, - insert * between 2020-01-15 and paycheck + After reconciling, it could be a good time to mark the reconciled + transactions' status as "cleared and confirmed", if you want to track + that, by adding the * marker. Eg in the paycheck transaction above, + insert * between 2023-01-15 and paycheck - If you're using version control, this can be another good time to com- + If you're using version control, this can be another good time to com- mit: - $ git commit -m 'txns' 2020.journal + $ git commit -m 'txns' 2023.journal Reporting Here are some basic reports. @@ -8683,26 +8657,26 @@ PART 5: COMMON TASKS Show all transactions: $ hledger print - 2020-01-01 * opening balances + 2023-01-01 * opening balances assets:bank:checking $1000 assets:bank:savings $2000 assets:cash $100 liabilities:creditcard $-50 equity:opening/closing balances $-3050 - 2020-01-10 * gift received + 2023-01-10 * gift received assets:cash $20 income:gifts - 2020-01-12 * farmers market + 2023-01-12 * farmers market expenses:food $13 assets:cash - 2020-01-15 * paycheck + 2023-01-15 * paycheck income:salary assets:bank:checking $1000 - 2020-01-16 * adjust cash + 2023-01-16 * adjust cash assets:cash $-2 = $105 expenses:misc @@ -8744,7 +8718,7 @@ PART 5: COMMON TASKS -------------------- 0 - Show only asset and liability balances, as a flat list, limited to + Show only asset and liability balances, as a flat list, limited to depth 2: $ hledger bal assets liabilities -2 @@ -8754,13 +8728,13 @@ PART 5: COMMON TASKS -------------------- $4055 - Show the same thing without negative numbers, formatted as a simple + Show the same thing without negative numbers, formatted as a simple balance sheet: $ hledger bs -2 - Balance Sheet 2020-01-16 + Balance Sheet 2023-01-16 - || 2020-01-16 + || 2023-01-16 ========================++============ Assets || ------------------------++------------ @@ -8783,9 +8757,9 @@ PART 5: COMMON TASKS Show income and expense totals, formatted as an income statement: hledger is - Income Statement 2020-01-01-2020-01-16 + Income Statement 2023-01-01-2023-01-16 - || 2020-01-01-2020-01-16 + || 2023-01-01-2023-01-16 ===============++======================= Revenues || ---------------++----------------------- @@ -8808,90 +8782,90 @@ PART 5: COMMON TASKS Show transactions affecting your wallet, with running total: $ hledger register cash - 2020-01-01 opening balances assets:cash $100 $100 - 2020-01-10 gift received assets:cash $20 $120 - 2020-01-12 farmers market assets:cash $-13 $107 - 2020-01-16 adjust cash assets:cash $-2 $105 + 2023-01-01 opening balances assets:cash $100 $100 + 2023-01-10 gift received assets:cash $20 $120 + 2023-01-12 farmers market assets:cash $-13 $107 + 2023-01-16 adjust cash assets:cash $-2 $105 Show weekly posting counts as a bar chart: $ hledger activity -W 2019-12-30 ***** - 2020-01-06 **** - 2020-01-13 **** + 2023-01-06 **** + 2023-01-13 **** Migrating to a new file - At the end of the year, you may want to continue your journal in a new + At the end of the year, you may want to continue your journal in a new file, so that old transactions don't slow down or clutter your reports, - and to help ensure the integrity of your accounting history. See the + and to help ensure the integrity of your accounting history. See the close command. If using version control, don't forget to git add the new file. 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 and limitations: - The need to precede add-on command options with -- when invoked from + The need to precede add-on command options with -- when invoked from hledger is awkward. (See Command options, Constructing command lines.) - A UTF-8-aware system locale must be configured to work with non-ascii + A UTF-8-aware system locale must be configured to work with non-ascii data. (See Unicode characters, Troubleshooting.) On Microsoft Windows, depending whether you are running in a CMD window or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii characters and colours may not be supported, and the tab key may not be - supported by hledger add. (Running in a WSL window should resolve + supported by hledger add. (Running in a WSL window should resolve these.) When processing large data files, hledger uses more memory than Ledger. Troubleshooting - Here are some common issues you might encounter when you run hledger, - and how to resolve them (and remember also you can usually get quick + Here are some common issues you might encounter when you run hledger, + and how to resolve them (and remember also you can usually get quick Support): PATH issues: I get an error like "No command 'hledger' found" Depending how you installed hledger, the executables may not be in your - shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- + shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one - of these directories to your shell's PATH, and/or open a new terminal + of these directories to your shell's PATH, and/or open a new terminal window. - LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using + LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using it - o LEDGER_FILE should be a real environment variable, not just a shell + o LEDGER_FILE should be a real environment variable, not just a shell variable. Eg on unix, the command env | grep LEDGER_FILE should show - it. You may need to use export (see https://stackover- + it. You may need to use export (see https://stackover- flow.com/a/7411509). - o You may need to force your shell to see the new configuration. A + o You may need to force your shell to see the new configuration. A simple way is to close your terminal window and open a new one. - LANG issues: I get errors like "Illegal byte sequence" or "Invalid or + LANG issues: I get errors like "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" or "commitAndReleaseBuffer: in- valid argument (invalid character)" - Programs compiled with GHC (hledger, haskell build tools, etc.) need - the system locale to be UTF-8-aware, or they will fail when they en- - counter non-ascii characters. To fix it, set the LANG environment - variable to a locale which supports UTF-8 and which is installed on + Programs compiled with GHC (hledger, haskell build tools, etc.) need + the system locale to be UTF-8-aware, or they will fail when they en- + counter non-ascii characters. To fix it, set the LANG environment + variable to a locale which supports UTF-8 and which is installed on your system. - On unix, locale -a lists the installed locales. Look for one which - mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8, - fr_FR.utf8. If necessary, use your system package manager to install - one. Then select it by setting the LANG environment variable. Note, - exact spelling and capitalisation of the locale name may be important: + On unix, locale -a lists the installed locales. Look for one which + mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8, + fr_FR.utf8. If necessary, use your system package manager to install + one. Then select it by setting the LANG environment variable. Note, + exact spelling and capitalisation of the locale name may be important: Here's one common way to configure this permanently for your shell: $ echo "export LANG=en_US.utf8" >>~/.profile # close and re-open terminal window COMPATIBILITY ISSUES: hledger gives an error with my Ledger file - Not all of Ledger's journal file syntax or feature set is supported. + Not all of Ledger's journal file syntax or feature set is supported. See hledger and Ledger for full details.