diff --git a/.otherdocs/hledger-api.1 b/.otherdocs/hledger-api.1 deleted file mode 100644 --- a/.otherdocs/hledger-api.1 +++ /dev/null @@ -1,122 +0,0 @@ - -.TH "hledger\-api" "1" "December 2017" "hledger\-api 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -hledger\-api \- web API server for the hledger accounting tool -.SH SYNOPSIS -.PP -\f[C]hledger\-api\ [OPTIONS]\f[] -.PD 0 -.P -.PD -\f[C]hledger\ api\ \-\-\ [OPTIONS]\f[] -.SH DESCRIPTION -.PP -hledger is a cross\-platform program for tracking money, time, or any -other commodity, using double\-entry accounting and a simple, editable -file format. -hledger is inspired by and largely compatible with ledger(1). -.PP -hledger\-api is a simple web API server, intended to support -client\-side web apps operating on hledger data. -It comes with a series of simple client\-side app examples, which drive -its evolution. -.PP -Like hledger, it reads data from one or more files in hledger journal, -timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -For more about this see hledger(1), hledger_journal(5) etc. -.PP -The server listens on IP address 127.0.0.1, accessible only to local -requests, by default. -You can change this with \f[C]\-\-host\f[], eg -\f[C]\-\-host\ 0.0.0.0\f[] to listen on all addresses. -Note there is no other access control, so you will need to hide -hledger\-api behind an authenticating proxy if you want to restrict -access. -You can change the TCP port (default: 8001) with \f[C]\-p\ PORT\f[]. -.PP -If invoked as \f[C]hledger\-api\ \-\-swagger\f[], instead of starting a -server the API docs will be printed in Swagger 2.0 format. -.SH OPTIONS -.PP -Note: if invoking hledger\-api as a hledger subcommand, write -\f[C]\-\-\f[] before options as shown above. -.TP -.B \f[C]\-f\ \-\-file=FILE\f[] -use a different input file. -For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or -\f[C]$HOME/.hledger.journal\f[]) -.RS -.RE -.TP -.B \f[C]\-d\ \-\-static\-dir=DIR\f[] -serve files from a different directory (default: \f[C]\&.\f[]) -.RS -.RE -.TP -.B \f[C]\-\-host=IPADDR\f[] -listen on this IP address (default: 127.0.0.1) -.RS -.RE -.TP -.B \f[C]\-p\ \-\-port=PORT\f[] -listen on this TCP port (default: 8001) -.RS -.RE -.TP -.B \f[C]\-\-swagger\f[] -print API docs in Swagger 2.0 format, and exit -.RS -.RE -.TP -.B \f[C]\-\-version\f[] -show version -.RS -.RE -.TP -.B \f[C]\-h\ \-\-help\f[] -show usage -.RS -.RE -.SH ENVIRONMENT -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede options with \f[C]\-\-\f[] when invoked from hledger -is awkward. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger-api.info b/.otherdocs/hledger-api.info deleted file mode 100644 --- a/.otherdocs/hledger-api.info +++ /dev/null @@ -1,70 +0,0 @@ -This is hledger-api.info, produced by makeinfo version 6.5 from stdin. - - -File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-api(1) hledger-api 1.5 -****************************** - -hledger-api is a simple web API server, intended to support client-side -web apps operating on hledger data. It comes with a series of simple -client-side app examples, which drive its evolution. - - Like hledger, it reads data from one or more files in hledger -journal, timeclock, timedot, or CSV format specified with '-f', or -'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), -hledger_journal(5) etc. - - The server listens on IP address 127.0.0.1, accessible only to local -requests, by default. You can change this with '--host', eg '--host -0.0.0.0' to listen on all addresses. Note there is no other access -control, so you will need to hide hledger-api behind an authenticating -proxy if you want to restrict access. You can change the TCP port -(default: 8001) with '-p PORT'. - - If invoked as 'hledger-api --swagger', instead of starting a server -the API docs will be printed in Swagger 2.0 format. -* Menu: - -* OPTIONS:: - - -File: hledger-api.info, Node: OPTIONS, Prev: Top, Up: Top - -1 OPTIONS -********* - -Note: if invoking hledger-api as a hledger subcommand, write '--' before -options as shown above. - -'-f --file=FILE' - - use a different input file. For stdin, use - (default: - '$LEDGER_FILE' or '$HOME/.hledger.journal') -'-d --static-dir=DIR' - - serve files from a different directory (default: '.') -'--host=IPADDR' - - listen on this IP address (default: 127.0.0.1) -'-p --port=PORT' - - listen on this TCP port (default: 8001) -'--swagger' - - print API docs in Swagger 2.0 format, and exit -'--version' - - show version -'-h --help' - - show usage - - -Tag Table: -Node: Top72 -Node: OPTIONS1216 -Ref: #options1301 - -End Tag Table diff --git a/.otherdocs/hledger-api.txt b/.otherdocs/hledger-api.txt deleted file mode 100644 --- a/.otherdocs/hledger-api.txt +++ /dev/null @@ -1,105 +0,0 @@ - -hledger-api(1) hledger User Manuals hledger-api(1) - - - -NAME - hledger-api - web API server for the hledger accounting tool - -SYNOPSIS - hledger-api [OPTIONS] - hledger api -- [OPTIONS] - -DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any - other commodity, using double-entry accounting and a simple, editable - file format. hledger is inspired by and largely compatible with - ledger(1). - - hledger-api is a simple web API server, intended to support client-side - web apps operating on hledger data. It comes with a series of simple - client-side app examples, which drive its evolution. - - Like hledger, it reads data from one or more files in hledger journal, - timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, - or $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). For more about this see hledger(1), - hledger_journal(5) etc. - - The server listens on IP address 127.0.0.1, accessible only to local - requests, by default. You can change this with --host, eg - --host 0.0.0.0 to listen on all addresses. Note there is no other - access control, so you will need to hide hledger-api behind an authen- - ticating proxy if you want to restrict access. You can change the TCP - port (default: 8001) with -p PORT. - - If invoked as hledger-api --swagger, instead of starting a server the - API docs will be printed in Swagger 2.0 format. - -OPTIONS - Note: if invoking hledger-api as a hledger subcommand, write -- before - options as shown above. - - -f --file=FILE - use a different input file. For stdin, use - (default: - $LEDGER_FILE or $HOME/.hledger.journal) - - -d --static-dir=DIR - serve files from a different directory (default: .) - - --host=IPADDR - listen on this IP address (default: 127.0.0.1) - - -p --port=PORT - listen on this TCP port (default: 8001) - - --swagger - print API docs in Swagger 2.0 format, and exit - - --version - show version - - -h --help - show usage - -ENVIRONMENT - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede options with -- when invoked from hledger is awk- - ward. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger-api 1.5 December 2017 hledger-api(1) diff --git a/.otherdocs/hledger-ui.1 b/.otherdocs/hledger-ui.1 deleted file mode 100644 --- a/.otherdocs/hledger-ui.1 +++ /dev/null @@ -1,485 +0,0 @@ - -.TH "hledger\-ui" "1" "December 2017" "hledger\-ui 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -hledger\-ui \- curses\-style interface for the hledger accounting tool -.SH SYNOPSIS -.PP -\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[] -.PD 0 -.P -.PD -\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[] -.SH DESCRIPTION -.PP -hledger is a cross\-platform program for tracking money, time, or any -other commodity, using double\-entry accounting and a simple, editable -file format. -hledger is inspired by and largely compatible with ledger(1). -.PP -hledger\-ui is hledger's curses\-style interface, providing an efficient -full\-window text UI for viewing accounts and transactions, and some -limited data entry capability. -It is easier than hledger's command\-line interface, and sometimes -quicker and more convenient than the web interface. -.PP -Like hledger, it reads data from one or more files in hledger journal, -timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -For more about this see hledger(1), hledger_journal(5) etc. -.SH OPTIONS -.PP -Note: if invoking hledger\-ui as a hledger subcommand, write -\f[C]\-\-\f[] before options as shown above. -.PP -Any QUERYARGS are interpreted as a hledger search query which filters -the data. -.TP -.B \f[C]\-\-watch\f[] -watch for data and date changes and reload automatically -.RS -.RE -.TP -.B \f[C]\-\-theme=default|terminal|greenterm\f[] -use this custom display theme -.RS -.RE -.TP -.B \f[C]\-\-register=ACCTREGEX\f[] -start in the (first) matched account's register screen -.RS -.RE -.TP -.B \f[C]\-\-change\f[] -show period balances (changes) at startup instead of historical balances -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show full account names, unindented -.RS -.RE -.PP -hledger input options: -.TP -.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] -use a different input file. -For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or -\f[C]$HOME/.hledger.journal\f[]) -.RS -.RE -.TP -.B \f[C]\-\-rules\-file=RULESFILE\f[] -Conversion rules file to use when reading CSV (default: FILE.rules) -.RS -.RE -.TP -.B \f[C]\-\-alias=OLD=NEW\f[] -rename accounts named OLD to NEW -.RS -.RE -.TP -.B \f[C]\-\-anon\f[] -anonymize accounts and payees -.RS -.RE -.TP -.B \f[C]\-\-pivot\ FIELDNAME\f[] -use some other field or tag for the account name -.RS -.RE -.TP -.B \f[C]\-I\ \-\-ignore\-assertions\f[] -ignore any failing balance assertions -.RS -.RE -.PP -hledger reporting options: -.TP -.B \f[C]\-b\ \-\-begin=DATE\f[] -include postings/txns on or after this date -.RS -.RE -.TP -.B \f[C]\-e\ \-\-end=DATE\f[] -include postings/txns before this date -.RS -.RE -.TP -.B \f[C]\-D\ \-\-daily\f[] -multiperiod/multicolumn report by day -.RS -.RE -.TP -.B \f[C]\-W\ \-\-weekly\f[] -multiperiod/multicolumn report by week -.RS -.RE -.TP -.B \f[C]\-M\ \-\-monthly\f[] -multiperiod/multicolumn report by month -.RS -.RE -.TP -.B \f[C]\-Q\ \-\-quarterly\f[] -multiperiod/multicolumn report by quarter -.RS -.RE -.TP -.B \f[C]\-Y\ \-\-yearly\f[] -multiperiod/multicolumn report by year -.RS -.RE -.TP -.B \f[C]\-p\ \-\-period=PERIODEXP\f[] -set start date, end date, and/or reporting interval all at once using -period expressions syntax (overrides the flags above) -.RS -.RE -.TP -.B \f[C]\-\-date2\f[] -match the secondary date instead (see command help for other effects) -.RS -.RE -.TP -.B \f[C]\-U\ \-\-unmarked\f[] -include only unmarked postings/txns (can combine with \-P or \-C) -.RS -.RE -.TP -.B \f[C]\-P\ \-\-pending\f[] -include only pending postings/txns -.RS -.RE -.TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns -.RS -.RE -.TP -.B \f[C]\-R\ \-\-real\f[] -include only non\-virtual postings -.RS -.RE -.TP -.B \f[C]\-NUM\ \-\-depth=NUM\f[] -hide/aggregate accounts or postings more than NUM levels deep -.RS -.RE -.TP -.B \f[C]\-E\ \-\-empty\f[] -show items with zero amount, normally hidden -.RS -.RE -.TP -.B \f[C]\-B\ \-\-cost\f[] -convert amounts to their cost at transaction time (using the transaction -price, if any) -.RS -.RE -.TP -.B \f[C]\-V\ \-\-value\f[] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) -.RS -.RE -.TP -.B \f[C]\-\-auto\f[] -apply automated posting rules to modify transactions. -.RS -.RE -.TP -.B \f[C]\-\-forecast\f[] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. -.RS -.RE -.PP -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 -.B \f[C]\-h\ \-\-help\f[] -show general usage (or after COMMAND, command usage) -.RS -.RE -.TP -.B \f[C]\-\-version\f[] -show version -.RS -.RE -.TP -.B \f[C]\-\-debug[=N]\f[] -show debug output (levels 1\-9, default: 1) -.RS -.RE -.PP -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 \f[C]\-\-\f[] argument before.) -.SH KEYS -.PP -\f[C]?\f[] shows a help dialog listing all keys. -(Some of these also appear in the quick help at the bottom of each -screen.) Press \f[C]?\f[] again (or \f[C]ESCAPE\f[], or \f[C]LEFT\f[]) -to close it. -The following keys work on most screens: -.PP -The cursor keys navigate: \f[C]right\f[] (or \f[C]enter\f[]) goes -deeper, \f[C]left\f[] returns to the previous screen, -\f[C]up\f[]/\f[C]down\f[]/\f[C]page\ up\f[]/\f[C]page\ down\f[]/\f[C]home\f[]/\f[C]end\f[] -move up and down through lists. -Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style -(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[]) -movement keys are also supported. -A tip: movement speed is limited by your keyboard repeat rate, to move -faster you may want to adjust it. -(If you're on a mac, the Karabiner app is one way to do that.) -.PP -With shift pressed, the cursor keys adjust the report period, limiting -the transactions to be shown (by default, all are shown). -\f[C]shift\-down/up\f[] steps downward and upward through these standard -report period durations: year, quarter, month, week, day. -Then, \f[C]shift\-left/right\f[] moves to the previous/next period. -\f[C]t\f[] sets the report period to today. -With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq] -period (the current day, week, month, quarter, or year), the period will -move automatically to track the current date. -To set a non\-standard period, you can use \f[C]/\f[] and a -\f[C]date:\f[] query. -.PP -\f[C]/\f[] lets you set a general filter query limiting the data shown, -using the same query terms as in hledger and hledger\-web. -While editing the query, you can use CTRL\-a/e/d/k, BS, cursor keys; -press \f[C]ENTER\f[] to set it, or \f[C]ESCAPE\f[]to cancel. -There are also keys for quickly adjusting some common filters like -account depth and transaction status (see below). -\f[C]BACKSPACE\f[] or \f[C]DELETE\f[] removes all filters, showing all -transactions. -.PP -\f[C]ESCAPE\f[] removes all filters and jumps back to the top screen. -Or, it cancels a minibuffer edit or help dialog in progress. -.PP -\f[C]CTRL\-l\f[] redraws the screen and centers the selection if -possible (selections near the top won't be centered, since we don't -scroll above the top). -.PP -\f[C]g\f[] reloads from the data file(s) and updates the current screen -and any previous screens. -(With large files, this could cause a noticeable pause.) -.PP -\f[C]I\f[] toggles balance assertion checking. -Disabling balance assertions temporarily can be useful for -troubleshooting. -.PP -\f[C]a\f[] runs command\-line hledger's add command, and reloads the -updated file. -This allows some basic data entry. -.PP -\f[C]A\f[] is like \f[C]a\f[], but runs the hledger\-iadd tool, which -provides a curses\-style interface. -This key will be available if \f[C]hledger\-iadd\f[] is installed in -$PATH. -.PP -\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default -(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file. -With some editors (emacs, vi), the cursor will be positioned at the -current transaction when invoked from the register and transaction -screens, and at the error location (if possible) when invoked from the -error screen. -.PP -\f[C]q\f[] quits the application. -.PP -Additional screen\-specific keys are described below. -.SH SCREENS -.SS Accounts screen -.PP -This is normally the first screen displayed. -It lists accounts and their balances, like hledger's balance command. -By default, it shows all accounts and their latest ending balances -(including the balances of subaccounts). -if you specify a query on the command line, it shows just the matched -accounts and the balances from matched transactions. -.PP -Account names are normally indented to show the hierarchy (tree mode). -To see less detail, set a depth limit by pressing a number key, -\f[C]1\f[] to \f[C]9\f[]. -\f[C]0\f[] shows even less detail, collapsing all accounts to a single -total. -\f[C]\-\f[] and \f[C]+\f[] (or \f[C]=\f[]) decrease and increase the -depth limit. -To remove the depth limit, set it higher than the maximum account depth, -or press \f[C]ESCAPE\f[]. -.PP -\f[C]F\f[] toggles flat mode, in which accounts are shown as a flat -list, with their full names. -In this mode, account balances exclude subaccounts, except for accounts -at the depth limit (as with hledger's balance command). -.PP -\f[C]H\f[] toggles between showing historical balances or period -balances. -Historical balances (the default) are ending balances at the end of the -report period, taking into account all transactions before that date -(filtered by the filter query if any), including transactions before the -start of the report period. -In other words, historical balances are what you would see on a bank -statement for that account (unless disturbed by a filter query). -Period balances ignore transactions before the report start date, so -they show the change in balance during the report period. -They are more useful eg when viewing a time log. -.PP -\f[C]U\f[] toggles filtering by unmarked status, including or excluding -unmarked postings in the balances. -Similarly, \f[C]P\f[] toggles pending postings, and \f[C]C\f[] toggles -cleared postings. -(By default, balances include all postings; if you activate one or two -status filters, only those postings are included; and if you activate -all three, the filter is removed.) -.PP -\f[C]R\f[] toggles real mode, in which virtual postings are ignored. -.PP -\f[C]Z\f[] toggles nonzero mode, in which only accounts with nonzero -balances are shown (hledger\-ui shows zero items by default, unlike -command\-line hledger). -.PP -Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions -register. -.SS Register screen -.PP -This screen shows the transactions affecting a particular account, like -a check register. -Each line represents one transaction and shows: -.IP \[bu] 2 -the other account(s) involved, in abbreviated form. -(If there are both real and virtual postings, it shows only the accounts -affected by real postings.) -.IP \[bu] 2 -the overall change to the current account's balance; positive for an -inflow to this account, negative for an outflow. -.IP \[bu] 2 -the running historical total or period total for the current account, -after the transaction. -This can be toggled with \f[C]H\f[]. -Similar to the accounts screen, the historical total is affected by -transactions (filtered by the filter query) before the report start -date, while the period total is not. -If the historical total is not disturbed by a filter query, it will be -the running historical balance you would see on a bank register for the -current account. -.PP -If the accounts screen was in tree mode, the register screen will -include transactions from both the current account and its subaccounts. -If the accounts screen was in flat mode, and a non\-depth\-clipped -account was selected, the register screen will exclude transactions from -subaccounts. -In other words, the register always shows the transactions responsible -for the period balance shown on the accounts screen. -As on the accounts screen, this can be toggled with \f[C]F\f[]. -.PP -\f[C]U\f[] toggles filtering by unmarked status, showing or hiding -unmarked transactions. -Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[] -toggles cleared transactions. -(By default, transactions with all statuses are shown; if you activate -one or two status filters, only those transactions are shown; and if you -activate all three, the filter is removed.)q -.PP -\f[C]R\f[] toggles real mode, in which virtual postings are ignored. -.PP -\f[C]Z\f[] toggles nonzero mode, in which only transactions posting a -nonzero change are shown (hledger\-ui shows zero items by default, -unlike command\-line hledger). -.PP -Press \f[C]right\f[] (or \f[C]enter\f[]) to view the selected -transaction in detail. -.SS Transaction screen -.PP -This screen shows a single transaction, as a general journal entry, -similar to hledger's print command and journal format -(hledger_journal(5)). -.PP -The transaction's date(s) and any cleared flag, transaction code, -description, comments, along with all of its account postings are shown. -Simple transactions have two postings, but there can be more (or in -certain cases, fewer). -.PP -\f[C]up\f[] and \f[C]down\f[] will step through all transactions listed -in the previous account register screen. -In the title bar, the numbers in parentheses show your position within -that account register. -They will vary depending on which account register you came from -(remember most transactions appear in multiple account registers). -The #N number preceding them is the transaction's position within the -complete unfiltered journal, which is a more stable id (at least until -the next reload). -.SS Error screen -.PP -This screen will appear if there is a problem, such as a parse error, -when you press g to reload. -Once you have fixed the problem, press g again to reload and resume -normal operation. -(Or, you can press escape to cancel the reload attempt.) -.SH ENVIRONMENT -.PP -\f[B]COLUMNS\f[] The screen width to use. -Default: the full terminal width. -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede options with \f[C]\-\-\f[] when invoked from hledger -is awkward. -.PP -\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin). -.PP -\f[C]\-V\f[] affects only the accounts screen. -.PP -When you press \f[C]g\f[], the current and all previous screens are -regenerated, which may cause a noticeable pause with large files. -Also there is no visual indication that this is in progress. -.PP -\f[C]\-\-watch\f[] is not yet fully robust. -It works well for normal usage, but many file changes in a short time -(eg saving the file thousands of times with an editor macro) can cause -problems at least on OSX. -Symptoms include: unresponsive UI, periodic resetting of the cursor -position, momentary display of parse errors, high CPU usage eventually -subsiding, and possibly a small but persistent build\-up of CPU usage -until the program is restarted. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger-ui.info b/.otherdocs/hledger-ui.info deleted file mode 100644 --- a/.otherdocs/hledger-ui.info +++ /dev/null @@ -1,394 +0,0 @@ -This is hledger-ui.info, produced by makeinfo version 6.5 from stdin. - - -File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-ui(1) hledger-ui 1.5 -**************************** - -hledger-ui is hledger's curses-style interface, providing an efficient -full-window text UI for viewing accounts and transactions, and some -limited data entry capability. It is easier than hledger's command-line -interface, and sometimes quicker and more convenient than the web -interface. - - Like hledger, it reads data from one or more files in hledger -journal, timeclock, timedot, or CSV format specified with '-f', or -'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), -hledger_journal(5) etc. -* Menu: - -* OPTIONS:: -* KEYS:: -* SCREENS:: - - -File: hledger-ui.info, Node: OPTIONS, Next: KEYS, 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 -the data. - -'--watch' - - watch for data and date changes and reload automatically -'--theme=default|terminal|greenterm' - - use this custom display theme -'--register=ACCTREGEX' - - start in the (first) matched account's register screen -'--change' - - show period balances (changes) at startup instead of historical - balances -'--flat' - - show full account names, unindented - - hledger 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: FILE.rules) -'--alias=OLD=NEW' - - rename accounts named OLD to NEW -'--anon' - - anonymize accounts and payees -'--pivot FIELDNAME' - - use some other field or tag for the account name -'-I --ignore-assertions' - - ignore any failing balance assertions - - hledger reporting options: - -'-b --begin=DATE' - - include postings/txns on or after this date -'-e --end=DATE' - - include postings/txns before this date -'-D --daily' - - multiperiod/multicolumn report by day -'-W --weekly' - - multiperiod/multicolumn report by week -'-M --monthly' - - multiperiod/multicolumn report by month -'-Q --quarterly' - - multiperiod/multicolumn report by quarter -'-Y --yearly' - - multiperiod/multicolumn report by year -'-p --period=PERIODEXP' - - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) -'--date2' - - match the secondary date instead (see command help for other - effects) -'-U --unmarked' - - include only unmarked postings/txns (can combine with -P or -C) -'-P --pending' - - include only pending postings/txns -'-C --cleared' - - include only cleared postings/txns -'-R --real' - - include only non-virtual postings -'-NUM --depth=NUM' - - hide/aggregate accounts or postings more than NUM levels deep -'-E --empty' - - show items with zero amount, normally hidden -'-B --cost' - - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' - - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) -'--auto' - - apply automated posting rules to modify transactions. -'--forecast' - - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, -the last one takes precedence. - - Some reporting options can also be written as query arguments. - - hledger help options: - -'-h --help' - - show general usage (or after COMMAND, command usage) -'--version' - - show 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: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top - -2 KEYS -****** - -'?' shows a help dialog listing all keys. (Some of these also appear in -the quick help at the bottom of each screen.) Press '?' again (or -'ESCAPE', or 'LEFT') to close it. The following keys work on most -screens: - - The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' -returns to the previous screen, 'up'/'down'/'page up'/'page -down'/'home'/'end' move up and down through lists. Vi-style -('h'/'j'/'k'/'l') and Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') -movement keys are also supported. A tip: movement speed is limited by -your keyboard repeat rate, to move faster you may want to adjust it. -(If you're on a mac, the Karabiner app is one way to do that.) - - With shift pressed, the cursor keys adjust the report period, -limiting the transactions to be shown (by default, all are shown). -'shift-down/up' steps downward and upward through these standard report -period durations: year, quarter, month, week, day. Then, -'shift-left/right' moves to the previous/next period. 't' sets the -report period to today. With the '--watch' option, when viewing a -"current" period (the current day, week, month, quarter, or year), the -period will move automatically to track the current date. To set a -non-standard period, you can use '/' and a 'date:' query. - - '/' lets you set a general filter query limiting the data shown, -using the same query terms as in hledger and hledger-web. While editing -the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to -set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting -some common filters like account depth and transaction status (see -below). 'BACKSPACE' or 'DELETE' removes all filters, showing all -transactions. - - 'ESCAPE' removes all filters and jumps back to the top screen. Or, -it cancels a minibuffer edit or help dialog in progress. - - 'CTRL-l' redraws the screen and centers the selection if possible -(selections near the top won't be centered, since we don't scroll above -the top). - - 'g' reloads from the data file(s) and updates the current screen and -any previous screens. (With large files, this could cause a noticeable -pause.) - - 'I' toggles balance assertion checking. Disabling balance assertions -temporarily can be useful for troubleshooting. - - 'a' runs command-line hledger's add command, and reloads the updated -file. This allows some basic data entry. - - 'A' is like 'a', but runs the hledger-iadd tool, which provides a -curses-style interface. This key will be available if 'hledger-iadd' is -installed in $PATH. - - 'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient --a "" -nw') on the journal file. With some editors (emacs, vi), the -cursor will be positioned at the current transaction when invoked from -the register and transaction screens, and at the error location (if -possible) when invoked from the error screen. - - 'q' quits the application. - - Additional screen-specific keys are described below. - - -File: hledger-ui.info, Node: SCREENS, Prev: KEYS, Up: Top - -3 SCREENS -********* - -* Menu: - -* Accounts screen:: -* Register screen:: -* Transaction screen:: -* Error screen:: - - -File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCREENS - -3.1 Accounts screen -=================== - -This is normally the first screen displayed. It lists accounts and -their balances, like hledger's balance command. By default, it shows -all accounts and their latest ending balances (including the balances of -subaccounts). if you specify a query on the command line, it shows just -the matched accounts and the balances from matched transactions. - - Account names are normally indented to show the hierarchy (tree -mode). To see less detail, set a depth limit by pressing a number key, -'1' to '9'. '0' shows even less detail, collapsing all accounts to a -single total. '-' and '+' (or '=') decrease and increase the depth -limit. To remove the depth limit, set it higher than the maximum -account depth, or press 'ESCAPE'. - - 'F' toggles flat mode, in which accounts are shown as a flat list, -with their full names. In this mode, account balances exclude -subaccounts, except for accounts at the depth limit (as with hledger's -balance command). - - 'H' toggles between showing historical balances or period balances. -Historical balances (the default) are ending balances at the end of the -report period, taking into account all transactions before that date -(filtered by the filter query if any), including transactions before the -start of the report period. In other words, historical balances are -what you would see on a bank statement for that account (unless -disturbed by a filter query). Period balances ignore transactions -before the report start date, so they show the change in balance during -the report period. They are more useful eg when viewing a time log. - - 'U' toggles filtering by unmarked status, including or excluding -unmarked postings in the balances. Similarly, 'P' toggles pending -postings, and 'C' toggles cleared postings. (By default, balances -include all postings; if you activate one or two status filters, only -those postings are included; and if you activate all three, the filter -is removed.) - - 'R' toggles real mode, in which virtual postings are ignored. - - 'Z' toggles nonzero mode, in which only accounts with nonzero -balances are shown (hledger-ui shows zero items by default, unlike -command-line hledger). - - Press 'right' or 'enter' to view an account's transactions register. - - -File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS - -3.2 Register screen -=================== - -This screen shows the transactions affecting a particular account, like -a check register. Each line represents one transaction and shows: - - * the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected - by real postings.) - - * the overall change to the current account's balance; positive for - an inflow to this account, negative for an outflow. - - * the running historical total or period total for the current - account, after the transaction. This can be toggled with 'H'. - Similar to the accounts screen, the historical total is affected by - transactions (filtered by the filter query) before the report start - date, while the period total is not. If the historical total is - not disturbed by a filter query, it will be the running historical - balance you would see on a bank register for the current account. - - If the accounts screen was in tree mode, the register screen will -include transactions from both the current account and its subaccounts. -If the accounts screen was in flat mode, and a non-depth-clipped account -was selected, the register screen will exclude transactions from -subaccounts. In other words, the register always shows the transactions -responsible for the period balance shown on the accounts screen. As on -the accounts screen, this can be toggled with 'F'. - - 'U' toggles filtering by unmarked status, showing or hiding unmarked -transactions. Similarly, 'P' toggles pending transactions, and 'C' -toggles cleared transactions. (By default, transactions with all -statuses are shown; if you activate one or two status filters, only -those transactions are shown; and if you activate all three, the filter -is removed.)q - - 'R' toggles real mode, in which virtual postings are ignored. - - 'Z' toggles nonzero mode, in which only transactions posting a -nonzero change are shown (hledger-ui shows zero items by default, unlike -command-line hledger). - - Press 'right' (or 'enter') to view the selected transaction in -detail. - - -File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS - -3.3 Transaction screen -====================== - -This screen shows a single transaction, as a general journal entry, -similar to hledger's print command and journal format -(hledger_journal(5)). - - The transaction's date(s) and any cleared flag, transaction code, -description, comments, along with all of its account postings are shown. -Simple transactions have two postings, but there can be more (or in -certain cases, fewer). - - 'up' and 'down' will step through all transactions listed in the -previous account register screen. In the title bar, the numbers in -parentheses show your position within that account register. They will -vary depending on which account register you came from (remember most -transactions appear in multiple account registers). The #N number -preceding them is the transaction's position within the complete -unfiltered journal, which is a more stable id (at least until the next -reload). - - -File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS - -3.4 Error screen -================ - -This screen will appear if there is a problem, such as a parse error, -when you press g to reload. Once you have fixed the problem, press g -again to reload and resume normal operation. (Or, you can press escape -to cancel the reload attempt.) - - -Tag Table: -Node: Top71 -Node: OPTIONS821 -Ref: #options918 -Node: KEYS4087 -Ref: #keys4182 -Node: SCREENS7141 -Ref: #screens7226 -Node: Accounts screen7316 -Ref: #accounts-screen7444 -Node: Register screen9674 -Ref: #register-screen9829 -Node: Transaction screen11903 -Ref: #transaction-screen12061 -Node: Error screen12931 -Ref: #error-screen13053 - -End Tag Table diff --git a/.otherdocs/hledger-ui.txt b/.otherdocs/hledger-ui.txt deleted file mode 100644 --- a/.otherdocs/hledger-ui.txt +++ /dev/null @@ -1,386 +0,0 @@ - -hledger-ui(1) hledger User Manuals hledger-ui(1) - - - -NAME - hledger-ui - curses-style interface for the hledger accounting tool - -SYNOPSIS - hledger-ui [OPTIONS] [QUERYARGS] - hledger ui -- [OPTIONS] [QUERYARGS] - -DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any - other commodity, using double-entry accounting and a simple, editable - file format. hledger is inspired by and largely compatible with - ledger(1). - - hledger-ui is hledger's curses-style interface, providing an efficient - full-window text UI for viewing accounts and transactions, and some - limited data entry capability. It is easier than hledger's com- - mand-line interface, and sometimes quicker and more convenient than the - web interface. - - Like hledger, it reads data from one or more files in hledger journal, - timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, - or $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). For more about this see hledger(1), - hledger_journal(5) etc. - -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 - the data. - - --watch - watch for data and date changes and reload automatically - - --theme=default|terminal|greenterm - use this custom display theme - - --register=ACCTREGEX - start in the (first) matched account's register screen - - --change - show period balances (changes) at startup instead of historical - balances - - --flat show full account names, unindented - - hledger 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: - FILE.rules) - - --alias=OLD=NEW - rename accounts named OLD to NEW - - --anon anonymize accounts and payees - - --pivot FIELDNAME - use some other field or tag for the account name - - -I --ignore-assertions - ignore any failing balance assertions - - hledger reporting options: - - -b --begin=DATE - include postings/txns on or after this date - - -e --end=DATE - include postings/txns before this date - - -D --daily - multiperiod/multicolumn report by day - - -W --weekly - multiperiod/multicolumn report by week - - -M --monthly - multiperiod/multicolumn report by month - - -Q --quarterly - multiperiod/multicolumn report by quarter - - -Y --yearly - multiperiod/multicolumn report by year - - -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) - - --date2 - match the secondary date instead (see command help for other - effects) - - -U --unmarked - include only unmarked postings/txns (can combine with -P or -C) - - -P --pending - include only pending postings/txns - - -C --cleared - include only cleared postings/txns - - -R --real - include only non-virtual postings - - -NUM --depth=NUM - hide/aggregate accounts or postings more than NUM levels deep - - -E --empty - show items with zero amount, normally hidden - - -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) - - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) - - --auto apply automated posting rules to modify transactions. - - --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, the - last one takes precedence. - - Some reporting options can also be written as query arguments. - - hledger help options: - - -h --help - show general usage (or after COMMAND, command usage) - - --version - show 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.) - -KEYS - ? shows a help dialog listing all keys. (Some of these also appear in - the quick help at the bottom of each screen.) Press ? again (or ESCAPE, - or LEFT) to close it. The following keys work on most screens: - - The cursor keys navigate: right (or enter) goes deeper, left returns to - the previous screen, up/down/page up/page down/home/end move up and - down through lists. Vi-style (h/j/k/l) and Emacs-style - (CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: - movement speed is limited by your keyboard repeat rate, to move faster - you may want to adjust it. (If you're on a mac, the Karabiner app is - one way to do that.) - - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). - shift-down/up steps downward and upward through these standard report - period durations: year, quarter, month, week, day. Then, - shift-left/right moves to the previous/next period. t sets the report - period to today. With the --watch option, when viewing a "current" - period (the current day, week, month, quarter, or year), the period - will move automatically to track the current date. To set a non-stan- - dard period, you can use / and a date: query. - - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set - it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and transaction status (see below). - BACKSPACE or DELETE removes all filters, showing all transactions. - - ESCAPE removes all filters and jumps back to the top screen. Or, it - cancels a minibuffer edit or help dialog in progress. - - CTRL-l redraws the screen and centers the selection if possible (selec- - tions near the top won't be centered, since we don't scroll above the - top). - - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable - pause.) - - I toggles balance assertion checking. Disabling balance assertions - temporarily can be useful for troubleshooting. - - a runs command-line hledger's add command, and reloads the updated - file. This allows some basic data entry. - - A is like a, but runs the hledger-iadd tool, which provides a - curses-style interface. This key will be available if hledger-iadd is - installed in $PATH. - - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- - sclient -a "" -nw) on the journal file. With some editors (emacs, vi), - the cursor will be positioned at the current transaction when invoked - from the register and transaction screens, and at the error location - (if possible) when invoked from the error screen. - - q quits the application. - - Additional screen-specific keys are described below. - -SCREENS - Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows - just the matched accounts and the balances from matched transactions. - - Account names are normally indented to show the hierarchy (tree mode). - To see less detail, set a depth limit by pressing a number key, 1 to 9. - 0 shows even less detail, collapsing all accounts to a single total. - - and + (or =) decrease and increase the depth limit. To remove the - depth limit, set it higher than the maximum account depth, or press - ESCAPE. - - F toggles flat mode, in which accounts are shown as a flat list, with - their full names. In this mode, account balances exclude subaccounts, - except for accounts at the depth limit (as with hledger's balance com- - mand). - - H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions - before the report start date, so they show the change in balance during - the report period. They are more useful eg when viewing a time log. - - U toggles filtering by unmarked status, including or excluding unmarked - postings in the balances. Similarly, P toggles pending postings, and C - toggles cleared postings. (By default, balances include all postings; - if you activate one or two status filters, only those postings are - included; and if you activate all three, the filter is removed.) - - R toggles real mode, in which virtual postings are ignored. - - Z toggles nonzero mode, in which only accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line - hledger). - - Press right or enter to view an account's transactions register. - - Register screen - This screen shows the transactions affecting a particular account, like - a check register. Each line represents one transaction and shows: - - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected - by real postings.) - - o the overall change to the current account's balance; positive for an - inflow to this account, negative for an outflow. - - o the running historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while - the period total is not. If the historical total is not disturbed by - a filter query, it will be the running historical balance you would - see on a bank register for the current account. - - If the accounts screen was in tree mode, the register screen will - include transactions from both the current account and its subaccounts. - If the accounts screen was in flat mode, and a non-depth-clipped - account was selected, the register screen will exclude transactions - from subaccounts. In other words, the register always shows the trans- - actions responsible for the period balance shown on the accounts - screen. As on the accounts screen, this can be toggled with F. - - U toggles filtering by unmarked status, showing or hiding unmarked - transactions. Similarly, P toggles pending transactions, and C toggles - cleared transactions. (By default, transactions with all statuses are - shown; if you activate one or two status filters, only those transac- - tions are shown; and if you activate all three, the filter is - removed.)q - - R toggles real mode, in which virtual postings are ignored. - - Z toggles nonzero mode, in which only transactions posting a nonzero - change are shown (hledger-ui shows zero items by default, unlike com- - mand-line hledger). - - Press right (or enter) to view the selected transaction in detail. - - Transaction screen - This screen shows a single transaction, as a general journal entry, - similar to hledger's print command and journal format (hledger_jour- - nal(5)). - - The transaction's date(s) and any cleared flag, transaction code, - description, comments, along with all of its account postings are - shown. Simple transactions have two postings, but there can be more - (or in certain cases, fewer). - - up and down will step through all transactions listed in the previous - account register screen. In the title bar, the numbers in parentheses - show your position within that account register. They will vary - depending on which account register you came from (remember most trans- - actions appear in multiple account registers). The #N number preceding - them is the transaction's position within the complete unfiltered jour- - nal, which is a more stable id (at least until the next reload). - - Error screen - This screen will appear if there is a problem, such as a parse error, - when you press g to reload. Once you have fixed the problem, press g - again to reload and resume normal operation. (Or, you can press escape - to cancel the reload attempt.) - -ENVIRONMENT - COLUMNS The screen width to use. Default: the full terminal width. - - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede options with -- when invoked from hledger is awk- - ward. - - -f- doesn't work (hledger-ui can't read from stdin). - - -V affects only the accounts screen. - - When you press g, the current and all previous screens are regenerated, - which may cause a noticeable pause with large files. Also there is no - visual indication that this is in progress. - - --watch is not yet fully robust. It works well for normal usage, but - many file changes in a short time (eg saving the file thousands of - times with an editor macro) can cause problems at least on OSX. Symp- - toms include: unresponsive UI, periodic resetting of the cursor posi- - tion, momentary display of parse errors, high CPU usage eventually sub- - siding, and possibly a small but persistent build-up of CPU usage until - the program is restarted. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger-ui 1.5 December 2017 hledger-ui(1) diff --git a/.otherdocs/hledger-web.1 b/.otherdocs/hledger-web.1 deleted file mode 100644 --- a/.otherdocs/hledger-web.1 +++ /dev/null @@ -1,326 +0,0 @@ - -.TH "hledger\-web" "1" "December 2017" "hledger\-web 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -hledger\-web \- web interface for the hledger accounting tool -.SH SYNOPSIS -.PP -\f[C]hledger\-web\ [OPTIONS]\f[] -.PD 0 -.P -.PD -\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[] -.SH DESCRIPTION -.PP -hledger is a cross\-platform program for tracking money, time, or any -other commodity, using double\-entry accounting and a simple, editable -file format. -hledger is inspired by and largely compatible with ledger(1). -.PP -hledger\-web is hledger's web interface. -It starts a simple web application for browsing and adding transactions, -and optionally opens it in a web browser window if possible. -It provides a more user\-friendly UI than the hledger CLI or hledger\-ui -interface, showing more at once (accounts, the current account register, -balance charts) and allowing history\-aware data entry, interactive -searching, and bookmarking. -.PP -hledger\-web also lets you share a ledger with multiple users, or even -the public web. -There is no access control, so if you need that you should put it behind -a suitable web proxy. -As a small protection against data loss when running an unprotected -instance, it writes a numbered backup of the main journal file (only ?) -on every edit. -.PP -Like hledger, it reads data from one or more files in hledger journal, -timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -For more about this see hledger(1), hledger_journal(5) etc. -.PP -By default, hledger\-web starts the web app in \[lq]transient mode\[rq] -and also opens it in your default web browser if possible. -In this mode the web app will keep running for as long as you have it -open in a browser window, and will exit after two minutes of inactivity -(no requests and no browser windows viewing it). -With \f[C]\-\-serve\f[], it just runs the web app without exiting, and -logs requests to the console. -.PP -By default the server listens on IP address 127.0.0.1, accessible only -to local requests. -You can use \f[C]\-\-host\f[] to change this, eg -\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses. -.PP -Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg -if you are running multiple hledger\-web instances. -.PP -You can use \f[C]\-\-base\-url\f[] 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[C]http://HOST:PORT/\f[] using the server's configured -host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80). -.PP -With \f[C]\-\-file\-url\f[] you can set a different base url for static -files, eg for better caching or cookie\-less serving on high performance -websites. -.PP -Note there is no built\-in access control (aside from listening on -127.0.0.1 by default). -So you will need to hide hledger\-web behind an authenticating proxy -(such as apache or nginx) if you want to restrict who can see and add -entries to your journal. -.PP -Command\-line options and arguments may be used to set an initial filter -on the data. -This is not shown in the web UI, but it will be applied in addition to -any search query entered there. -.PP -With journal and timeclock files (but not CSV files, currently) the web -app detects changes made by other means and will show the new data on -the next request. -If a change makes the file unparseable, hledger\-web will show an error -until the file has been fixed. -.SH OPTIONS -.PP -Note: if invoking hledger\-web as a hledger subcommand, write -\f[C]\-\-\f[] before options as shown above. -.TP -.B \f[C]\-\-serve\f[] -serve and log requests, don't browse or auto\-exit -.RS -.RE -.TP -.B \f[C]\-\-host=IPADDR\f[] -listen on this IP address (default: 127.0.0.1) -.RS -.RE -.TP -.B \f[C]\-\-port=PORT\f[] -listen on this TCP port (default: 5000) -.RS -.RE -.TP -.B \f[C]\-\-base\-url=URL\f[] -set the base url (default: http://IPADDR:PORT). -You would change this when sharing over the network, or integrating -within a larger website. -.RS -.RE -.TP -.B \f[C]\-\-file\-url=URL\f[] -set the static files url (default: BASEURL/static). -hledger\-web normally serves static files itself, but if you wanted to -serve them from another server for efficiency, you would set the url -with this. -.RS -.RE -.PP -hledger input options: -.TP -.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] -use a different input file. -For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or -\f[C]$HOME/.hledger.journal\f[]) -.RS -.RE -.TP -.B \f[C]\-\-rules\-file=RULESFILE\f[] -Conversion rules file to use when reading CSV (default: FILE.rules) -.RS -.RE -.TP -.B \f[C]\-\-alias=OLD=NEW\f[] -rename accounts named OLD to NEW -.RS -.RE -.TP -.B \f[C]\-\-anon\f[] -anonymize accounts and payees -.RS -.RE -.TP -.B \f[C]\-\-pivot\ FIELDNAME\f[] -use some other field or tag for the account name -.RS -.RE -.TP -.B \f[C]\-I\ \-\-ignore\-assertions\f[] -ignore any failing balance assertions -.RS -.RE -.PP -hledger reporting options: -.TP -.B \f[C]\-b\ \-\-begin=DATE\f[] -include postings/txns on or after this date -.RS -.RE -.TP -.B \f[C]\-e\ \-\-end=DATE\f[] -include postings/txns before this date -.RS -.RE -.TP -.B \f[C]\-D\ \-\-daily\f[] -multiperiod/multicolumn report by day -.RS -.RE -.TP -.B \f[C]\-W\ \-\-weekly\f[] -multiperiod/multicolumn report by week -.RS -.RE -.TP -.B \f[C]\-M\ \-\-monthly\f[] -multiperiod/multicolumn report by month -.RS -.RE -.TP -.B \f[C]\-Q\ \-\-quarterly\f[] -multiperiod/multicolumn report by quarter -.RS -.RE -.TP -.B \f[C]\-Y\ \-\-yearly\f[] -multiperiod/multicolumn report by year -.RS -.RE -.TP -.B \f[C]\-p\ \-\-period=PERIODEXP\f[] -set start date, end date, and/or reporting interval all at once using -period expressions syntax (overrides the flags above) -.RS -.RE -.TP -.B \f[C]\-\-date2\f[] -match the secondary date instead (see command help for other effects) -.RS -.RE -.TP -.B \f[C]\-U\ \-\-unmarked\f[] -include only unmarked postings/txns (can combine with \-P or \-C) -.RS -.RE -.TP -.B \f[C]\-P\ \-\-pending\f[] -include only pending postings/txns -.RS -.RE -.TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns -.RS -.RE -.TP -.B \f[C]\-R\ \-\-real\f[] -include only non\-virtual postings -.RS -.RE -.TP -.B \f[C]\-NUM\ \-\-depth=NUM\f[] -hide/aggregate accounts or postings more than NUM levels deep -.RS -.RE -.TP -.B \f[C]\-E\ \-\-empty\f[] -show items with zero amount, normally hidden -.RS -.RE -.TP -.B \f[C]\-B\ \-\-cost\f[] -convert amounts to their cost at transaction time (using the transaction -price, if any) -.RS -.RE -.TP -.B \f[C]\-V\ \-\-value\f[] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) -.RS -.RE -.TP -.B \f[C]\-\-auto\f[] -apply automated posting rules to modify transactions. -.RS -.RE -.TP -.B \f[C]\-\-forecast\f[] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. -.RS -.RE -.PP -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 -.B \f[C]\-h\ \-\-help\f[] -show general usage (or after COMMAND, command usage) -.RS -.RE -.TP -.B \f[C]\-\-version\f[] -show version -.RS -.RE -.TP -.B \f[C]\-\-debug[=N]\f[] -show debug output (levels 1\-9, default: 1) -.RS -.RE -.PP -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 \f[C]\-\-\f[] argument before.) -.SH ENVIRONMENT -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede options with \f[C]\-\-\f[] when invoked from hledger -is awkward. -.PP -\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin). -.PP -Query arguments and some hledger options are ignored. -.PP -Does not work in text\-mode browsers. -.PP -Does not work well on small screens. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger-web.info b/.otherdocs/hledger-web.info deleted file mode 100644 --- a/.otherdocs/hledger-web.info +++ /dev/null @@ -1,214 +0,0 @@ -This is hledger-web.info, produced by makeinfo version 6.5 from stdin. - - -File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-web(1) hledger-web 1.5 -****************************** - -hledger-web is hledger's web interface. It starts a simple web -application for browsing and adding transactions, and optionally opens -it in a web browser window if possible. It provides a more -user-friendly UI than the hledger CLI or hledger-ui interface, showing -more at once (accounts, the current account register, balance charts) -and allowing history-aware data entry, interactive searching, and -bookmarking. - - hledger-web also lets you share a ledger with multiple users, or even -the public web. There is no access control, so if you need that you -should put it behind a suitable web proxy. As a small protection -against data loss when running an unprotected instance, it writes a -numbered backup of the main journal file (only ?) on every edit. - - Like hledger, it reads data from one or more files in hledger -journal, timeclock, timedot, or CSV format specified with '-f', or -'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), -hledger_journal(5) etc. - - By default, hledger-web starts the web app in "transient mode" and -also opens it in your default web browser if possible. In this mode the -web app will keep running for as long as you have it open in a browser -window, and will exit after two minutes of inactivity (no requests and -no browser windows viewing it). With '--serve', it just runs the web -app without exiting, and logs requests to the console. - - 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. - - 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. - - Note there is no built-in access control (aside from listening on -127.0.0.1 by default). So you will need to hide hledger-web behind an -authenticating proxy (such as apache or nginx) if you want to restrict -who can see and add entries to your journal. - - Command-line options and arguments may be used to set an initial -filter on the data. This is not shown in the web UI, but it will be -applied in addition to any search query entered there. - - With journal and timeclock files (but not CSV files, currently) the -web app detects changes made by other means and will show the new data -on the next request. If a change makes the file unparseable, -hledger-web will show an error until the file has been fixed. -* Menu: - -* OPTIONS:: - - -File: hledger-web.info, Node: OPTIONS, Prev: Top, Up: Top - -1 OPTIONS -********* - -Note: if invoking hledger-web as a hledger subcommand, write '--' before -options as shown above. - -'--serve' - - serve and log requests, don't browse or auto-exit -'--host=IPADDR' - - listen on this IP address (default: 127.0.0.1) -'--port=PORT' - - listen on this TCP port (default: 5000) -'--base-url=URL' - - set the base url (default: http://IPADDR:PORT). You would change - this when sharing over the network, or integrating within a larger - website. -'--file-url=URL' - - set the static files url (default: BASEURL/static). hledger-web - normally serves static files itself, but if you wanted to serve - them from another server for efficiency, you would set the url with - this. - - hledger 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: FILE.rules) -'--alias=OLD=NEW' - - rename accounts named OLD to NEW -'--anon' - - anonymize accounts and payees -'--pivot FIELDNAME' - - use some other field or tag for the account name -'-I --ignore-assertions' - - ignore any failing balance assertions - - hledger reporting options: - -'-b --begin=DATE' - - include postings/txns on or after this date -'-e --end=DATE' - - include postings/txns before this date -'-D --daily' - - multiperiod/multicolumn report by day -'-W --weekly' - - multiperiod/multicolumn report by week -'-M --monthly' - - multiperiod/multicolumn report by month -'-Q --quarterly' - - multiperiod/multicolumn report by quarter -'-Y --yearly' - - multiperiod/multicolumn report by year -'-p --period=PERIODEXP' - - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) -'--date2' - - match the secondary date instead (see command help for other - effects) -'-U --unmarked' - - include only unmarked postings/txns (can combine with -P or -C) -'-P --pending' - - include only pending postings/txns -'-C --cleared' - - include only cleared postings/txns -'-R --real' - - include only non-virtual postings -'-NUM --depth=NUM' - - hide/aggregate accounts or postings more than NUM levels deep -'-E --empty' - - show items with zero amount, normally hidden -'-B --cost' - - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' - - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) -'--auto' - - apply automated posting rules to modify transactions. -'--forecast' - - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, -the last one takes precedence. - - Some reporting options can also be written as query arguments. - - hledger help options: - -'-h --help' - - show general usage (or after COMMAND, command usage) -'--version' - - show 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.) - - -Tag Table: -Node: Top72 -Node: OPTIONS3152 -Ref: #options3237 - -End Tag Table diff --git a/.otherdocs/hledger-web.txt b/.otherdocs/hledger-web.txt deleted file mode 100644 --- a/.otherdocs/hledger-web.txt +++ /dev/null @@ -1,250 +0,0 @@ - -hledger-web(1) hledger User Manuals hledger-web(1) - - - -NAME - hledger-web - web interface for the hledger accounting tool - -SYNOPSIS - hledger-web [OPTIONS] - hledger web -- [OPTIONS] - -DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any - other commodity, using double-entry accounting and a simple, editable - file format. hledger is inspired by and largely compatible with - ledger(1). - - hledger-web is hledger's web interface. It starts a simple web appli- - cation for browsing and adding transactions, and optionally opens it in - a web browser window if possible. It provides a more user-friendly UI - than the hledger CLI or hledger-ui interface, showing more at once - (accounts, the current account register, balance charts) and allowing - history-aware data entry, interactive searching, and bookmarking. - - hledger-web also lets you share a ledger with multiple users, or even - the public web. There is no access control, so if you need that you - should put it behind a suitable web proxy. As a small protection - against data loss when running an unprotected instance, it writes a - numbered backup of the main journal file (only ?) on every edit. - - Like hledger, it reads data from one or more files in hledger journal, - timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, - or $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). For more about this see hledger(1), - hledger_journal(5) etc. - - By default, hledger-web starts the web app in "transient mode" and also - opens it in your default web browser if possible. In this mode the web - app will keep running for as long as you have it open in a browser win- - dow, and will exit after two minutes of inactivity (no requests and no - browser windows viewing it). With --serve, it just runs the web app - without exiting, and logs requests to the console. - - 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. - - 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. - - Note there is no built-in access control (aside from listening on - 127.0.0.1 by default). So you will need to hide hledger-web behind an - authenticating proxy (such as apache or nginx) if you want to restrict - who can see and add entries to your journal. - - Command-line options and arguments may be used to set an initial filter - on the data. This is not shown in the web UI, but it will be applied - in addition to any search query entered there. - - With journal and timeclock files (but not CSV files, currently) the web - app detects changes made by other means and will show the new data on - the next request. If a change makes the file unparseable, hledger-web - will show an error until the file has been fixed. - -OPTIONS - Note: if invoking hledger-web as a hledger subcommand, write -- before - options as shown above. - - --serve - serve and log requests, don't browse or auto-exit - - --host=IPADDR - listen on this IP address (default: 127.0.0.1) - - --port=PORT - listen on this TCP port (default: 5000) - - --base-url=URL - set the base url (default: http://IPADDR:PORT). You would - change this when sharing over the network, or integrating within - a larger website. - - --file-url=URL - set the static files url (default: BASEURL/static). hledger-web - normally serves static files itself, but if you wanted to serve - them from another server for efficiency, you would set the url - with this. - - hledger 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: - FILE.rules) - - --alias=OLD=NEW - rename accounts named OLD to NEW - - --anon anonymize accounts and payees - - --pivot FIELDNAME - use some other field or tag for the account name - - -I --ignore-assertions - ignore any failing balance assertions - - hledger reporting options: - - -b --begin=DATE - include postings/txns on or after this date - - -e --end=DATE - include postings/txns before this date - - -D --daily - multiperiod/multicolumn report by day - - -W --weekly - multiperiod/multicolumn report by week - - -M --monthly - multiperiod/multicolumn report by month - - -Q --quarterly - multiperiod/multicolumn report by quarter - - -Y --yearly - multiperiod/multicolumn report by year - - -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once - using period expressions syntax (overrides the flags above) - - --date2 - match the secondary date instead (see command help for other - effects) - - -U --unmarked - include only unmarked postings/txns (can combine with -P or -C) - - -P --pending - include only pending postings/txns - - -C --cleared - include only cleared postings/txns - - -R --real - include only non-virtual postings - - -NUM --depth=NUM - hide/aggregate accounts or postings more than NUM levels deep - - -E --empty - show items with zero amount, normally hidden - - -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) - - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) - - --auto apply automated posting rules to modify transactions. - - --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. - - When a reporting option appears more than once in the command line, the - last one takes precedence. - - Some reporting options can also be written as query arguments. - - hledger help options: - - -h --help - show general usage (or after COMMAND, command usage) - - --version - show 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.) - -ENVIRONMENT - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede options with -- when invoked from hledger is awk- - ward. - - -f- doesn't work (hledger-web can't read from stdin). - - Query arguments and some hledger options are ignored. - - Does not work in text-mode browsers. - - Does not work well on small screens. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger-web 1.5 December 2017 hledger-web(1) diff --git a/.otherdocs/hledger_csv.5 b/.otherdocs/hledger_csv.5 deleted file mode 100644 --- a/.otherdocs/hledger_csv.5 +++ /dev/null @@ -1,334 +0,0 @@ - -.TH "hledger_csv" "5" "December 2017" "hledger 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -CSV \- how hledger reads CSV data, and the CSV rules file format -.SH DESCRIPTION -.PP -hledger can read CSV (comma\-separated value) files as if they were -journal files, automatically converting each CSV record into a -transaction. -(To learn about \f[I]writing\f[] CSV, see CSV output.) -.PP -Converting CSV to transactions requires some special conversion rules. -These do several things: -.IP \[bu] 2 -they describe the layout and format of the CSV data -.IP \[bu] 2 -they can customize the generated journal entries using a simple -templating language -.IP \[bu] 2 -they can add refinements based on patterns in the CSV data, eg -categorizing transactions with more detailed account names. -.PP -When reading a CSV file named \f[C]FILE.csv\f[], hledger looks for a -conversion rules file named \f[C]FILE.csv.rules\f[] in the same -directory. -You can override this with the \f[C]\-\-rules\-file\f[] option. -If the rules file does not exist, hledger will auto\-create one with -some example rules, which you'll need to adjust. -.PP -At minimum, the rules file must identify the \f[C]date\f[] and -\f[C]amount\f[] fields. -It may also be necessary to specify the date format, and the number of -header lines to skip. -Eg: -.IP -.nf -\f[C] -fields\ date,\ _,\ _,\ amount -date\-format\ \ %d/%m/%Y -skip\ 1 -\f[] -.fi -.PP -A more complete example: -.IP -.nf -\f[C] -#\ hledger\ CSV\ rules\ for\ amazon.com\ order\ history - -#\ sample: -#\ "Date","Type","To/From","Name","Status","Amount","Fees","Transaction\ ID" -#\ "Jul\ 29,\ 2012","Payment","To","Adapteva,\ Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" - -#\ skip\ one\ header\ line -skip\ 1 - -#\ name\ the\ csv\ fields\ (and\ assign\ the\ transaction\[aq]s\ date,\ amount\ and\ code) -fields\ date,\ _,\ toorfrom,\ name,\ amzstatus,\ amount,\ fees,\ code - -#\ how\ to\ parse\ the\ date -date\-format\ %b\ %\-d,\ %Y - -#\ combine\ two\ fields\ to\ make\ the\ description -description\ %toorfrom\ %name - -#\ save\ these\ fields\ as\ tags -comment\ \ \ \ \ status:%amzstatus,\ fees:%fees - -#\ set\ the\ base\ account\ for\ all\ transactions -account1\ \ \ \ assets:amazon - -#\ flip\ the\ sign\ on\ the\ amount -amount\ \ \ \ \ \ \-%amount -\f[] -.fi -.PP -For more examples, see Convert CSV files. -.SH CSV RULES -.PP -The following seven kinds of rule can appear in the rules file, in any -order. -Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are -ignored. -.SS skip -.PP -\f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[] -.PP -Skip this number of CSV records at the beginning. -You'll need this whenever your CSV data contains header lines. -Eg: -.IP -.nf -\f[C] -#\ ignore\ the\ first\ CSV\ line -skip\ 1 -\f[] -.fi -.SS date\-format -.PP -\f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[] -.PP -When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or -\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you'll need to specify -the format. -DATEFMT is a strptime\-like date parsing pattern, which must parse the -date field values completely. -Examples: -.IP -.nf -\f[C] -#\ for\ dates\ like\ "6/11/2013": -date\-format\ %\-d/%\-m/%Y -\f[] -.fi -.IP -.nf -\f[C] -#\ for\ dates\ like\ "11/06/2013": -date\-format\ %m/%d/%Y -\f[] -.fi -.IP -.nf -\f[C] -#\ for\ dates\ like\ "2013\-Nov\-06": -date\-format\ %Y\-%h\-%d -\f[] -.fi -.IP -.nf -\f[C] -#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM": -date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p -\f[] -.fi -.SS field list -.PP -\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[], -\f[I]\f[CI]FIELDNAME2\f[I]\f[]\&... -.PP -This (a) names the CSV fields, in order (names may not contain -whitespace; uninteresting names may be left blank), and (b) assigns them -to journal entry fields if you use any of these standard field names: -\f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], -\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[], -\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[], -\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[]. -Eg: -.IP -.nf -\f[C] -#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]s\ date,\ description\ and\ amount, -#\ and\ give\ the\ 7th\ and\ 8th\ fields\ meaningful\ names\ for\ later\ reference: -# -#\ CSV\ field: -#\ \ \ \ \ \ 1\ \ \ \ \ 2\ \ \ \ \ \ \ \ \ \ \ \ 3\ 4\ \ \ \ \ \ \ 5\ 6\ 7\ \ \ \ \ \ \ \ \ \ 8 -#\ entry\ field: -fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield -\f[] -.fi -.SS field assignment -.PP -\f[I]\f[CI]ENTRYFIELDNAME\f[I]\f[] \f[I]\f[CI]FIELDVALUE\f[I]\f[] -.PP -This sets a journal entry field (one of the standard names above) to the -given text value, which can include CSV field values interpolated by -name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]). - Eg: -.IP -.nf -\f[C] -#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended -amount\ USD\ %4 -\f[] -.fi -.IP -.nf -\f[C] -#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags) -comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1 -\f[] -.fi -.PP -Field assignments can be used instead of or in addition to a field list. -.SS conditional block -.PP -\f[C]if\f[] \f[I]\f[CI]PATTERN\f[I]\f[] -.PD 0 -.P -.PD -\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... -.PP -\f[C]if\f[] -.PD 0 -.P -.PD -\f[I]\f[CI]PATTERN\f[I]\f[] -.PD 0 -.P -.PD -\f[I]\f[CI]PATTERN\f[I]\f[]\&... -.PD 0 -.P -.PD -\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... -.PP -This applies one or more field assignments, only to those CSV records -matched by one of the PATTERNs. -The patterns are case\-insensitive regular expressions which match -anywhere within the whole CSV record (it's not yet possible to match -within a specific field). -When there are multiple patterns they can be written on separate lines, -unindented. -The field assignments are on separate lines indented by at least one -space. -Examples: -.IP -.nf -\f[C] -#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries" -if\ groceries -\ account2\ expenses:groceries -\f[] -.fi -.IP -.nf -\f[C] -#\ if\ the\ CSV\ record\ contains\ any\ of\ these\ patterns,\ set\ account2\ and\ comment\ as\ shown -if -monthly\ service\ fee -atm\ transaction\ fee -banking\ thru\ software -\ account2\ expenses:business:banking -\ comment\ \ XXX\ deductible\ ?\ check\ it -\f[] -.fi -.SS include -.PP -\f[C]include\f[]\f[I]\f[CI]RULESFILE\f[I]\f[] -.PP -Include another rules file at this point. -\f[C]RULESFILE\f[] is either an absolute file path or a path relative to -the current file's directory. -Eg: -.IP -.nf -\f[C] -#\ rules\ reused\ with\ several\ CSV\ files -include\ common.rules -\f[] -.fi -.SS newest\-first -.PP -\f[C]newest\-first\f[] -.PP -Consider adding this rule if all of the following are true: you might be -processing just one day of data, your CSV records are in reverse -chronological order (newest first), and you care about preserving the -order of same\-day transactions. -It usually isn't needed, because hledger autodetects the CSV order, but -when all CSV records have the same date it will assume they are oldest -first. -.SH CSV TIPS -.SS CSV ordering -.PP -The generated journal entries will be sorted by date. -The order of same\-day entries will be preserved (except in the special -case where you might need \f[C]newest\-first\f[], see above). -.SS CSV accounts -.PP -Each journal entry will have two postings, to \f[C]account1\f[] and -\f[C]account2\f[] respectively. -It's not yet possible to generate entries with more than two postings. -It's conventional and recommended to use \f[C]account1\f[] for the -account whose CSV we are reading. -.SS CSV amounts -.PP -The \f[C]amount\f[] field sets the amount of the \f[C]account1\f[] -posting. -.PP -If the CSV has debit/credit amounts in separate fields, assign to the -\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead. -(Whichever one has a value will be used, with appropriate sign. -If both contain a value, it may not work so well.) -.PP -If an amount value is parenthesised, it will be de\-parenthesised and -sign\-flipped. -.PP -If an amount value begins with a double minus sign, those will cancel -out and be removed. -.PP -If the CSV has the currency symbol in a separate field, assign that to -the \f[C]currency\f[] pseudo field to have it prepended to the amount. -Or, you can use a field assignment to \f[C]amount\f[] that interpolates -both CSV fields (giving more control, eg to put the currency symbol on -the right). -.SS CSV balance assertions -.PP -If the CSV includes a running balance, you can assign that to the -\f[C]balance\f[] pseudo field; whenever the running balance value is -non\-empty, it will be asserted as the balance after the -\f[C]account1\f[] posting. -.SS Reading multiple CSV files -.PP -You can read multiple CSV files at once using multiple \f[C]\-f\f[] -arguments on the command line, and hledger will look for a -correspondingly\-named rules file for each. -Note if you use the \f[C]\-\-rules\-file\f[] option, this one rules file -will be used for all the CSV files being read. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger_csv.info b/.otherdocs/hledger_csv.info deleted file mode 100644 --- a/.otherdocs/hledger_csv.info +++ /dev/null @@ -1,349 +0,0 @@ -This is hledger_csv.info, produced by makeinfo version 6.5 from stdin. - - -File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir) - -hledger_csv(5) hledger 1.5 -************************** - -hledger can read CSV (comma-separated value) files as if they were -journal files, automatically converting each CSV record into a -transaction. (To learn about _writing_ CSV, see CSV output.) - - Converting CSV to transactions requires some special conversion -rules. These do several things: - - * they describe the layout and format of the CSV data - * they can customize the generated journal entries using a simple - templating language - * they can add refinements based on patterns in the CSV data, eg - categorizing transactions with more detailed account names. - - When reading a CSV file named 'FILE.csv', hledger looks for a -conversion rules file named 'FILE.csv.rules' in the same directory. You -can override this with the '--rules-file' option. If the rules file -does not exist, hledger will auto-create one with some example rules, -which you'll need to adjust. - - At minimum, the rules file must identify the 'date' and 'amount' -fields. It may also be necessary to specify the date format, and the -number of header lines to skip. Eg: - -fields date, _, _, amount -date-format %d/%m/%Y -skip 1 - - A more complete example: - -# hledger CSV rules for amazon.com order history - -# sample: -# "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" -# "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" - -# skip one header line -skip 1 - -# name the csv fields (and assign the transaction's date, amount and code) -fields date, _, toorfrom, name, amzstatus, amount, fees, code - -# how to parse the date -date-format %b %-d, %Y - -# combine two fields to make the description -description %toorfrom %name - -# save these fields as tags -comment status:%amzstatus, fees:%fees - -# set the base account for all transactions -account1 assets:amazon - -# flip the sign on the amount -amount -%amount - - For more examples, see Convert CSV files. -* Menu: - -* CSV RULES:: -* CSV TIPS:: - - -File: hledger_csv.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top - -1 CSV RULES -*********** - -The following seven kinds of rule can appear in the rules file, in any -order. Blank lines and lines beginning with '#' or ';' are ignored. -* Menu: - -* skip:: -* date-format:: -* field list:: -* field assignment:: -* conditional block:: -* include:: -* newest-first:: - - -File: hledger_csv.info, Node: skip, Next: date-format, Up: CSV RULES - -1.1 skip -======== - -'skip'_'N'_ - - Skip this number of CSV records at the beginning. You'll need this -whenever your CSV data contains header lines. Eg: - -# ignore the first CSV line -skip 1 - - -File: hledger_csv.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES - -1.2 date-format -=============== - -'date-format'_'DATEFMT'_ - - When your CSV date fields are not formatted like 'YYYY/MM/DD' (or -'YYYY-MM-DD' or 'YYYY.MM.DD'), you'll need to specify the format. -DATEFMT is a strptime-like date parsing pattern, which must parse the -date field values completely. Examples: - -# for dates like "6/11/2013": -date-format %-d/%-m/%Y - -# for dates like "11/06/2013": -date-format %m/%d/%Y - -# for dates like "2013-Nov-06": -date-format %Y-%h-%d - -# for dates like "11/6/2013 11:32 PM": -date-format %-m/%-d/%Y %l:%M %p - - -File: hledger_csv.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES - -1.3 field list -============== - -'fields'_'FIELDNAME1'_, _'FIELDNAME2'_... - - This (a) names the CSV fields, in order (names may not contain -whitespace; uninteresting names may be left blank), and (b) assigns them -to journal entry fields if you use any of these standard field names: -'date', 'date2', 'status', 'code', 'description', 'comment', 'account1', -'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'. -Eg: - -# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, -# and give the 7th and 8th fields meaningful names for later reference: -# -# CSV field: -# 1 2 3 4 5 6 7 8 -# entry field: -fields date, description, , amount, , , somefield, anotherfield - - -File: hledger_csv.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES - -1.4 field assignment -==================== - -_'ENTRYFIELDNAME'_ _'FIELDVALUE'_ - - This sets a journal entry field (one of the standard names above) to -the given text value, which can include CSV field values interpolated by -name ('%CSVFIELDNAME') or 1-based position ('%N'). Eg: - -# set the amount to the 4th CSV field with "USD " prepended -amount USD %4 - -# combine three fields to make a comment (containing two tags) -comment note: %somefield - %anotherfield, date: %1 - - Field assignments can be used instead of or in addition to a field -list. - - -File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES - -1.5 conditional block -===================== - -'if' _'PATTERN'_ - _'FIELDASSIGNMENTS'_... - - 'if' -_'PATTERN'_ -_'PATTERN'_... - _'FIELDASSIGNMENTS'_... - - This applies one or more field assignments, only to those CSV records -matched by one of the PATTERNs. The patterns are case-insensitive -regular expressions which match anywhere within the whole CSV record -(it's not yet possible to match within a specific field). When there -are multiple patterns they can be written on separate lines, unindented. -The field assignments are on separate lines indented by at least one -space. Examples: - -# if the CSV record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the CSV record contains any of these patterns, set account2 and comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - -File: hledger_csv.info, Node: include, Next: newest-first, Prev: conditional block, Up: CSV RULES - -1.6 include -=========== - -'include'_'RULESFILE'_ - - Include another rules file at this point. 'RULESFILE' is either an -absolute file path or a path relative to the current file's directory. -Eg: - -# rules reused with several CSV files -include common.rules - - -File: hledger_csv.info, Node: newest-first, Prev: include, Up: CSV RULES - -1.7 newest-first -================ - -'newest-first' - - Consider adding this rule if all of the following are true: you might -be processing just one day of data, your CSV records are in reverse -chronological order (newest first), and you care about preserving the -order of same-day transactions. It usually isn't needed, because -hledger autodetects the CSV order, but when all CSV records have the -same date it will assume they are oldest first. - - -File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top - -2 CSV TIPS -********** - -* Menu: - -* CSV ordering:: -* CSV accounts:: -* CSV amounts:: -* CSV balance assertions:: -* Reading multiple CSV files:: - - -File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS - -2.1 CSV ordering -================ - -The generated journal entries will be sorted by date. The order of -same-day entries will be preserved (except in the special case where you -might need 'newest-first', see above). - - -File: hledger_csv.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS - -2.2 CSV accounts -================ - -Each journal entry will have two postings, to 'account1' and 'account2' -respectively. It's not yet possible to generate entries with more than -two postings. It's conventional and recommended to use 'account1' for -the account whose CSV we are reading. - - -File: hledger_csv.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS - -2.3 CSV amounts -=============== - -The 'amount' field sets the amount of the 'account1' posting. - - If the CSV has debit/credit amounts in separate fields, assign to the -'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has -a value will be used, with appropriate sign. If both contain a value, -it may not work so well.) - - If an amount value is parenthesised, it will be de-parenthesised and -sign-flipped. - - If an amount value begins with a double minus sign, those will cancel -out and be removed. - - If the CSV has the currency symbol in a separate field, assign that -to the 'currency' pseudo field to have it prepended to the amount. Or, -you can use a field assignment to 'amount' that interpolates both CSV -fields (giving more control, eg to put the currency symbol on the -right). - - -File: hledger_csv.info, Node: CSV balance assertions, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS - -2.4 CSV balance assertions -========================== - -If the CSV includes a running balance, you can assign that to the -'balance' pseudo field; whenever the running balance value is non-empty, -it will be asserted as the balance after the 'account1' posting. - - -File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions, Up: CSV TIPS - -2.5 Reading multiple CSV files -============================== - -You can read multiple CSV files at once using multiple '-f' arguments on -the command line, and hledger will look for a correspondingly-named -rules file for each. Note if you use the '--rules-file' option, this -one rules file will be used for all the CSV files being read. - - -Tag Table: -Node: Top72 -Node: CSV RULES2161 -Ref: #csv-rules2269 -Node: skip2531 -Ref: #skip2625 -Node: date-format2797 -Ref: #date-format2924 -Node: field list3430 -Ref: #field-list3567 -Node: field assignment4272 -Ref: #field-assignment4427 -Node: conditional block4931 -Ref: #conditional-block5085 -Node: include5981 -Ref: #include6111 -Node: newest-first6342 -Ref: #newest-first6456 -Node: CSV TIPS6867 -Ref: #csv-tips6961 -Node: CSV ordering7079 -Ref: #csv-ordering7197 -Node: CSV accounts7378 -Ref: #csv-accounts7516 -Node: CSV amounts7770 -Ref: #csv-amounts7916 -Node: CSV balance assertions8691 -Ref: #csv-balance-assertions8873 -Node: Reading multiple CSV files9078 -Ref: #reading-multiple-csv-files9248 - -End Tag Table diff --git a/.otherdocs/hledger_csv.txt b/.otherdocs/hledger_csv.txt deleted file mode 100644 --- a/.otherdocs/hledger_csv.txt +++ /dev/null @@ -1,252 +0,0 @@ - -hledger_csv(5) hledger User Manuals hledger_csv(5) - - - -NAME - CSV - how hledger reads CSV data, and the CSV rules file format - -DESCRIPTION - hledger can read CSV (comma-separated value) files as if they were - journal files, automatically converting each CSV record into a transac- - tion. (To learn about writing CSV, see CSV output.) - - Converting CSV to transactions requires some special conversion rules. - These do several things: - - o they describe the layout and format of the CSV data - - o they can customize the generated journal entries using a simple tem- - plating language - - o they can add refinements based on patterns in the CSV data, eg cate- - gorizing transactions with more detailed account names. - - When reading a CSV file named FILE.csv, hledger looks for a conversion - rules file named FILE.csv.rules in the same directory. You can over- - ride this with the --rules-file option. If the rules file does not - exist, hledger will auto-create one with some example rules, which - you'll need to adjust. - - At minimum, the rules file must identify the date and amount fields. - It may also be necessary to specify the date format, and the number of - header lines to skip. Eg: - - fields date, _, _, amount - date-format %d/%m/%Y - skip 1 - - A more complete example: - - # hledger CSV rules for amazon.com order history - - # sample: - # "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" - # "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" - - # skip one header line - skip 1 - - # name the csv fields (and assign the transaction's date, amount and code) - fields date, _, toorfrom, name, amzstatus, amount, fees, code - - # how to parse the date - date-format %b %-d, %Y - - # combine two fields to make the description - description %toorfrom %name - - # save these fields as tags - comment status:%amzstatus, fees:%fees - - # set the base account for all transactions - account1 assets:amazon - - # flip the sign on the amount - amount -%amount - - For more examples, see Convert CSV files. - -CSV RULES - The following seven kinds of rule can appear in the rules file, in any - order. Blank lines and lines beginning with # or ; are ignored. - - skip - skipN - - Skip this number of CSV records at the beginning. You'll need this - whenever your CSV data contains header lines. Eg: - - # ignore the first CSV line - skip 1 - - date-format - date-formatDATEFMT - - When your CSV date fields are not formatted like YYYY/MM/DD (or - YYYY-MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT - is a strptime-like date parsing pattern, which must parse the date - field values completely. Examples: - - # for dates like "6/11/2013": - date-format %-d/%-m/%Y - - # for dates like "11/06/2013": - date-format %m/%d/%Y - - # for dates like "2013-Nov-06": - date-format %Y-%h-%d - - # for dates like "11/6/2013 11:32 PM": - date-format %-m/%-d/%Y %l:%M %p - - field list - fieldsFIELDNAME1, FIELDNAME2... - - This (a) names the CSV fields, in order (names may not contain white- - space; uninteresting names may be left blank), and (b) assigns them to - journal entry fields if you use any of these standard field names: - date, date2, status, code, description, comment, account1, account2, - amount, amount-in, amount-out, currency, balance. Eg: - - # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, - # and give the 7th and 8th fields meaningful names for later reference: - # - # CSV field: - # 1 2 3 4 5 6 7 8 - # entry field: - fields date, description, , amount, , , somefield, anotherfield - - field assignment - ENTRYFIELDNAME FIELDVALUE - - This sets a journal entry field (one of the standard names above) to - the given text value, which can include CSV field values interpolated - by name (%CSVFIELDNAME) or 1-based position (%N). - Eg: - - # set the amount to the 4th CSV field with "USD " prepended - amount USD %4 - - # combine three fields to make a comment (containing two tags) - comment note: %somefield - %anotherfield, date: %1 - - Field assignments can be used instead of or in addition to a field - list. - - conditional block - if PATTERN - FIELDASSIGNMENTS... - - if - PATTERN - PATTERN... - FIELDASSIGNMENTS... - - This applies one or more field assignments, only to those CSV records - matched by one of the PATTERNs. The patterns are case-insensitive reg- - ular expressions which match anywhere within the whole CSV record (it's - not yet possible to match within a specific field). When there are - multiple patterns they can be written on separate lines, unindented. - The field assignments are on separate lines indented by at least one - space. Examples: - - # if the CSV record contains "groceries", set account2 to "expenses:groceries" - if groceries - account2 expenses:groceries - - # if the CSV record contains any of these patterns, set account2 and comment as shown - if - monthly service fee - atm transaction fee - banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - - include - includeRULESFILE - - Include another rules file at this point. RULESFILE is either an abso- - lute file path or a path relative to the current file's directory. Eg: - - # rules reused with several CSV files - include common.rules - - newest-first - newest-first - - Consider adding this rule if all of the following are true: you might - be processing just one day of data, your CSV records are in reverse - chronological order (newest first), and you care about preserving the - order of same-day transactions. It usually isn't needed, because - hledger autodetects the CSV order, but when all CSV records have the - same date it will assume they are oldest first. - -CSV TIPS - CSV ordering - The generated journal entries will be sorted by date. The order of - same-day entries will be preserved (except in the special case where - you might need newest-first, see above). - - CSV accounts - Each journal entry will have two postings, to account1 and account2 - respectively. It's not yet possible to generate entries with more than - two postings. It's conventional and recommended to use account1 for - the account whose CSV we are reading. - - CSV amounts - The amount field sets the amount of the account1 posting. - - If the CSV has debit/credit amounts in separate fields, assign to the - amount-in and amount-out pseudo fields instead. (Whichever one has a - value will be used, with appropriate sign. If both contain a value, it - may not work so well.) - - If an amount value is parenthesised, it will be de-parenthesised and - sign-flipped. - - If an amount value begins with a double minus sign, those will cancel - out and be removed. - - If the CSV has the currency symbol in a separate field, assign that to - the currency pseudo field to have it prepended to the amount. Or, you - can use a field assignment to amount that interpolates both CSV fields - (giving more control, eg to put the currency symbol on the right). - - CSV balance assertions - If the CSV includes a running balance, you can assign that to the bal- - ance pseudo field; whenever the running balance value is non-empty, it - will be asserted as the balance after the account1 posting. - - Reading multiple CSV files - You can read multiple CSV files at once using multiple -f arguments on - the command line, and hledger will look for a correspondingly-named - rules file for each. Note if you use the --rules-file option, this one - rules file will be used for all the CSV files being read. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger 1.5 December 2017 hledger_csv(5) diff --git a/.otherdocs/hledger_journal.5 b/.otherdocs/hledger_journal.5 deleted file mode 100644 --- a/.otherdocs/hledger_journal.5 +++ /dev/null @@ -1,1249 +0,0 @@ -.\"t - -.TH "hledger_journal" "5" "December 2017" "hledger 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -Journal \- hledger's default file format, representing a General Journal -.SH DESCRIPTION -.PP -hledger's usual data source is a plain text file containing journal -entries in hledger journal format. -This file represents a standard accounting general journal. -I use file names ending in \f[C]\&.journal\f[], but that's not required. -The journal file contains a number of transaction entries, each -describing a transfer of money (or any commodity) between two or more -named accounts, in a simple format readable by both hledger and humans. -.PP -hledger's journal format is a compatible subset, mostly, of ledger's -journal format, so hledger can work with compatible ledger journal files -as well. -It's safe, and encouraged, to run both hledger and ledger on the same -journal file, eg to validate the results you're getting. -.PP -You can use hledger without learning any more about this file; just use -the add or web commands to create and update it. -Many users, though, also edit the journal file directly with a text -editor, perhaps assisted by the helper modes for emacs or vim. -.PP -Here's an example: -.IP -.nf -\f[C] -;\ A\ sample\ journal\ file.\ This\ is\ a\ comment. - -2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ transaction\[aq]s\ first\ line\ starts\ in\ column\ 0,\ contains\ date\ and\ description -\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ posting\ lines\ start\ with\ whitespace,\ each\ contains\ an\ account\ name -\ \ \ \ income:salary\ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ \ \ \ followed\ by\ at\ least\ two\ spaces\ and\ an\ amount - -2008/06/01\ gift -\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ at\ least\ two\ postings\ in\ a\ transaction -\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ <\-\ their\ amounts\ must\ balance\ to\ 0 - -2008/06/02\ save -\ \ \ \ assets:bank:saving\ \ \ \ $1 -\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ ;\ <\-\ one\ amount\ may\ be\ omitted;\ here\ $\-1\ is\ inferred - -2008/06/03\ eat\ &\ shop\ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ description\ can\ be\ anything -\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ $1 -\ \ \ \ expenses:supplies\ \ \ \ \ $1\ \ \ \ ;\ <\-\ this\ transaction\ debits\ two\ expense\ accounts -\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ $\-2\ inferred - -2008/10/01\ take\ a\ loan -\ \ \ \ assets:bank:checking\ \ $1 -\ \ \ \ liabilities:debts\ \ \ \ $\-1 - -2008/12/31\ *\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ an\ optional\ *\ or\ !\ after\ the\ date\ means\ "cleared"\ (or\ anything\ you\ want) -\ \ \ \ liabilities:debts\ \ \ \ \ $1 -\ \ \ \ assets:bank:checking -\f[] -.fi -.SH FILE FORMAT -.SS Transactions -.PP -Transactions are movements of some quantity of commodities between named -accounts. -Each transaction is represented by a journal entry beginning with a -simple date in column 0. -This can be followed by any of the following, separated by spaces: -.IP \[bu] 2 -(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]) -.IP \[bu] 2 -(optional) a transaction code (any short number or text, enclosed in -parentheses) -.IP \[bu] 2 -(optional) a transaction description (any remaining text until end of -line or a semicolon) -.IP \[bu] 2 -(optional) a transaction comment (any remaining text following a -semicolon until end of line) -.PP -Then comes zero or more (but usually at least 2) indented lines -representing\&... -.SS Postings -.PP -A posting is an addition of some amount to, or removal of some amount -from, an account. -Each posting line begins with at least one space or tab (2 or 4 spaces -is common), followed by: -.IP \[bu] 2 -(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]), -followed by a space -.IP \[bu] 2 -(required) an account name (any text, optionally containing \f[B]single -spaces\f[], until end of line or a double space) -.IP \[bu] 2 -(optional) \f[B]two or more spaces\f[] or tabs followed by an amount. -.PP -Positive amounts are being added to the account, negative amounts are -being removed. -.PP -The amounts within a transaction must always sum up to zero. -As a convenience, one amount may be left blank; it will be inferred so -as to balance the transaction. -.PP -Be sure to note the unusual two\-space delimiter between account name -and amount. -This makes it easy to write account names containing spaces. -But if you accidentally leave only one space (or tab) before the amount, -the amount will be considered part of the account name. -.SS Dates -.SS Simple dates -.PP -Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D) -Leading zeros are optional. -The year may be omitted, in which case it will be inferred from the -context \- the current transaction, the default year set with a default -year directive, or the current date when the command is run. -Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[], -\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[]. -.SS Secondary dates -.PP -Real\-life transactions sometimes involve more than one date \- eg the -date you write a cheque, and the date it clears in your bank. -When you want to model this, eg for more accurate balances, you can -specify individual posting dates, which I recommend. -Or, you can use the secondary dates (aka auxiliary/effective dates) -feature, supported for compatibility with Ledger. -.PP -A secondary date can be written after the primary date, separated by an -equals sign. -The primary date, on the left, is used by default; the secondary date, -on the right, is used when the \f[C]\-\-date2\f[] flag is specified -(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work). -.PP -The meaning of secondary dates is up to you, but it's best to follow a -consistent rule. -Eg write the bank's clearing date as primary, and when needed, the date -the transaction was initiated as secondary. -.PP -Here's an example. -Note that a secondary date will use the year of the primary date if -unspecified. -.IP -.nf -\f[C] -2010/2/23=2/19\ movie\ ticket -\ \ expenses:cinema\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10 -\ \ assets:checking -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ register\ checking -2010/02/23\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10 -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ register\ checking\ \-\-date2 -2010/02/19\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10 -\f[] -.fi -.PP -Secondary dates require some effort; you must use them consistently in -your journal entries and remember whether to use or not use the -\f[C]\-\-date2\f[] flag for your reports. -They are included in hledger for Ledger compatibility, but posting dates -are a more powerful and less confusing alternative. -.SS Posting dates -.PP -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like \f[C]date:DATE\f[]. -This is probably the best way to control posting dates precisely. -Eg in this example the expense should appear in May reports, and the -deduction from checking should be reported on 6/1 for easy bank -reconciliation: -.IP -.nf -\f[C] -2015/5/30 -\ \ \ \ expenses:food\ \ \ \ \ $10\ \ \ ;\ food\ purchased\ on\ saturday\ 5/30 -\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ ;\ bank\ cleared\ it\ on\ monday,\ date:6/1 -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ register\ food -2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10 -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.j\ register\ checking -2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10 -\f[] -.fi -.PP -DATE should be a simple date; if the year is not specified it will use -the year of the transaction's date. -You can set the secondary date similarly, with \f[C]date2:DATE2\f[]. -The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date -value if they are present, eg a \f[C]date:\f[] tag with no value is not -allowed. -.PP -Ledger's earlier, more compact bracketed date syntax is also supported: -\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]. -hledger will attempt to parse any square\-bracketed sequence of the -\f[C]0123456789/\-.=\f[] characters in this way. -With this syntax, DATE infers its year from the transaction and DATE2 -infers its year from DATE. -.SS Status -.PP -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: -.PP -.TS -tab(@); -l l. -T{ -mark \ -T}@T{ -status -T} -_ -T{ -\ -T}@T{ -unmarked -T} -T{ -\f[C]!\f[] -T}@T{ -pending -T} -T{ -\f[C]*\f[] -T}@T{ -cleared -T} -.TE -.PP -When reporting, you can filter by status with the -\f[C]\-U/\-\-unmarked\f[], \f[C]\-P/\-\-pending\f[], and -\f[C]\-C/\-\-cleared\f[] flags; or the \f[C]status:\f[], -\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in -hledger\-ui. -.PP -Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq] -state is called \[lq]uncleared\[rq]. -As of hledger 1.3 we have renamed it to unmarked for clarity. -.PP -To replicate Ledger and old hledger's behaviour of also matching -pending, combine \-U and \-P. -.PP -Status marks are optional, but can be helpful eg for reconciling with -real\-world accounts. -Some editor modes provide highlighting and shortcuts for working with -status. -Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c -C\-e, or posting status with C\-c C\-c. -.PP -What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq] -actually mean is up to you. -Here's one suggestion: -.PP -.TS -tab(@); -lw(9.9n) lw(60.1n). -T{ -status -T}@T{ -meaning -T} -_ -T{ -uncleared -T}@T{ -recorded but not yet reconciled; needs review -T} -T{ -pending -T}@T{ -tentatively reconciled (if needed, eg during a big reconciliation) -T} -T{ -cleared -T}@T{ -complete, reconciled as far as possible, and considered correct -T} -.TE -.PP -With this scheme, you would use \f[C]\-PC\f[] to see the current balance -at your bank, \f[C]\-U\f[] to see things which will probably hit your -bank soon (like uncashed checks), and no flags to see the most -up\-to\-date state of your finances. -.SS Description -.PP -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). -Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it -can be used for whatever you wish, or left blank. -Transaction descriptions can be queried, unlike comments. -.SS Payee and note -.PP -You can optionally include a \f[C]|\f[] (pipe) character in a -description to subdivide it into a payee/payer name on the left and -additional notes on the right. -This may be worthwhile if you need to do more precise querying and -pivoting by payee. -.SS Account names -.PP -Account names typically have several parts separated by a full colon, -from which hledger derives a hierarchical chart of accounts. -They can be anything you like, but in finance there are traditionally -five top\-level accounts: \f[C]assets\f[], \f[C]liabilities\f[], -\f[C]income\f[], \f[C]expenses\f[], and \f[C]equity\f[]. -.PP -Account names may contain single spaces, eg: -\f[C]assets:accounts\ receivable\f[]. -Because of this, they must always be followed by \f[B]two or more -spaces\f[] (or newline). -.PP -Account names can be aliased. -.SS Amounts -.PP -After the account name, there is usually an amount. -Important: between account name and amount, there must be \f[B]two or -more spaces\f[]. -.PP -Amounts consist of a number and (usually) a currency symbol or commodity -name. -Some examples: -.PP -\f[C]2.00001\f[] -.PD 0 -.P -.PD -\f[C]$1\f[] -.PD 0 -.P -.PD -\f[C]4000\ AAPL\f[] -.PD 0 -.P -.PD -\f[C]3\ "green\ apples"\f[] -.PD 0 -.P -.PD -\f[C]\-$1,000,000.00\f[] -.PD 0 -.P -.PD -\f[C]INR\ 9,99,99,999.00\f[] -.PD 0 -.P -.PD -\f[C]EUR\ \-2.000.000,00\f[] -.PD 0 -.P -.PD -\f[C]1\ 999\ 999.9455\f[] -.PP -As you can see, the amount format is somewhat flexible: -.IP \[bu] 2 -amounts are a number (the \[lq]quantity\[rq]) and optionally a currency -symbol/commodity name (the \[lq]commodity\[rq]). -.IP \[bu] 2 -the commodity is a symbol, word, or phrase, on the left or right, with -or without a separating space. -If the commodity contains numbers, spaces or non\-word punctuation it -must be enclosed in double quotes. -.IP \[bu] 2 -negative amounts with a commodity on the left can have the minus sign -before or after it -.IP \[bu] 2 -digit groups (thousands, or any other grouping) can be separated by -space or comma or period and should be used as separator between all -groups -.IP \[bu] 2 -decimal part can be separated by comma or period and should be different -from digit groups separator -.PP -You can use any of these variations when recording data. -However, there is some ambiguous way of representing numbers like -\f[C]$1.000\f[] and \f[C]$1,000\f[] both may mean either one thousand or -one dollar. -By default hledger will assume that this is sole delimiter is used only -for decimals. -On the other hand commodity format declared prior to that line will help -to resolve that ambiguity differently: -.IP -.nf -\f[C] -commodity\ $1,000.00 - -2017/12/25\ New\ life\ of\ Scrooge -\ \ \ \ expenses:gifts\ \ $1,000 -\ \ \ \ assets -\f[] -.fi -.PP -Though journal may contain mixed styles to represent amount, when -hledger displays amounts, it will choose a consistent format for each -commodity. -(Except for price amounts, which are always formatted as written). -The display format is chosen as follows: -.IP \[bu] 2 -if there is a commodity directive specifying the format, that is used -.IP \[bu] 2 -otherwise the format is inferred from the first posting amount in that -commodity in the journal, and the precision (number of decimal places) -will be the maximum from all posting amounts in that commmodity -.IP \[bu] 2 -or if there are no such amounts in the journal, a default format is used -(like \f[C]$1000.00\f[]). -.PP -Price amounts and amounts in D directives usually don't affect amount -format inference, but in some situations they can do so indirectly. -(Eg when D's default commodity is applied to a commodity\-less amount, -or when an amountless posting is balanced using a price's commodity, or -when \-V is used.) If you find this causing problems, set the desired -format with a commodity directive. -.SS Virtual Postings -.PP -When you parenthesise the account name in a posting, we call that a -\f[I]virtual posting\f[], which means: -.IP \[bu] 2 -it is ignored when checking that the transaction is balanced -.IP \[bu] 2 -it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used, -or the \f[C]real:1\f[] query. -.PP -You could use this, eg, to set an account's opening balance without -needing to use the \f[C]equity:opening\ balances\f[] account: -.IP -.nf -\f[C] -1/1\ special\ unbalanced\ posting\ to\ set\ initial\ balance -\ \ (assets:checking)\ \ \ $1000 -\f[] -.fi -.PP -When the account name is bracketed, we call it a \f[I]balanced virtual -posting\f[]. -This is like an ordinary virtual posting except the balanced virtual -postings in a transaction must balance to 0, like the real postings (but -separately from them). -Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or -\f[C]real:1\f[]. -.IP -.nf -\f[C] -1/1\ buy\ food\ with\ cash,\ and\ update\ some\ budget\-tracking\ subaccounts\ elsewhere -\ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10 -\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10 -\ \ [assets:checking:available]\ \ \ \ \ $10 -\ \ [assets:checking:budget:food]\ \ $\-10 -\f[] -.fi -.PP -Virtual postings have some legitimate uses, but those are few. -You can usually find an equivalent journal entry using real postings, -which is more correct and provides better error checking. -.SS Balance Assertions -.PP -hledger supports Ledger\-style balance assertions in journal files. -These look like \f[C]=EXPECTEDBALANCE\f[] following a posting's amount. -Eg in this example we assert the expected dollar balance in accounts a -and b after each posting: -.IP -.nf -\f[C] -2013/1/1 -\ \ a\ \ \ $1\ \ =$1 -\ \ b\ \ \ \ \ \ \ =$\-1 - -2013/1/2 -\ \ a\ \ \ $1\ \ =$2 -\ \ b\ \ $\-1\ \ =$\-2 -\f[] -.fi -.PP -After reading a journal file, hledger will check all balance assertions -and report an error if any of them fail. -Balance assertions can protect you from, eg, inadvertently disrupting -reconciled balances while cleaning up old entries. -You can disable them temporarily with the -\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for -troubleshooting or for reading Ledger files. -.SS Assertions and ordering -.PP -hledger sorts an account's postings and assertions first by date and -then (for postings on the same day) by parse order. -Note this is different from Ledger, which sorts assertions only by parse -order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) -.PP -So, hledger balance assertions keep working if you reorder -differently\-dated transactions within the journal. -But if you reorder same\-dated transactions or postings, assertions -might break and require updating. -This order dependence does bring an advantage: precise control over the -order of postings and assertions within a day, so you can assert -intra\-day balances. -.SS Assertions and included files -.PP -With included files, things are a little more complicated. -Including preserves the ordering of postings and assertions. -If you have multiple postings to an account on the same day, split -across different files, and you also want to assert the account's -balance on the same day, you'll have to put the assertion in the right -file. -.SS Assertions and multiple \-f options -.PP -Balance assertions don't work well across files specified with multiple -\-f options. -Use include or concatenate the files instead. -.SS Assertions and commodities -.PP -The asserted balance must be a simple single\-commodity amount, and in -fact the assertion checks only this commodity's balance within the -(possibly multi\-commodity) account balance. -We could call this a partial balance assertion. -This is compatible with Ledger, and makes it possible to make assertions -about accounts containing multiple commodities. -.PP -To assert each commodity's balance in such a multi\-commodity account, -you can add multiple postings (with amount 0 if necessary). -But note that no matter how many assertions you add, you can't be sure -the account does not contain some unexpected commodity. -(We'll add support for this kind of total balance assertion if there's -demand.) -.SS Assertions and subaccounts -.PP -Balance assertions do not count the balance from subaccounts; they check -the posted account's exclusive balance. -For example: -.IP -.nf -\f[C] -1/1 -\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1 -\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1 -\ \ equity -\f[] -.fi -.PP -The balance report's flat mode shows these exclusive balances more -clearly: -.IP -.nf -\f[C] -$\ hledger\ bal\ checking\ \-\-flat -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2 -\f[] -.fi -.SS Assertions and virtual postings -.PP -Balance assertions are checked against all postings, both real and -virtual. -They are not affected by the \f[C]\-\-real/\-R\f[] flag or -\f[C]real:\f[] query. -.SS Balance Assignments -.PP -Ledger\-style balance assignments are also supported. -These are like balance assertions, but with no posting amount on the -left side of the equals sign; instead it is calculated automatically so -as to satisfy the assertion. -This can be a convenience during data entry, eg when setting opening -balances: -.IP -.nf -\f[C] -;\ starting\ a\ new\ journal,\ set\ asset\ account\ balances\ -2016/1/1\ opening\ balances -\ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ =\ $409.32 -\ \ assets:savings\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $735.24 -\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ =\ $42 -\ \ equity:opening\ balances -\f[] -.fi -.PP -or when adjusting a balance to reality: -.IP -.nf -\f[C] -;\ no\ cash\ left;\ update\ balance,\ record\ any\ untracked\ spending\ as\ a\ generic\ expense -2016/1/15 -\ \ assets:cash\ \ \ \ =\ $0 -\ \ expenses:misc -\f[] -.fi -.PP -The calculated amount depends on the account's balance in the commodity -at that point (which depends on the previously\-dated postings of the -commodity to that account since the last balance assertion or -assignment). -Note that using balance assignments makes your journal a little less -explicit; to know the exact amount posted, you have to run hledger or do -the calculations yourself, instead of just reading it. -.SS Prices -.SS Transaction prices -.PP -Within a transaction, you can note an amount's price in another -commodity. -This can be used to document the cost (in a purchase) or selling price -(in a sale). -For example, transaction prices are useful to record purchases of a -foreign currency. -.PP -Transaction prices are fixed, and do not change over time. -(Ledger users: Ledger uses a different syntax for fixed prices, -\f[C]{=UNITPRICE}\f[], which hledger currently ignores). -.PP -There are several ways to record a transaction price: -.IP "1." 3 -Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount: -.RS 4 -.IP -.nf -\f[C] -2009/1/1 -\ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each -\ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00 -\f[] -.fi -.RE -.IP "2." 3 -Write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: -.RS 4 -.IP -.nf -\f[C] -2009/1/1 -\ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot -\ \ assets:dollars -\f[] -.fi -.RE -.IP "3." 3 -Specify amounts for all postings, using exactly two commodities, and let -hledger infer the price that balances the transaction: -.RS 4 -.IP -.nf -\f[C] -2009/1/1 -\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased -\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135 -\f[] -.fi -.RE -.PP -Amounts with transaction prices can be displayed in the transaction -price's commodity by using the \f[C]\-B/\-\-cost\f[] flag (except for -#551) (\[lq]B\[rq] is from \[lq]cost Basis\[rq]). -Eg for the above, here is how \-B affects the balance report: -.IP -.nf -\f[C] -$\ hledger\ bal\ \-N\ \-\-flat -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros -$\ hledger\ bal\ \-N\ \-\-flat\ \-B -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost -\f[] -.fi -.PP -Note \-B is sensitive to the order of postings when a transaction price -is inferred: the inferred price will be in the commodity of the last -amount. -So if example 3's postings are reversed, while the transaction is -equivalent, \-B shows something different: -.IP -.nf -\f[C] -2009/1/1 -\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ 135\ dollars\ sold -\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ for\ 100\ euros -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ bal\ \-N\ \-\-flat\ \-B -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €\-100\ \ assets:dollars\ \ #\ <\-\ the\ dollars\[aq]\ selling\ price -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros -\f[] -.fi -.SS Market prices -.PP -Market prices are not tied to a particular transaction; they represent -historical exchange rates between two commodities. -(Ledger calls them historical prices.) For example, the prices published -by a stock exchange or the foreign exchange market. -hledger can use these prices to show the market value of things at a -given date, see market value. -.PP -To record market prices, use P directives in the main journal or in an -included file. -Their format is: -.IP -.nf -\f[C] -P\ DATE\ COMMODITYBEINGPRICED\ UNITPRICE -\f[] -.fi -.PP -DATE is a simple date as usual. -COMMODITYBEINGPRICED is the symbol of the commodity being priced. -UNITPRICE is an ordinary amount (symbol and quantity) in a second -commodity, specifying the unit price or conversion rate for the first -commodity in terms of the second, on the given date. -.PP -For example, the following directives say that one euro was worth 1.35 -US dollars during 2009, and $1.40 from 2010 onward: -.IP -.nf -\f[C] -P\ 2009/1/1\ €\ $1.35 -P\ 2010/1/1\ €\ $1.40 -\f[] -.fi -.SS Comments -.PP -Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash -(\f[C]#\f[]) or star (\f[C]*\f[]) are comments, and will be ignored. -(Star comments cause org\-mode nodes to be ignored, allowing emacs users -to fold and navigate their journals with org\-mode or orgstruct\-mode.) -.PP -Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[] -directives is a (multi\-line) comment. -If there is no \f[C]end\ comment\f[], the comment extends to the end of -the file. -.PP -You can attach comments to a transaction by writing them after the -description and/or indented on the following lines (before the -postings). -Similarly, you can attach comments to an individual posting by writing -them after the amount and/or indented on the following lines. -Transaction and posting comments must begin with a semicolon -(\f[C];\f[]). -.PP -Some examples: -.IP -.nf -\f[C] -#\ a\ file\ comment - -;\ also\ a\ file\ comment - -comment -This\ is\ a\ multiline\ file\ comment, -which\ continues\ until\ a\ line -where\ the\ "end\ comment"\ string -appears\ on\ its\ own\ (or\ end\ of\ file). -end\ comment - -2012/5/14\ something\ \ ;\ a\ transaction\ comment -\ \ \ \ ;\ the\ transaction\ comment,\ continued -\ \ \ \ posting1\ \ 1\ \ ;\ a\ comment\ for\ posting\ 1 -\ \ \ \ posting2 -\ \ \ \ ;\ a\ comment\ for\ posting\ 2 -\ \ \ \ ;\ another\ comment\ line\ for\ posting\ 2 -;\ a\ file\ comment\ (because\ not\ indented) -\f[] -.fi -.SS Tags -.PP -Tags are a way to add extra labels or labelled data to postings and -transactions, which you can then search or pivot on. -.PP -A simple tag is a word (which may contain hyphens) followed by a full -colon, written inside a transaction or posting comment line: -.IP -.nf -\f[C] -2017/1/16\ bought\ groceries\ \ \ \ ;\ sometag: -\f[] -.fi -.PP -Tags can have a value, which is the text after the colon, up to the next -comma or end of line, with leading/trailing whitespace removed: -.IP -.nf -\f[C] -\ \ \ \ expenses:food\ \ \ \ $10\ \ \ ;\ a\-posting\-tag:\ the\ tag\ value -\f[] -.fi -.PP -Note this means hledger's tag values can not contain commas or newlines. -Ending at commas means you can write multiple short tags on one line, -comma separated: -.IP -.nf -\f[C] -\ \ \ \ assets:checking\ \ \ \ \ \ \ ;\ a\ comment\ containing\ tag1:,\ tag2:\ some\ value\ ... -\f[] -.fi -.PP -Here, -.IP \[bu] 2 -\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a -tag -.IP \[bu] 2 -\[lq]\f[C]tag1\f[]\[rq] is a tag with no value -.IP \[bu] 2 -\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is -\[lq]\f[C]some\ value\ ...\f[]\[rq] -.PP -Tags in a transaction comment affect the transaction and all of its -postings, while tags in a posting comment affect only that posting. -For example, the following transaction has three tags (\f[C]A\f[], -\f[C]TAG2\f[], \f[C]third\-tag\f[]) and the posting has four (those plus -\f[C]posting\-tag\f[]): -.IP -.nf -\f[C] -1/1\ a\ transaction\ \ ;\ A:,\ TAG2: -\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ <\-\ with\ a\ value -\ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag: -\f[] -.fi -.PP -Tags are like Ledger's metadata feature, except hledger's tag values are -simple strings. -.SS Directives -.SS Account aliases -.PP -You can define aliases which rewrite your account names (after reading -the journal, before generating reports). -hledger's account aliases can be useful for: -.IP \[bu] 2 -expanding shorthand account names to their full form, allowing easier -data entry and a less verbose journal -.IP \[bu] 2 -adapting old journals to your current chart of accounts -.IP \[bu] 2 -experimenting with new account organisations, like a new hierarchy or -combining two accounts into one -.IP \[bu] 2 -customising reports -.PP -See also Cookbook: rewrite account names. -.SS Basic aliases -.PP -To set an account alias, use the \f[C]alias\f[] directive in your -journal file. -This affects all subsequent journal entries in the current file or its -included files. -The spaces around the = are optional: -.IP -.nf -\f[C] -alias\ OLD\ =\ NEW -\f[] -.fi -.PP -Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the -command line. -This affects all entries. -It's useful for trying out aliases interactively. -.PP -OLD and NEW are full account names. -hledger will replace any occurrence of the old account name with the new -one. -Subaccounts are also affected. -Eg: -.IP -.nf -\f[C] -alias\ checking\ =\ assets:bank:wells\ fargo:checking -#\ rewrites\ "checking"\ to\ "assets:bank:wells\ fargo:checking",\ or\ "checking:a"\ to\ "assets:bank:wells\ fargo:checking:a" -\f[] -.fi -.SS Regex aliases -.PP -There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes: -.IP -.nf -\f[C] -alias\ /REGEX/\ =\ REPLACEMENT -\f[] -.fi -.PP -or \f[C]\-\-alias\ \[aq]/REGEX/=REPLACEMENT\[aq]\f[]. -.PP -REGEX is a case\-insensitive regular expression. -Anywhere it matches inside an account name, the matched part will be -replaced by REPLACEMENT. -If REGEX contains parenthesised match groups, these can be referenced by -the usual numeric backreferences in REPLACEMENT. -Eg: -.IP -.nf -\f[C] -alias\ /^(.+):bank:([^:]+)(.*)/\ =\ \\1:\\2\ \\3 -#\ rewrites\ "assets:bank:wells\ fargo:checking"\ to\ \ "assets:wells\ fargo\ checking" -\f[] -.fi -.PP -Also note that REPLACEMENT continues to the end of line (or on command -line, to end of option argument), so it can contain trailing whitespace. -.SS Multiple aliases -.PP -You can define as many aliases as you like using directives or -command\-line options. -Aliases are recursive \- each alias sees the result of applying previous -ones. -(This is different from Ledger, where aliases are non\-recursive by -default). -Aliases are applied in the following order: -.IP "1." 3 -alias directives, most recently seen first (recent directives take -precedence over earlier ones; directives not yet seen are ignored) -.IP "2." 3 -alias options, in the order they appear on the command line -.SS end aliases -.PP -You can clear (forget) all currently defined aliases with the -\f[C]end\ aliases\f[] directive: -.IP -.nf -\f[C] -end\ aliases -\f[] -.fi -.SS account directive -.PP -The \f[C]account\f[] directive predefines account names, as in Ledger -and Beancount. -This may be useful for your own documentation; hledger doesn't make use -of it yet. -.IP -.nf -\f[C] -;\ account\ ACCT -;\ \ \ OPTIONAL\ COMMENTS/TAGS... - -account\ assets:bank:checking -\ a\ comment -\ acct\-no:12345 - -account\ expenses:food - -;\ etc. -\f[] -.fi -.SS apply account directive -.PP -You can specify a parent account which will be prepended to all accounts -within a section of the journal. -Use the \f[C]apply\ account\f[] and \f[C]end\ apply\ account\f[] -directives like so: -.IP -.nf -\f[C] -apply\ account\ home - -2010/1/1 -\ \ \ \ food\ \ \ \ $10 -\ \ \ \ cash - -end\ apply\ account -\f[] -.fi -.PP -which is equivalent to: -.IP -.nf -\f[C] -2010/01/01 -\ \ \ \ home:food\ \ \ \ \ \ \ \ \ \ \ $10 -\ \ \ \ home:cash\ \ \ \ \ \ \ \ \ \ $\-10 -\f[] -.fi -.PP -If \f[C]end\ apply\ account\f[] is omitted, the effect lasts to the end -of the file. -Included files are also affected, eg: -.IP -.nf -\f[C] -apply\ account\ business -include\ biz.journal -end\ apply\ account -apply\ account\ personal -include\ personal.journal -\f[] -.fi -.PP -Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings -were also supported. -.SS Multi\-line comments -.PP -A line containing just \f[C]comment\f[] starts a multi\-line comment, -and a line containing just \f[C]end\ comment\f[] ends it. -See comments. -.SS commodity directive -.PP -The \f[C]commodity\f[] directive predefines commodities (currently this -is just informational), and also it may define the display format for -amounts in this commodity (overriding the automatically inferred -format). -.PP -It may be written on a single line, like this: -.IP -.nf -\f[C] -;\ commodity\ EXAMPLEAMOUNT - -;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated, -;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and -;\ separating\ thousands\ with\ comma. -commodity\ 1,000.0000\ AAAA -\f[] -.fi -.PP -or on multiple lines, using the \[lq]format\[rq] subdirective. -In this case the commodity symbol appears twice and should be the same -in both places: -.IP -.nf -\f[C] -;\ commodity\ SYMBOL -;\ \ \ format\ EXAMPLEAMOUNT - -;\ display\ indian\ rupees\ with\ currency\ name\ on\ the\ left, -;\ thousands,\ lakhs\ and\ crores\ comma\-separated, -;\ period\ as\ decimal\ point,\ and\ two\ decimal\ places. -commodity\ INR -\ \ format\ INR\ 9,99,99,999.00 -\f[] -.fi -.SS Default commodity -.PP -The D directive sets a default commodity (and display format), to be -used for amounts without a commodity symbol (ie, plain numbers). -(Note this differs from Ledger's default commodity directive.) The -commodity and display format will be applied to all subsequent -commodity\-less amounts, or until the next D directive. -.IP -.nf -\f[C] -#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars -#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places) -D\ $1,000.00 - -1/1 -\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1 -\ \ b -\f[] -.fi -.SS Default year -.PP -You can set a default year to be used for subsequent dates which don't -specify a year. -This is a line beginning with \f[C]Y\f[] followed by the year. -Eg: -.IP -.nf -\f[C] -Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009 - -12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15 -\ \ expenses\ \ 1 -\ \ assets - -Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010 - -2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected -\ \ expenses\ \ 1 -\ \ assets - -1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31 -\ \ expenses\ \ 1 -\ \ assets -\f[] -.fi -.SS Including other files -.PP -You can pull in the content of additional journal files by writing an -include directive, like this: -.IP -.nf -\f[C] -include\ path/to/file.journal -\f[] -.fi -.PP -If the path does not begin with a slash, it is relative to the current -file. -Glob patterns (\f[C]*\f[]) are not currently supported. -.PP -The \f[C]include\f[] directive can only be used in journal files. -It can include journal, timeclock or timedot files, but not CSV files. -.SH Periodic transactions -.PP -A periodic transaction starts with a tilde `~' in place of a date -followed by a period expression: -.IP -.nf -\f[C] -~\ weekly -\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck -\ \ income:acme\ inc -\f[] -.fi -.PP -Periodic transactions are used for forecasting and budgeting only, they -have no effect unless the \f[C]\-\-forecast\f[] or \f[C]\-\-budget\f[] -flag is used. -With \f[C]\-\-forecast\f[], each periodic transaction rule generates -recurring forecast transactions at the specified interval, beginning the -day after the last recorded journal transaction and ending 6 months from -today, or at the specified report end date. -With \f[C]balance\ \-\-budget\f[], each periodic transaction declares -recurring budget goals for one or more accounts. -.PD 0 -.P -.PD -For more details, see: balance > Budgeting, Budgeting and Forecasting. -.SH Automated posting rules -.PP -Automated posting rule starts with an equal sign `=' in place of a date, -followed by a query: -.IP -.nf -\f[C] -=\ expenses:gifts -\ \ \ \ budget:gifts\ \ *\-1 -\ \ \ \ assets:budget\ \ *1 -\f[] -.fi -.PP -When \f[C]\-\-auto\f[] option is specified on the command line, -automated posting rule will add its postings to all transactions that -match the query. -.PP -If amount in the automated posting rule includes commodity name, new -posting will be made in the given commodity, otherwise commodity of the -matched transaction will be used. -.PP -When amount in the automated posting rule begins with the '*', amount -will be treated as a multiplier that is applied to the amount of the -first posting in the matched transaction. -.PP -In example above, every transaction in \f[C]expenses:gifts\f[] account -will have two additional postings added to it: amount of the original -gift will be debited from \f[C]budget:gifts\f[] and credited into -\f[C]assets:budget\f[]: -.IP -.nf -\f[C] -;\ Original\ transaction -2017\-12\-14 -\ \ expenses:gifts\ \ $20 -\ \ assets - -;\ With\ automated\ postings\ applied -2017/12/14 -\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20 -\ \ \ \ assets -\ \ \ \ budget:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20 -\ \ \ \ assets:budget\ \ \ \ \ \ \ \ \ \ \ \ \ \ $20 -\f[] -.fi -.SH EDITOR SUPPORT -.PP -Add\-on modes exist for various text editors, to make working with -journal files easier. -They add colour, navigation aids and helpful commands. -For hledger users who edit the journal file directly (the majority), -using one of these modes is quite recommended. -.PP -These were written with Ledger in mind, but also work with hledger -files: -.PP -.TS -tab(@); -lw(16.5n) lw(53.5n). -T{ -Emacs -T}@T{ -http://www.ledger\-cli.org/3.0/doc/ledger\-mode.html -T} -T{ -Vim -T}@T{ -https://github.com/ledger/ledger/wiki/Getting\-started -T} -T{ -Sublime Text -T}@T{ -https://github.com/ledger/ledger/wiki/Using\-Sublime\-Text -T} -T{ -Textmate -T}@T{ -https://github.com/ledger/ledger/wiki/Using\-TextMate\-2 -T} -T{ -Text Wrangler \ -T}@T{ -https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-TextWrangler -T} -T{ -Visual Studio Code -T}@T{ -https://marketplace.visualstudio.com/items?itemName=mark\-hansen.hledger\-vscode -T} -.TE - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger_journal.info b/.otherdocs/hledger_journal.info deleted file mode 100644 --- a/.otherdocs/hledger_journal.info +++ /dev/null @@ -1,1235 +0,0 @@ -This is hledger_journal.info, produced by makeinfo version 6.5 from -stdin. - - -File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) - -hledger_journal(5) hledger 1.5 -****************************** - -hledger's usual data source is a plain text file containing journal -entries in hledger journal format. This file represents a standard -accounting general journal. I use file names ending in '.journal', but -that's not required. The journal file contains a number of transaction -entries, each describing a transfer of money (or any commodity) between -two or more named accounts, in a simple format readable by both hledger -and humans. - - hledger's journal format is a compatible subset, mostly, of ledger's -journal format, so hledger can work with compatible ledger journal files -as well. It's safe, and encouraged, to run both hledger and ledger on -the same journal file, eg to validate the results you're getting. - - You can use hledger without learning any more about this file; just -use the add or web commands to create and update it. Many users, -though, also edit the journal file directly with a text editor, perhaps -assisted by the helper modes for emacs or vim. - - Here's an example: - -; A sample journal file. This is a comment. - -2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description - assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name - income:salary $-1 ; followed by at least two spaces and an amount - -2008/06/01 gift - assets:bank:checking $1 ; <- at least two postings in a transaction - income:gifts $-1 ; <- their amounts must balance to 0 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred - -2008/06/03 eat & shop ; <- description can be anything - expenses:food $1 - expenses:supplies $1 ; <- this transaction debits two expense accounts - assets:cash ; <- $-2 inferred - -2008/10/01 take a loan - assets:bank:checking $1 - liabilities:debts $-1 - -2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) - liabilities:debts $1 - assets:bank:checking - -* Menu: - -* FILE FORMAT:: -* Periodic transactions:: -* Automated posting rules:: -* EDITOR SUPPORT:: - - -File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top - -1 FILE FORMAT -************* - -* Menu: - -* Transactions:: -* Postings:: -* Dates:: -* Status:: -* Description:: -* Account names:: -* Amounts:: -* Virtual Postings:: -* Balance Assertions:: -* Balance Assignments:: -* Prices:: -* Comments:: -* Tags:: -* Directives:: - - -File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT - -1.1 Transactions -================ - -Transactions are movements of some quantity of commodities between named -accounts. Each transaction is represented by a journal entry beginning -with a simple date in column 0. This can be followed by any of the -following, separated by spaces: - - * (optional) a status character (empty, '!', or '*') - * (optional) a transaction code (any short number or text, enclosed - in parentheses) - * (optional) a transaction description (any remaining text until end - of line or a semicolon) - * (optional) a transaction comment (any remaining text following a - semicolon until end of line) - - Then comes zero or more (but usually at least 2) indented lines -representing... - - -File: hledger_journal.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT - -1.2 Postings -============ - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - * (optional) a status character (empty, '!', or '*'), followed by a - space - * (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - * (optional) *two or more spaces* or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are -being removed. - - The amounts within a transaction must always sum up to zero. As a -convenience, one amount may be left blank; it will be inferred so as to -balance the transaction. - - Be sure to note the unusual two-space delimiter between account name -and amount. This makes it easy to write account names containing -spaces. But if you accidentally leave only one space (or tab) before -the amount, the amount will be considered part of the account name. - - -File: hledger_journal.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT - -1.3 Dates -========= - -* Menu: - -* Simple dates:: -* Secondary dates:: -* Posting dates:: - - -File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: Dates - -1.3.1 Simple dates ------------------- - -Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) -Leading zeros are optional. The year may be omitted, in which case it -will be inferred from the context - the current transaction, the default -year set with a default year directive, or the current date when the -command is run. Some examples: '2010/01/31', '1/31', '2010-01-31', -'2010.1.31'. - - -File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates - -1.3.2 Secondary dates ---------------------- - -Real-life transactions sometimes involve more than one date - eg the -date you write a cheque, and the date it clears in your bank. When you -want to model this, eg for more accurate balances, you can specify -individual posting dates, which I recommend. Or, you can use the -secondary dates (aka auxiliary/effective dates) feature, supported for -compatibility with Ledger. - - A secondary date can be written after the primary date, separated by -an equals sign. The primary date, on the left, is used by default; the -secondary date, on the right, is used when the '--date2' flag is -specified ('--aux-date' or '--effective' also work). - - The meaning of secondary dates is up to you, but it's best to follow -a consistent rule. Eg write the bank's clearing date as primary, and -when needed, the date the transaction was initiated as secondary. - - Here's an example. Note that a secondary date will use the year of -the primary date if unspecified. - -2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking - -$ hledger register checking -2010/02/23 movie ticket assets:checking $-10 $-10 - -$ hledger register checking --date2 -2010/02/19 movie ticket assets:checking $-10 $-10 - - Secondary dates require some effort; you must use them consistently -in your journal entries and remember whether to use or not use the -'--date2' flag for your reports. They are included in hledger for -Ledger compatibility, but posting dates are a more powerful and less -confusing alternative. - - -File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: Dates - -1.3.3 Posting dates -------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like 'date:DATE'. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015/05/30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015/06/01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction's date. You can set the secondary date -similarly, with 'date2:DATE2'. The 'date:' or 'date2:' tags must have a -valid simple date value if they are present, eg a 'date:' tag with no -value is not allowed. - - Ledger's earlier, more compact bracketed date syntax is also -supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'. hledger will attempt -to parse any square-bracketed sequence of the '0123456789/-.=' -characters in this way. With this syntax, DATE infers its year from the -transaction and DATE2 infers its year from DATE. - - -File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: FILE FORMAT - -1.4 Status -========== - -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: - -mark status - ------------------ - unmarked -'!' pending -'*' cleared - - When reporting, you can filter by status with the '-U/--unmarked', -'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', -and 'status:*' queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" -state is called "uncleared". As of hledger 1.3 we have renamed it to -unmarked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching -pending, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. Some editor modes provide highlighting and -shortcuts for working with status. Eg in Emacs ledger-mode, you can -toggle transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to -you. Here's one suggestion: - -status meaning --------------------------------------------------------------------------- -uncleared recorded but not yet reconciled; needs review -pending tentatively reconciled (if needed, eg during a big - reconciliation) -cleared complete, reconciled as far as possible, and considered - correct - - With this scheme, you would use '-PC' to see the current balance at -your bank, '-U' to see things which will probably hit your bank soon -(like uncashed checks), and no flags to see the most up-to-date state of -your finances. - - -File: hledger_journal.info, Node: Description, Next: Account names, Prev: Status, Up: FILE FORMAT - -1.5 Description -=============== - -A transaction's description is the rest of the line following the date -and status mark (or until a comment begins). Sometimes called the -"narration" in traditional bookkeeping, it can be used for whatever you -wish, or left blank. Transaction descriptions can be queried, unlike -comments. -* Menu: - -* Payee and note:: - - -File: hledger_journal.info, Node: Payee and note, Up: Description - -1.5.1 Payee and note --------------------- - -You can optionally include a '|' (pipe) character in a description to -subdivide it into a payee/payer name on the left and additional notes on -the right. This may be worthwhile if you need to do more precise -querying and pivoting by payee. - - -File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT - -1.6 Account names -================= - -Account names typically have several parts separated by a full colon, -from which hledger derives a hierarchical chart of accounts. They can -be anything you like, but in finance there are traditionally five -top-level accounts: 'assets', 'liabilities', 'income', 'expenses', and -'equity'. - - Account names may contain single spaces, eg: 'assets:accounts -receivable'. Because of this, they must always be followed by *two or -more spaces* (or newline). - - Account names can be aliased. - - -File: hledger_journal.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT - -1.7 Amounts -=========== - -After the account name, there is usually an amount. Important: between -account name and amount, there must be *two or more spaces*. - - Amounts consist of a number and (usually) a currency symbol or -commodity name. Some examples: - - '2.00001' -'$1' -'4000 AAPL' -'3 "green apples"' -'-$1,000,000.00' -'INR 9,99,99,999.00' -'EUR -2.000.000,00' -'1 999 999.9455' - - As you can see, the amount format is somewhat flexible: - - * amounts are a number (the "quantity") and optionally a currency - symbol/commodity name (the "commodity"). - * the commodity is a symbol, word, or phrase, on the left or right, - with or without a separating space. If the commodity contains - numbers, spaces or non-word punctuation it must be enclosed in - double quotes. - * negative amounts with a commodity on the left can have the minus - sign before or after it - * digit groups (thousands, or any other grouping) can be separated by - space or comma or period and should be used as separator between - all groups - * decimal part can be separated by comma or period and should be - different from digit groups separator - - You can use any of these variations when recording data. However, -there is some ambiguous way of representing numbers like '$1.000' and -'$1,000' both may mean either one thousand or one dollar. By default -hledger will assume that this is sole delimiter is used only for -decimals. On the other hand commodity format declared prior to that -line will help to resolve that ambiguity differently: - -commodity $1,000.00 - -2017/12/25 New life of Scrooge - expenses:gifts $1,000 - assets - - Though journal may contain mixed styles to represent amount, when -hledger displays amounts, it will choose a consistent format for each -commodity. (Except for price amounts, which are always formatted as -written). The display format is chosen as follows: - - * if there is a commodity directive specifying the format, that is - used - * otherwise the format is inferred from the first posting amount in - that commodity in the journal, and the precision (number of decimal - places) will be the maximum from all posting amounts in that - commmodity - * or if there are no such amounts in the journal, a default format is - used (like '$1000.00'). - - Price amounts and amounts in D directives usually don't affect amount -format inference, but in some situations they can do so indirectly. (Eg -when D's default commodity is applied to a commodity-less amount, or -when an amountless posting is balanced using a price's commodity, or -when -V is used.) If you find this causing problems, set the desired -format with a commodity directive. - - -File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT - -1.8 Virtual Postings -==================== - -When you parenthesise the account name in a posting, we call that a -_virtual posting_, which means: - - * it is ignored when checking that the transaction is balanced - * it is excluded from reports when the '--real/-R' flag is used, or - the 'real:1' query. - - You could use this, eg, to set an account's opening balance without -needing to use the 'equity:opening balances' account: - -1/1 special unbalanced posting to set initial balance - (assets:checking) $1000 - - When the account name is bracketed, we call it a _balanced virtual -posting_. This is like an ordinary virtual posting except the balanced -virtual postings in a transaction must balance to 0, like the real -postings (but separately from them). Balanced virtual postings are also -excluded by '--real/-R' or 'real:1'. - -1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere - expenses:food $10 - assets:cash $-10 - [assets:checking:available] $10 - [assets:checking:budget:food] $-10 - - Virtual postings have some legitimate uses, but those are few. You -can usually find an equivalent journal entry using real postings, which -is more correct and provides better error checking. - - -File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT - -1.9 Balance Assertions -====================== - -hledger supports Ledger-style balance assertions in journal files. -These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in -this example we assert the expected dollar balance in accounts a and b -after each posting: - -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the '--ignore-assertions' flag, which can be useful for troubleshooting -or for reading Ledger files. -* Menu: - -* Assertions and ordering:: -* Assertions and included files:: -* Assertions and multiple -f options:: -* Assertions and commodities:: -* Assertions and subaccounts:: -* Assertions and virtual postings:: - - -File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions - -1.9.1 Assertions and ordering ------------------------------ - -hledger sorts an account's postings and assertions first by date and -then (for postings on the same day) by parse order. Note this is -different from Ledger, which sorts assertions only by parse order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder -differently-dated transactions within the journal. But if you reorder -same-dated transactions or postings, assertions might break and require -updating. This order dependence does bring an advantage: precise -control over the order of postings and assertions within a day, so you -can assert intra-day balances. - - -File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions - -1.9.2 Assertions and included files ------------------------------------ - -With included files, things are a little more complicated. Including -preserves the ordering of postings and assertions. If you have multiple -postings to an account on the same day, split across different files, -and you also want to assert the account's balance on the same day, -you'll have to put the assertion in the right file. - - -File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions - -1.9.3 Assertions and multiple -f options ----------------------------------------- - -Balance assertions don't work well across files specified with multiple --f options. Use include or concatenate the files instead. - - -File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and multiple -f options, Up: Balance Assertions - -1.9.4 Assertions and commodities --------------------------------- - -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity's balance within the -(possibly multi-commodity) account balance. We could call this a -partial balance assertion. This is compatible with Ledger, and makes it -possible to make assertions about accounts containing multiple -commodities. - - To assert each commodity's balance in such a multi-commodity account, -you can add multiple postings (with amount 0 if necessary). But note -that no matter how many assertions you add, you can't be sure the -account does not contain some unexpected commodity. (We'll add support -for this kind of total balance assertion if there's demand.) - - -File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions - -1.9.5 Assertions and subaccounts --------------------------------- - -Balance assertions do not count the balance from subaccounts; they check -the posted account's exclusive balance. For example: - -1/1 - checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 - checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 - equity - - The balance report's flat mode shows these exclusive balances more -clearly: - -$ hledger bal checking --flat - 1 checking - 1 checking:fund --------------------- - 2 - - -File: hledger_journal.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions - -1.9.6 Assertions and virtual postings -------------------------------------- - -Balance assertions are checked against all postings, both real and -virtual. They are not affected by the '--real/-R' flag or 'real:' -query. - - -File: hledger_journal.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT - -1.10 Balance Assignments -======================== - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). Note that using balance assignments makes your journal a -little less explicit; to know the exact amount posted, you have to run -hledger or do the calculations yourself, instead of just reading it. - - -File: hledger_journal.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT - -1.11 Prices -=========== - -* Menu: - -* Transaction prices:: -* Market prices:: - - -File: hledger_journal.info, Node: Transaction prices, Next: Market prices, Up: Prices - -1.11.1 Transaction prices -------------------------- - -Within a transaction, you can note an amount's price in another -commodity. This can be used to document the cost (in a purchase) or -selling price (in a sale). For example, transaction prices are useful -to record purchases of a foreign currency. - - Transaction prices are fixed, and do not change over time. (Ledger -users: Ledger uses a different syntax for fixed prices, '{=UNITPRICE}', -which hledger currently ignores). - - There are several ways to record a transaction price: - - 1. Write the price per unit, as '@ UNITPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as '@@ TOTALPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts with transaction prices can be displayed in the transaction -price's commodity by using the '-B/--cost' flag (except for #551) ("B" -is from "cost Basis"). Eg for the above, here is how -B affects the -balance report: - -$ hledger bal -N --flat - $-135 assets:dollars - €100 assets:euros -$ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction -price is inferred: the inferred price will be in the commodity of the -last amount. So if example 3's postings are reversed, while the -transaction is equivalent, -B shows something different: - -2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros €100 ; for 100 euros - -$ hledger bal -N --flat -B - €-100 assets:dollars # <- the dollars' selling price - €100 assets:euros - - -File: hledger_journal.info, Node: Market prices, Prev: Transaction prices, Up: Prices - -1.11.2 Market prices --------------------- - -Market prices are not tied to a particular transaction; they represent -historical exchange rates between two commodities. (Ledger calls them -historical prices.) For example, the prices published by a stock -exchange or the foreign exchange market. hledger can use these prices -to show the market value of things at a given date, see market value. - - To record market prices, use P directives in the main journal or in -an included file. Their format is: - -P DATE COMMODITYBEINGPRICED UNITPRICE - - DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol -of the commodity being priced. UNITPRICE is an ordinary amount (symbol -and quantity) in a second commodity, specifying the unit price or -conversion rate for the first commodity in terms of the second, on the -given date. - - For example, the following directives say that one euro was worth -1.35 US dollars during 2009, and $1.40 from 2010 onward: - -P 2009/1/1 € $1.35 -P 2010/1/1 € $1.40 - - -File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT - -1.12 Comments -============= - -Lines in the journal beginning with a semicolon (';') or hash ('#') or -star ('*') are comments, and will be ignored. (Star comments cause -org-mode nodes to be ignored, allowing emacs users to fold and navigate -their journals with org-mode or orgstruct-mode.) - - Also, anything between 'comment' and 'end comment' directives is a -(multi-line) comment. If there is no 'end comment', the comment extends -to the end of the file. - - You can attach comments to a transaction by writing them after the -description and/or indented on the following lines (before the -postings). Similarly, you can attach comments to an individual posting -by writing them after the amount and/or indented on the following lines. -Transaction and posting comments must begin with a semicolon (';'). - - Some examples: - -# a file comment - -; also a file comment - -comment -This is a multiline file comment, -which continues until a line -where the "end comment" string -appears on its own (or end of file). -end comment - -2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 -; a file comment (because not indented) - - -File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT - -1.13 Tags -========= - -Tags are a way to add extra labels or labelled data to postings and -transactions, which you can then search or pivot on. - - A simple tag is a word (which may contain hyphens) followed by a full -colon, written inside a transaction or posting comment line: - -2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the -next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or -newlines. Ending at commas means you can write multiple short tags on -one line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - * "'a comment containing'" is just comment text, not a tag - * "'tag1'" is a tag with no value - * "'tag2'" is another tag, whose value is "'some value ...'" - - Tags in a transaction comment affect the transaction and all of its -postings, while tags in a posting comment affect only that posting. For -example, the following transaction has three tags ('A', 'TAG2', -'third-tag') and the posting has four (those plus 'posting-tag'): - -1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values -are simple strings. - - -File: hledger_journal.info, Node: Directives, Prev: Tags, Up: FILE FORMAT - -1.14 Directives -=============== - -* Menu: - -* Account aliases:: -* account directive:: -* apply account directive:: -* Multi-line comments:: -* commodity directive:: -* Default commodity:: -* Default year:: -* Including other files:: - - -File: hledger_journal.info, Node: Account aliases, Next: account directive, Up: Directives - -1.14.1 Account aliases ----------------------- - -You can define aliases which rewrite your account names (after reading -the journal, before generating reports). hledger's account aliases can -be useful for: - - * expanding shorthand account names to their full form, allowing - easier data entry and a less verbose journal - * adapting old journals to your current chart of accounts - * experimenting with new account organisations, like a new hierarchy - or combining two accounts into one - * customising reports - - See also Cookbook: rewrite account names. -* Menu: - -* Basic aliases:: -* Regex aliases:: -* Multiple aliases:: -* end aliases:: - - -File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases - -1.14.1.1 Basic aliases -...................... - -To set an account alias, use the 'alias' directive in your journal file. -This affects all subsequent journal entries in the current file or its -included files. The spaces around the = are optional: - -alias OLD = NEW - - Or, you can use the '--alias 'OLD=NEW'' option on the command line. -This affects all entries. It's useful for trying out aliases -interactively. - - OLD and NEW are full account names. hledger will replace any -occurrence of the old account name with the new one. Subaccounts are -also affected. Eg: - -alias checking = assets:bank:wells fargo:checking -# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - -File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases - -1.14.1.2 Regex aliases -...................... - -There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes: - -alias /REGEX/ = REPLACEMENT - - or '--alias '/REGEX/=REPLACEMENT''. - - REGEX is a case-insensitive regular expression. Anywhere it matches -inside an account name, the matched part will be replaced by -REPLACEMENT. If REGEX contains parenthesised match groups, these can be -referenced by the usual numeric backreferences in REPLACEMENT. Eg: - -alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 -# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - Also note that REPLACEMENT continues to the end of line (or on -command line, to end of option argument), so it can contain trailing -whitespace. - - -File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases - -1.14.1.3 Multiple aliases -......................... - -You can define as many aliases as you like using directives or -command-line options. Aliases are recursive - each alias sees the -result of applying previous ones. (This is different from Ledger, where -aliases are non-recursive by default). Aliases are applied in the -following order: - - 1. alias directives, most recently seen first (recent directives take - precedence over earlier ones; directives not yet seen are ignored) - 2. alias options, in the order they appear on the command line - - -File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases - -1.14.1.4 end aliases -.................... - -You can clear (forget) all currently defined aliases with the 'end -aliases' directive: - -end aliases - - -File: hledger_journal.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives - -1.14.2 account directive ------------------------- - -The 'account' directive predefines account names, as in Ledger and -Beancount. This may be useful for your own documentation; hledger -doesn't make use of it yet. - -; account ACCT -; OPTIONAL COMMENTS/TAGS... - -account assets:bank:checking - a comment - acct-no:12345 - -account expenses:food - -; etc. - - -File: hledger_journal.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives - -1.14.3 apply account directive ------------------------------- - -You can specify a parent account which will be prepended to all accounts -within a section of the journal. Use the 'apply account' and 'end apply -account' directives like so: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - which is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - If 'end apply account' is omitted, the effect lasts to the end of the -file. Included files are also affected, eg: - -apply account business -include biz.journal -end apply account -apply account personal -include personal.journal - - Prior to hledger 1.0, legacy 'account' and 'end' spellings were also -supported. - - -File: hledger_journal.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives - -1.14.4 Multi-line comments --------------------------- - -A line containing just 'comment' starts a multi-line comment, and a line -containing just 'end comment' ends it. See comments. - - -File: hledger_journal.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives - -1.14.5 commodity directive --------------------------- - -The 'commodity' directive predefines commodities (currently this is just -informational), and also it may define the display format for amounts in -this commodity (overriding the automatically inferred format). - - It may be written on a single line, like this: - -; commodity EXAMPLEAMOUNT - -; display AAAA amounts with the symbol on the right, space-separated, -; using period as decimal point, with four decimal places, and -; separating thousands with comma. -commodity 1,000.0000 AAAA - - or on multiple lines, using the "format" subdirective. In this case -the commodity symbol appears twice and should be the same in both -places: - -; commodity SYMBOL -; format EXAMPLEAMOUNT - -; display indian rupees with currency name on the left, -; thousands, lakhs and crores comma-separated, -; period as decimal point, and two decimal places. -commodity INR - format INR 9,99,99,999.00 - - -File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives - -1.14.6 Default commodity ------------------------- - -The D directive sets a default commodity (and display format), to be -used for amounts without a commodity symbol (ie, plain numbers). (Note -this differs from Ledger's default commodity directive.) The commodity -and display format will be applied to all subsequent commodity-less -amounts, or until the next D directive. - -# commodity-less amounts should be treated as dollars -# (and displayed with symbol on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, becomes $1 - b - - -File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives - -1.14.7 Default year -------------------- - -You can set a default year to be used for subsequent dates which don't -specify a year. This is a line beginning with 'Y' followed by the year. -Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -Y2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - -File: hledger_journal.info, Node: Including other files, Prev: Default year, Up: Directives - -1.14.8 Including other files ----------------------------- - -You can pull in the content of additional journal files by writing an -include directive, like this: - -include path/to/file.journal - - If the path does not begin with a slash, it is relative to the -current file. Glob patterns ('*') are not currently supported. - - The 'include' directive can only be used in journal files. It can -include journal, timeclock or timedot files, but not CSV files. - - -File: hledger_journal.info, Node: Periodic transactions, Next: Automated posting rules, Prev: FILE FORMAT, Up: Top - -2 Periodic transactions -*********************** - -A periodic transaction starts with a tilde '~' in place of a date -followed by a period expression: - -~ weekly - assets:bank:checking $400 ; paycheck - income:acme inc - - Periodic transactions are used for forecasting and budgeting only, -they have no effect unless the '--forecast' or '--budget' flag is used. -With '--forecast', each periodic transaction rule generates recurring -forecast transactions at the specified interval, beginning the day after -the last recorded journal transaction and ending 6 months from today, or -at the specified report end date. With 'balance --budget', each -periodic transaction declares recurring budget goals for one or more -accounts. -For more details, see: balance > Budgeting, Budgeting and Forecasting. - - -File: hledger_journal.info, Node: Automated posting rules, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top - -3 Automated posting rules -************************* - -Automated posting rule starts with an equal sign '=' in place of a date, -followed by a query: - -= expenses:gifts - budget:gifts *-1 - assets:budget *1 - - When '--auto' option is specified on the command line, automated -posting rule will add its postings to all transactions that match the -query. - - If amount in the automated posting rule includes commodity name, new -posting will be made in the given commodity, otherwise commodity of the -matched transaction will be used. - - When amount in the automated posting rule begins with the '*', amount -will be treated as a multiplier that is applied to the amount of the -first posting in the matched transaction. - - In example above, every transaction in 'expenses:gifts' account will -have two additional postings added to it: amount of the original gift -will be debited from 'budget:gifts' and credited into 'assets:budget': - -; Original transaction -2017-12-14 - expenses:gifts $20 - assets - -; With automated postings applied -2017/12/14 - expenses:gifts $20 - assets - budget:gifts $-20 - assets:budget $20 - - -File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated posting rules, Up: Top - -4 EDITOR SUPPORT -**************** - -Add-on modes exist for various text editors, to make working with -journal files easier. They add colour, navigation aids and helpful -commands. For hledger users who edit the journal file directly (the -majority), using one of these modes is quite recommended. - - These were written with Ledger in mind, but also work with hledger -files: - -Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html -Vim https://github.com/ledger/ledger/wiki/Getting-started -Sublime Text https://github.com/ledger/ledger/wiki/Using-Sublime-Text -Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 -Text Wrangler https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-TextWrangler -Visual Studio https://marketplace.visualstudio.com/items?itemName=mark-hansen.hledger-vscode -Code - - -Tag Table: -Node: Top76 -Node: FILE FORMAT2424 -Ref: #file-format2555 -Node: Transactions2778 -Ref: #transactions2899 -Node: Postings3583 -Ref: #postings3710 -Node: Dates4705 -Ref: #dates4820 -Node: Simple dates4885 -Ref: #simple-dates5011 -Node: Secondary dates5377 -Ref: #secondary-dates5531 -Node: Posting dates7094 -Ref: #posting-dates7223 -Node: Status8597 -Ref: #status8717 -Node: Description10425 -Ref: #description10563 -Node: Payee and note10882 -Ref: #payee-and-note10996 -Node: Account names11238 -Ref: #account-names11381 -Node: Amounts11868 -Ref: #amounts12004 -Node: Virtual Postings14684 -Ref: #virtual-postings14843 -Node: Balance Assertions16063 -Ref: #balance-assertions16238 -Node: Assertions and ordering17134 -Ref: #assertions-and-ordering17320 -Node: Assertions and included files18020 -Ref: #assertions-and-included-files18261 -Node: Assertions and multiple -f options18594 -Ref: #assertions-and-multiple--f-options18848 -Node: Assertions and commodities18980 -Ref: #assertions-and-commodities19215 -Node: Assertions and subaccounts19911 -Ref: #assertions-and-subaccounts20143 -Node: Assertions and virtual postings20664 -Ref: #assertions-and-virtual-postings20871 -Node: Balance Assignments21013 -Ref: #balance-assignments21182 -Node: Prices22302 -Ref: #prices22435 -Node: Transaction prices22486 -Ref: #transaction-prices22631 -Node: Market prices24787 -Ref: #market-prices24922 -Node: Comments25882 -Ref: #comments26004 -Node: Tags27246 -Ref: #tags27364 -Node: Directives28766 -Ref: #directives28879 -Node: Account aliases29072 -Ref: #account-aliases29216 -Node: Basic aliases29820 -Ref: #basic-aliases29963 -Node: Regex aliases30653 -Ref: #regex-aliases30821 -Node: Multiple aliases31539 -Ref: #multiple-aliases31711 -Node: end aliases32209 -Ref: #end-aliases32349 -Node: account directive32450 -Ref: #account-directive32630 -Node: apply account directive32926 -Ref: #apply-account-directive33122 -Node: Multi-line comments33781 -Ref: #multi-line-comments33971 -Node: commodity directive34099 -Ref: #commodity-directive34283 -Node: Default commodity35155 -Ref: #default-commodity35328 -Node: Default year35865 -Ref: #default-year36030 -Node: Including other files36453 -Ref: #including-other-files36610 -Node: Periodic transactions37007 -Ref: #periodic-transactions37178 -Node: Automated posting rules37921 -Ref: #automated-posting-rules38099 -Node: EDITOR SUPPORT39208 -Ref: #editor-support39338 - -End Tag Table diff --git a/.otherdocs/hledger_journal.txt b/.otherdocs/hledger_journal.txt deleted file mode 100644 --- a/.otherdocs/hledger_journal.txt +++ /dev/null @@ -1,918 +0,0 @@ - -hledger_journal(5) hledger User Manuals hledger_journal(5) - - - -NAME - Journal - hledger's default file format, representing a General Journal - -DESCRIPTION - hledger's usual data source is a plain text file containing journal - entries in hledger journal format. This file represents a standard - accounting general journal. I use file names ending in .journal, but - that's not required. The journal file contains a number of transaction - entries, each describing a transfer of money (or any commodity) between - two or more named accounts, in a simple format readable by both hledger - and humans. - - hledger's journal format is a compatible subset, mostly, of ledger's - journal format, so hledger can work with compatible ledger journal - files as well. It's safe, and encouraged, to run both hledger and - ledger on the same journal file, eg to validate the results you're get- - ting. - - You can use hledger without learning any more about this file; just use - the add or web commands to create and update it. Many users, though, - also edit the journal file directly with a text editor, perhaps - assisted by the helper modes for emacs or vim. - - Here's an example: - - ; A sample journal file. This is a comment. - - 2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description - assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name - income:salary $-1 ; followed by at least two spaces and an amount - - 2008/06/01 gift - assets:bank:checking $1 ; <- at least two postings in a transaction - income:gifts $-1 ; <- their amounts must balance to 0 - - 2008/06/02 save - assets:bank:saving $1 - assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred - - 2008/06/03 eat & shop ; <- description can be anything - expenses:food $1 - expenses:supplies $1 ; <- this transaction debits two expense accounts - assets:cash ; <- $-2 inferred - - 2008/10/01 take a loan - assets:bank:checking $1 - liabilities:debts $-1 - - 2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) - liabilities:debts $1 - assets:bank:checking - -FILE FORMAT - Transactions - Transactions are movements of some quantity of commodities between - named accounts. Each transaction is represented by a journal entry - beginning with a simple date in column 0. This can be followed by any - of the following, separated by spaces: - - o (optional) a status character (empty, !, or *) - - o (optional) a transaction code (any short number or text, enclosed in - parentheses) - - o (optional) a transaction description (any remaining text until end of - line or a semicolon) - - o (optional) a transaction comment (any remaining text following a - semicolon until end of line) - - Then comes zero or more (but usually at least 2) indented lines repre- - senting... - - Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or - tab (2 or 4 spaces is common), followed by: - - o (optional) a status character (empty, !, or *), followed by a space - - o (required) an account name (any text, optionally containing single - spaces, until end of line or a double space) - - o (optional) two or more spaces or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are - being removed. - - The amounts within a transaction must always sum up to zero. As a con- - venience, one amount may be left blank; it will be inferred so as to - balance the transaction. - - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing spa- - ces. But if you accidentally leave only one space (or tab) before the - amount, the amount will be considered part of the account name. - - Dates - Simple dates - Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) - Leading zeros are optional. The year may be omitted, in which case it - will be inferred from the context - the current transaction, the - default year set with a default year directive, or the current date - when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, - 2010.1.31. - - Secondary dates - Real-life transactions sometimes involve more than one date - eg the - date you write a cheque, and the date it clears in your bank. When you - want to model this, eg for more accurate balances, you can specify - individual posting dates, which I recommend. Or, you can use the sec- - ondary dates (aka auxiliary/effective dates) feature, supported for - compatibility with Ledger. - - A secondary date can be written after the primary date, separated by an - equals sign. The primary date, on the left, is used by default; the - secondary date, on the right, is used when the --date2 flag is speci- - fied (--aux-date or --effective also work). - - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg write the bank's clearing date as primary, and - when needed, the date the transaction was initiated as secondary. - - Here's an example. Note that a secondary date will use the year of the - primary date if unspecified. - - 2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking - - $ hledger register checking - 2010/02/23 movie ticket assets:checking $-10 $-10 - - $ hledger register checking --date2 - 2010/02/19 movie ticket assets:checking $-10 $-10 - - Secondary dates require some effort; you must use them consistently in - your journal entries and remember whether to use or not use the --date2 - flag for your reports. They are included in hledger for Ledger compat- - ibility, but posting dates are a more powerful and less confusing - alternative. - - Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) - like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May - reports, and the deduction from checking should be reported on 6/1 for - easy bank reconciliation: - - 2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - - $ hledger -f t.j register food - 2015/05/30 expenses:food $10 $10 - - $ hledger -f t.j register checking - 2015/06/01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will use - the year of the transaction's date. You can set the secondary date - similarly, with date2:DATE2. The date: or date2: tags must have a - valid simple date value if they are present, eg a date: tag with no - value is not allowed. - - Ledger's earlier, more compact bracketed date syntax is also supported: - [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any - square-bracketed sequence of the 0123456789/-.= characters in this way. - With this syntax, DATE infers its year from the transaction and DATE2 - infers its year from DATE. - - Status - Transactions, or individual postings within a transaction, can have a - status mark, which is a single character before the transaction - description or posting account name, separated from it by a space, - indicating one of three statuses: - - - mark status - ------------------ - unmarked - ! pending - * cleared - - When reporting, you can filter by status with the -U/--unmarked, - -P/--pending, and -C/--cleared flags; or the status:, status:!, and - status:* queries; or the U, P, C keys in hledger-ui. - - Note, in Ledger and in older versions of hledger, the "unmarked" state - is called "uncleared". As of hledger 1.3 we have renamed it to - unmarked for clarity. - - To replicate Ledger and old hledger's behaviour of also matching pend- - ing, combine -U and -P. - - Status marks are optional, but can be helpful eg for reconciling with - real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle - transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to you. - Here's one suggestion: - - - status meaning - -------------------------------------------------------------------------- - uncleared recorded but not yet reconciled; needs review - pending tentatively reconciled (if needed, eg during a big reconcil- - iation) - cleared complete, reconciled as far as possible, and considered cor- - rect - - With this scheme, you would use -PC to see the current balance at your - bank, -U to see things which will probably hit your bank soon (like - uncashed checks), and no flags to see the most up-to-date state of your - finances. - - Description - A transaction's description is the rest of the line following the date - and status mark (or until a comment begins). Sometimes called the - "narration" in traditional bookkeeping, it can be used for whatever you - wish, or left blank. Transaction descriptions can be queried, unlike - comments. - - Payee and note - You can optionally include a | (pipe) character in a description to - subdivide it into a payee/payer name on the left and additional notes - on the right. This may be worthwhile if you need to do more precise - querying and pivoting by payee. - - Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five - top-level accounts: assets, liabilities, income, expenses, and equity. - - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more - spaces (or newline). - - Account names can be aliased. - - Amounts - After the account name, there is usually an amount. Important: between - account name and amount, there must be two or more spaces. - - Amounts consist of a number and (usually) a currency symbol or commod- - ity name. Some examples: - - 2.00001 - $1 - 4000 AAPL - 3 "green apples" - -$1,000,000.00 - INR 9,99,99,999.00 - EUR -2.000.000,00 - 1 999 999.9455 - - As you can see, the amount format is somewhat flexible: - - o amounts are a number (the "quantity") and optionally a currency sym- - bol/commodity name (the "commodity"). - - o the commodity is a symbol, word, or phrase, on the left or right, - with or without a separating space. If the commodity contains num- - bers, spaces or non-word punctuation it must be enclosed in double - quotes. - - o negative amounts with a commodity on the left can have the minus sign - before or after it - - o digit groups (thousands, or any other grouping) can be separated by - space or comma or period and should be used as separator between all - groups - - o decimal part can be separated by comma or period and should be dif- - ferent from digit groups separator - - You can use any of these variations when recording data. However, - there is some ambiguous way of representing numbers like $1.000 and - $1,000 both may mean either one thousand or one dollar. By default - hledger will assume that this is sole delimiter is used only for deci- - mals. On the other hand commodity format declared prior to that line - will help to resolve that ambiguity differently: - - commodity $1,000.00 - - 2017/12/25 New life of Scrooge - expenses:gifts $1,000 - assets - - Though journal may contain mixed styles to represent amount, when - hledger displays amounts, it will choose a consistent format for each - commodity. (Except for price amounts, which are always formatted as - written). The display format is chosen as follows: - - o if there is a commodity directive specifying the format, that is used - - o otherwise the format is inferred from the first posting amount in - that commodity in the journal, and the precision (number of decimal - places) will be the maximum from all posting amounts in that commmod- - ity - - o or if there are no such amounts in the journal, a default format is - used (like $1000.00). - - Price amounts and amounts in D directives usually don't affect amount - format inference, but in some situations they can do so indirectly. - (Eg when D's default commodity is applied to a commodity-less amount, - or when an amountless posting is balanced using a price's commodity, or - when -V is used.) If you find this causing problems, set the desired - format with a commodity directive. - - Virtual Postings - When you parenthesise the account name in a posting, we call that a - virtual posting, which means: - - o it is ignored when checking that the transaction is balanced - - o it is excluded from reports when the --real/-R flag is used, or the - real:1 query. - - You could use this, eg, to set an account's opening balance without - needing to use the equity:opening balances account: - - 1/1 special unbalanced posting to set initial balance - (assets:checking) $1000 - - When the account name is bracketed, we call it a balanced virtual post- - ing. This is like an ordinary virtual posting except the balanced vir- - tual postings in a transaction must balance to 0, like the real post- - ings (but separately from them). Balanced virtual postings are also - excluded by --real/-R or real:1. - - 1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere - expenses:food $10 - assets:cash $-10 - [assets:checking:available] $10 - [assets:checking:budget:food] $-10 - - Virtual postings have some legitimate uses, but those are few. You can - usually find an equivalent journal entry using real postings, which is - more correct and provides better error checking. - - Balance Assertions - hledger supports Ledger-style balance assertions in journal files. - These look like =EXPECTEDBALANCE following a posting's amount. Eg in - this example we assert the expected dollar balance in accounts a and b - after each posting: - - 2013/1/1 - a $1 =$1 - b =$-1 - - 2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the - --ignore-assertions flag, which can be useful for troubleshooting or - for reading Ledger files. - - Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- - ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- - ings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder differ- - ently-dated transactions within the journal. But if you reorder - same-dated transactions or postings, assertions might break and require - updating. This order dependence does bring an advantage: precise con- - trol over the order of postings and assertions within a day, so you can - assert intra-day balances. - - Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - ple postings to an account on the same day, split across different - files, and you also want to assert the account's balance on the same - day, you'll have to put the assertion in the right file. - - Assertions and multiple -f options - Balance assertions don't work well across files specified with multiple - -f options. Use include or concatenate the files instead. - - Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the - (possibly multi-commodity) account balance. We could call this a par- - tial balance assertion. This is compatible with Ledger, and makes it - possible to make assertions about accounts containing multiple commodi- - ties. - - To assert each commodity's balance in such a multi-commodity account, - you can add multiple postings (with amount 0 if necessary). But note - that no matter how many assertions you add, you can't be sure the - account does not contain some unexpected commodity. (We'll add support - for this kind of total balance assertion if there's demand.) - - Assertions and subaccounts - Balance assertions do not count the balance from subaccounts; they - check the posted account's exclusive balance. For example: - - 1/1 - checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 - checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 - equity - - The balance report's flat mode shows these exclusive balances more - clearly: - - $ hledger bal checking --flat - 1 checking - 1 checking:fund - -------------------- - 2 - - Assertions and virtual postings - Balance assertions are checked against all postings, both real and vir- - tual. They are not affected by the --real/-R flag or real: query. - - Balance Assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when - setting opening balances: - - ; starting a new journal, set asset account balances - 2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - - ; no cash left; update balance, record any untracked spending as a generic expense - 2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- - ment). Note that using balance assignments makes your journal a little - less explicit; to know the exact amount posted, you have to run hledger - or do the calculations yourself, instead of just reading it. - - Prices - Transaction prices - Within a transaction, you can note an amount's price in another commod- - ity. This can be used to document the cost (in a purchase) or selling - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. - - Transaction prices are fixed, and do not change over time. (Ledger - users: Ledger uses a different syntax for fixed prices, {=UNITPRICE}, - which hledger currently ignores). - - There are several ways to record a transaction price: - - 1. Write the price per unit, as @ UNITPRICE after the amount: - - 2009/1/1 - assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as @@ TOTALPRICE after the amount: - - 2009/1/1 - assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, and - let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros 100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts with transaction prices can be displayed in the transaction - price's commodity by using the -B/--cost flag (except for #551) ("B" is - from "cost Basis"). Eg for the above, here is how -B affects the bal- - ance report: - - $ hledger bal -N --flat - $-135 assets:dollars - 100 assets:euros - $ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last - amount. So if example 3's postings are reversed, while the transaction - is equivalent, -B shows something different: - - 2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros 100 ; for 100 euros - - $ hledger bal -N --flat -B - -100 assets:dollars # <- the dollars' selling price - 100 assets:euros - - Market prices - Market prices are not tied to a particular transaction; they represent - historical exchange rates between two commodities. (Ledger calls them - historical prices.) For example, the prices published by a stock - exchange or the foreign exchange market. hledger can use these prices - to show the market value of things at a given date, see market value. - - To record market prices, use P directives in the main journal or in an - included file. Their format is: - - P DATE COMMODITYBEINGPRICED UNITPRICE - - DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of - the commodity being priced. UNITPRICE is an ordinary amount (symbol - and quantity) in a second commodity, specifying the unit price or con- - version rate for the first commodity in terms of the second, on the - given date. - - For example, the following directives say that one euro was worth 1.35 - US dollars during 2009, and $1.40 from 2010 onward: - - P 2009/1/1 $1.35 - P 2010/1/1 $1.40 - - Comments - Lines in the journal beginning with a semicolon (;) or hash (#) or star - (*) are comments, and will be ignored. (Star comments cause org-mode - nodes to be ignored, allowing emacs users to fold and navigate their - journals with org-mode or orgstruct-mode.) - - Also, anything between comment and end comment directives is a - (multi-line) comment. If there is no end comment, the comment extends - to the end of the file. - - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. - Transaction and posting comments must begin with a semicolon (;). - - Some examples: - - # a file comment - - ; also a file comment - - comment - This is a multiline file comment, - which continues until a line - where the "end comment" string - appears on its own (or end of file). - end comment - - 2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 - ; a file comment (because not indented) - - Tags - Tags are a way to add extra labels or labelled data to postings and - transactions, which you can then search or pivot on. - - A simple tag is a word (which may contain hyphens) followed by a full - colon, written inside a transaction or posting comment line: - - 2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the - next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or new- - lines. Ending at commas means you can write multiple short tags on one - line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - o "a comment containing" is just comment text, not a tag - - o "tag1" is a tag with no value - - o "tag2" is another tag, whose value is "some value ..." - - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, - third-tag) and the posting has four (those plus posting-tag): - - 1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values - are simple strings. - - Directives - Account aliases - You can define aliases which rewrite your account names (after reading - the journal, before generating reports). hledger's account aliases can - be useful for: - - o expanding shorthand account names to their full form, allowing easier - data entry and a less verbose journal - - o adapting old journals to your current chart of accounts - - o experimenting with new account organisations, like a new hierarchy or - combining two accounts into one - - o customising reports - - See also Cookbook: rewrite account names. - - Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its - included files. The spaces around the = are optional: - - alias OLD = NEW - - Or, you can use the --alias 'OLD=NEW' option on the command line. This - affects all entries. It's useful for trying out aliases interactively. - - OLD and NEW are full account names. hledger will replace any occur- - rence of the old account name with the new one. Subaccounts are also - affected. Eg: - - alias checking = assets:bank:wells fargo:checking - # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - Regex aliases - There is also a more powerful variant that uses a regular expression, - indicated by the forward slashes: - - alias /REGEX/ = REPLACEMENT - - or --alias '/REGEX/=REPLACEMENT'. - - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- - erenced by the usual numeric backreferences in REPLACEMENT. Eg: - - alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 - # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - Also note that REPLACEMENT continues to the end of line (or on command - line, to end of option argument), so it can contain trailing white- - space. - - Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where - aliases are non-recursive by default). Aliases are applied in the fol- - lowing order: - - 1. alias directives, most recently seen first (recent directives take - precedence over earlier ones; directives not yet seen are ignored) - - 2. alias options, in the order they appear on the command line - - end aliases - You can clear (forget) all currently defined aliases with the - end aliases directive: - - end aliases - - account directive - The account directive predefines account names, as in Ledger and Bean- - count. This may be useful for your own documentation; hledger doesn't - make use of it yet. - - ; account ACCT - ; OPTIONAL COMMENTS/TAGS... - - account assets:bank:checking - a comment - acct-no:12345 - - account expenses:food - - ; etc. - - apply account directive - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and - end apply account directives like so: - - apply account home - - 2010/1/1 - food $10 - cash - - end apply account - - which is equivalent to: - - 2010/01/01 - home:food $10 - home:cash $-10 - - If end apply account is omitted, the effect lasts to the end of the - file. Included files are also affected, eg: - - apply account business - include biz.journal - end apply account - apply account personal - include personal.journal - - Prior to hledger 1.0, legacy account and end spellings were also sup- - ported. - - Multi-line comments - A line containing just comment starts a multi-line comment, and a line - containing just end comment ends it. See comments. - - commodity directive - The commodity directive predefines commodities (currently this is just - informational), and also it may define the display format for amounts - in this commodity (overriding the automatically inferred format). - - It may be written on a single line, like this: - - ; commodity EXAMPLEAMOUNT - - ; display AAAA amounts with the symbol on the right, space-separated, - ; using period as decimal point, with four decimal places, and - ; separating thousands with comma. - commodity 1,000.0000 AAAA - - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both - places: - - ; commodity SYMBOL - ; format EXAMPLEAMOUNT - - ; display indian rupees with currency name on the left, - ; thousands, lakhs and crores comma-separated, - ; period as decimal point, and two decimal places. - commodity INR - format INR 9,99,99,999.00 - - Default commodity - The D directive sets a default commodity (and display format), to be - used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less - amounts, or until the next D directive. - - # commodity-less amounts should be treated as dollars - # (and displayed with symbol on the left, thousands separators and two decimal places) - D $1,000.00 - - 1/1 - a 5 ; <- commodity-less amount, becomes $1 - b - - Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. - Eg: - - Y2009 ; set default year to 2009 - - 12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - - Y2010 ; change default year to 2010 - - 2009/1/30 ; specifies the year, not affected - expenses 1 - assets - - 1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Including other files - You can pull in the content of additional journal files by writing an - include directive, like this: - - include path/to/file.journal - - If the path does not begin with a slash, it is relative to the current - file. Glob patterns (*) are not currently supported. - - The include directive can only be used in journal files. It can - include journal, timeclock or timedot files, but not CSV files. - -Periodic transactions - A periodic transaction starts with a tilde `~' in place of a date fol- - lowed by a period expression: - - ~ weekly - assets:bank:checking $400 ; paycheck - income:acme inc - - Periodic transactions are used for forecasting and budgeting only, they - have no effect unless the --forecast or --budget flag is used. With - --forecast, each periodic transaction rule generates recurring forecast - transactions at the specified interval, beginning the day after the - last recorded journal transaction and ending 6 months from today, or at - the specified report end date. With balance --budget, each periodic - transaction declares recurring budget goals for one or more accounts. - For more details, see: balance > Budgeting, Budgeting and Forecasting. - -Automated posting rules - Automated posting rule starts with an equal sign `=' in place of a - date, followed by a query: - - = expenses:gifts - budget:gifts *-1 - assets:budget *1 - - When --auto option is specified on the command line, automated posting - rule will add its postings to all transactions that match the query. - - If amount in the automated posting rule includes commodity name, new - posting will be made in the given commodity, otherwise commodity of the - matched transaction will be used. - - When amount in the automated posting rule begins with the '*', amount - will be treated as a multiplier that is applied to the amount of the - first posting in the matched transaction. - - In example above, every transaction in expenses:gifts account will have - two additional postings added to it: amount of the original gift will - be debited from budget:gifts and credited into assets:budget: - - ; Original transaction - 2017-12-14 - expenses:gifts $20 - assets - - ; With automated postings applied - 2017/12/14 - expenses:gifts $20 - assets - budget:gifts $-20 - assets:budget $20 - -EDITOR SUPPORT - Add-on modes exist for various text editors, to make working with jour- - nal files easier. They add colour, navigation aids and helpful com- - mands. For hledger users who edit the journal file directly (the - majority), using one of these modes is quite recommended. - - These were written with Ledger in mind, but also work with hledger - files: - - - Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html - Vim https://github.com/ledger/ledger/wiki/Getting-started - - - Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub- - lime-Text - Textmate https://github.com/ledger/ledger/wiki/Using-Text- - Mate-2 - Text Wrangler https://github.com/ledger/ledger/wiki/Edit- - ing-Ledger-files-with-TextWrangler - Visual Studio https://marketplace.visualstudio.com/items?item- - Code Name=mark-hansen.hledger-vscode - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger 1.5 December 2017 hledger_journal(5) diff --git a/.otherdocs/hledger_timeclock.5 b/.otherdocs/hledger_timeclock.5 deleted file mode 100644 --- a/.otherdocs/hledger_timeclock.5 +++ /dev/null @@ -1,92 +0,0 @@ - -.TH "hledger_timeclock" "5" "December 2017" "hledger 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -Timeclock \- the time logging format of timeclock.el, as read by hledger -.SH DESCRIPTION -.PP -hledger can read timeclock files. -As with Ledger, these are (a subset of) timeclock.el's format, -containing clock\-in and clock\-out entries as in the example below. -The date is a simple date. -The time format is HH:MM[:SS][+\-ZZZZ]. -Seconds and timezone are optional. -The timezone, if present, must be four digits and is ignored (currently -the time is always interpreted as a local time). -.IP -.nf -\f[C] -i\ 2015/03/30\ 09:00:00\ some:account\ name\ \ optional\ description\ after\ two\ spaces -o\ 2015/03/30\ 09:20:00 -i\ 2015/03/31\ 22:21:45\ another\ account -o\ 2015/04/01\ 02:00:34 -\f[] -.fi -.PP -hledger treats each clock\-in/clock\-out pair as a transaction posting -some number of hours to an account. -Or if the session spans more than one day, it is split into several -transactions, one for each day. -For the above time log, \f[C]hledger\ print\f[] generates these journal -entries: -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.timeclock\ print -2015/03/30\ *\ optional\ description\ after\ two\ spaces -\ \ \ \ (some:account\ name)\ \ \ \ \ \ \ \ \ 0.33h - -2015/03/31\ *\ 22:21\-23:59 -\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 1.64h - -2015/04/01\ *\ 00:00\-02:00 -\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 2.01h -\f[] -.fi -.PP -Here is a sample.timeclock to download and some queries to try: -.IP -.nf -\f[C] -$\ hledger\ \-f\ sample.timeclock\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ current\ time\ balances -$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ 2009/3\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ sessions\ in\ march\ 2009 -$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ weekly\ \-\-depth\ 1\ \-\-empty\ \ #\ time\ summary\ by\ week -\f[] -.fi -.PP -To generate time logs, ie to clock in and clock out, you could: -.IP \[bu] 2 -use emacs and the built\-in timeclock.el, or the extended -timeclock\-x.el and perhaps the extras in ledgerutils.el -.IP \[bu] 2 -at the command line, use these bash aliases: -\f[C]shell\ \ \ alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG"\ \ \ alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG"\f[] -.IP \[bu] 2 -or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x -repository. -These rely on a \[lq]timeclock\[rq] executable which I think is just the -ledger 2 executable renamed. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger_timeclock.info b/.otherdocs/hledger_timeclock.info deleted file mode 100644 --- a/.otherdocs/hledger_timeclock.info +++ /dev/null @@ -1,60 +0,0 @@ -This is hledger_timeclock.info, produced by makeinfo version 6.5 from -stdin. - - -File: hledger_timeclock.info, Node: Top, Up: (dir) - -hledger_timeclock(5) hledger 1.5 -******************************** - -hledger can read timeclock files. As with Ledger, these are (a subset -of) timeclock.el's format, containing clock-in and clock-out entries as -in the example below. The date is a simple date. The time format is -HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, if -present, must be four digits and is ignored (currently the time is -always interpreted as a local time). - -i 2015/03/30 09:00:00 some:account name optional description after two spaces -o 2015/03/30 09:20:00 -i 2015/03/31 22:21:45 another account -o 2015/04/01 02:00:34 - - hledger treats each clock-in/clock-out pair as a transaction posting -some number of hours to an account. Or if the session spans more than -one day, it is split into several transactions, one for each day. For -the above time log, 'hledger print' generates these journal entries: - -$ hledger -f t.timeclock print -2015/03/30 * optional description after two spaces - (some:account name) 0.33h - -2015/03/31 * 22:21-23:59 - (another account) 1.64h - -2015/04/01 * 00:00-02:00 - (another account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - -$ hledger -f sample.timeclock balance # current time balances -$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 -$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - * use emacs and the built-in timeclock.el, or the extended - timeclock-x.el and perhaps the extras in ledgerutils.el - - * at the command line, use these bash aliases: 'shell alias ti="echo - i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o - `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' - * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. - These rely on a "timeclock" executable which I think is just the - ledger 2 executable renamed. - - - -Tag Table: -Node: Top78 - -End Tag Table diff --git a/.otherdocs/hledger_timeclock.txt b/.otherdocs/hledger_timeclock.txt deleted file mode 100644 --- a/.otherdocs/hledger_timeclock.txt +++ /dev/null @@ -1,80 +0,0 @@ - -hledger_timeclock(5) hledger User Manuals hledger_timeclock(5) - - - -NAME - Timeclock - the time logging format of timeclock.el, as read by hledger - -DESCRIPTION - hledger can read timeclock files. As with Ledger, these are (a subset - of) timeclock.el's format, containing clock-in and clock-out entries as - in the example below. The date is a simple date. The time format is - HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, - if present, must be four digits and is ignored (currently the time is - always interpreted as a local time). - - i 2015/03/30 09:00:00 some:account name optional description after two spaces - o 2015/03/30 09:20:00 - i 2015/03/31 22:21:45 another account - o 2015/04/01 02:00:34 - - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For - the above time log, hledger print generates these journal entries: - - $ hledger -f t.timeclock print - 2015/03/30 * optional description after two spaces - (some:account name) 0.33h - - 2015/03/31 * 22:21-23:59 - (another account) 1.64h - - 2015/04/01 * 00:00-02:00 - (another account) 2.01h - - Here is a sample.timeclock to download and some queries to try: - - $ hledger -f sample.timeclock balance # current time balances - $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 - $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - o use emacs and the built-in timeclock.el, or the extended time- - clock-x.el and perhaps the extras in ledgerutils.el - - o at the command line, use these bash aliases: - shell alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" - - o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 - executable renamed. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger 1.5 December 2017 hledger_timeclock(5) diff --git a/.otherdocs/hledger_timedot.5 b/.otherdocs/hledger_timedot.5 deleted file mode 100644 --- a/.otherdocs/hledger_timedot.5 +++ /dev/null @@ -1,154 +0,0 @@ - -.TH "hledger_timedot" "5" "December 2017" "hledger 1.5" "hledger User Manuals" - - - -.SH NAME -.PP -Timedot \- hledger's human\-friendly time logging format -.SH DESCRIPTION -.PP -Timedot is a plain text format for logging dated, categorised quantities -(of time, usually), supported by hledger. -It is convenient for approximate and retroactive time logging, eg when -the real\-time clock\-in/out required with a timeclock file is too -precise or too interruptive. -It can be formatted like a bar chart, making clear at a glance where -time was spent. -.PP -Though called \[lq]timedot\[rq], this format is read by hledger as -commodityless quantities, so it could be used to represent dated -quantities other than time. -In the docs below we'll assume it's time. -.SH FILE FORMAT -.PP -A timedot file contains a series of day entries. -A day entry begins with a date, and is followed by category/quantity -pairs, one per line. -Dates are hledger\-style simple dates (see hledger_journal(5)). -Categories are hledger\-style account names, optionally indented. -As in a hledger journal, there must be at least two spaces between the -category (account name) and the quantity. -.PP -Quantities can be written as: -.IP \[bu] 2 -a sequence of dots (.) representing quarter hours. -Spaces may optionally be used for grouping and readability. -Eg: \&.... -\&.. -.IP \[bu] 2 -an integral or decimal number, representing hours. -Eg: 1.5 -.IP \[bu] 2 -an integral or decimal number immediately followed by a unit symbol -\f[C]s\f[], \f[C]m\f[], \f[C]h\f[], \f[C]d\f[], \f[C]w\f[], \f[C]mo\f[], -or \f[C]y\f[], representing seconds, minutes, hours, days weeks, months -or years respectively. -Eg: 90m. -The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, -1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. -.PP -Blank lines and lines beginning with #, ; or * are ignored. -An example: -.IP -.nf -\f[C] -#\ on\ this\ day,\ 6h\ was\ spent\ on\ client\ work,\ 1.5h\ on\ haskell\ FOSS\ work,\ etc. -2016/2/1 -inc:client1\ \ \ ....\ ....\ ....\ ....\ ....\ .... -fos:haskell\ \ \ ....\ ..\ -biz:research\ \ . - -2016/2/2 -inc:client1\ \ \ ....\ .... -biz:research\ \ . -\f[] -.fi -.PP -Or with numbers: -.IP -.nf -\f[C] -2016/2/3 -inc:client1\ \ \ 4 -fos:hledger\ \ \ 3 -biz:research\ \ 1 -\f[] -.fi -.PP -Reporting: -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.timedot\ print\ date:2016/2/2 -2016/02/02\ * -\ \ \ \ (inc:client1)\ \ \ \ \ \ \ \ \ \ 2.00 - -2016/02/02\ * -\ \ \ \ (biz:research)\ \ \ \ \ \ \ \ \ \ 0.25 -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.timedot\ bal\ \-\-daily\ \-\-tree -Balance\ changes\ in\ 2016/02/01\-2016/02/03: - -\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2016/02/01d\ \ 2016/02/02d\ \ 2016/02/03d\ -============++======================================== -\ biz\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ -\ \ \ research\ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ -\ fos\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ -\ \ \ haskell\ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ -\ \ \ hledger\ \ ||\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ -\ inc\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ -\ \ \ client1\ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ -\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 7.75\ \ \ \ \ \ \ \ \ 2.25\ \ \ \ \ \ \ \ \ 8.00\ -\f[] -.fi -.PP -I prefer to use period for separating account components. -We can make this work with an account alias: -.IP -.nf -\f[C] -2016/2/4 -fos.hledger.timedot\ \ 4 -fos.ledger\ \ \ \ \ \ \ \ \ \ \ .. -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4 -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50\ \ fos -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.00\ \ \ \ hledger:timedot -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0.50\ \ \ \ ledger -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50 -\f[] -.fi -.PP -Here is a sample.timedot. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/.otherdocs/hledger_timedot.info b/.otherdocs/hledger_timedot.info deleted file mode 100644 --- a/.otherdocs/hledger_timedot.info +++ /dev/null @@ -1,116 +0,0 @@ -This is hledger_timedot.info, produced by makeinfo version 6.5 from -stdin. - - -File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir) - -hledger_timedot(5) hledger 1.5 -****************************** - -Timedot is a plain text format for logging dated, categorised quantities -(of time, usually), supported by hledger. It is convenient for -approximate and retroactive time logging, eg when the real-time -clock-in/out required with a timeclock file is too precise or too -interruptive. It can be formatted like a bar chart, making clear at a -glance where time was spent. - - Though called "timedot", this format is read by hledger as -commodityless quantities, so it could be used to represent dated -quantities other than time. In the docs below we'll assume it's time. -* Menu: - -* FILE FORMAT:: - - -File: hledger_timedot.info, Node: FILE FORMAT, Prev: Top, Up: Top - -1 FILE FORMAT -************* - -A timedot file contains a series of day entries. A day entry begins -with a date, and is followed by category/quantity pairs, one per line. -Dates are hledger-style simple dates (see hledger_journal(5)). -Categories are hledger-style account names, optionally indented. As in -a hledger journal, there must be at least two spaces between the -category (account name) and the quantity. - - Quantities can be written as: - - * a sequence of dots (.) representing quarter hours. Spaces may - optionally be used for grouping and readability. Eg: .... .. - - * an integral or decimal number, representing hours. Eg: 1.5 - - * an integral or decimal number immediately followed by a unit symbol - 's', 'm', 'h', 'd', 'w', 'mo', or 'y', representing seconds, - minutes, hours, days weeks, months or years respectively. Eg: 90m. - The following equivalencies are assumed, currently: 1m = 60s, 1h = - 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. - - Blank lines and lines beginning with #, ; or * are ignored. An -example: - -# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. -2016/2/1 -inc:client1 .... .... .... .... .... .... -fos:haskell .... .. -biz:research . - -2016/2/2 -inc:client1 .... .... -biz:research . - - Or with numbers: - -2016/2/3 -inc:client1 4 -fos:hledger 3 -biz:research 1 - - Reporting: - -$ hledger -f t.timedot print date:2016/2/2 -2016/02/02 * - (inc:client1) 2.00 - -2016/02/02 * - (biz:research) 0.25 - -$ hledger -f t.timedot bal --daily --tree -Balance changes in 2016/02/01-2016/02/03: - - || 2016/02/01d 2016/02/02d 2016/02/03d -============++======================================== - biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 -------------++---------------------------------------- - || 7.75 2.25 8.00 - - I prefer to use period for separating account components. We can -make this work with an account alias: - -2016/2/4 -fos.hledger.timedot 4 -fos.ledger .. - -$ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4 - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger --------------------- - 4.50 - - Here is a sample.timedot. - - -Tag Table: -Node: Top76 -Node: FILE FORMAT805 -Ref: #file-format906 - -End Tag Table diff --git a/.otherdocs/hledger_timedot.txt b/.otherdocs/hledger_timedot.txt deleted file mode 100644 --- a/.otherdocs/hledger_timedot.txt +++ /dev/null @@ -1,127 +0,0 @@ - -hledger_timedot(5) hledger User Manuals hledger_timedot(5) - - - -NAME - Timedot - hledger's human-friendly time logging format - -DESCRIPTION - Timedot is a plain text format for logging dated, categorised quanti- - ties (of time, usually), supported by hledger. It is convenient for - approximate and retroactive time logging, eg when the real-time - clock-in/out required with a timeclock file is too precise or too - interruptive. It can be formatted like a bar chart, making clear at a - glance where time was spent. - - Though called "timedot", this format is read by hledger as commodity- - less quantities, so it could be used to represent dated quantities - other than time. In the docs below we'll assume it's time. - -FILE FORMAT - A timedot file contains a series of day entries. A day entry begins - with a date, and is followed by category/quantity pairs, one per line. - Dates are hledger-style simple dates (see hledger_journal(5)). Cate- - gories are hledger-style account names, optionally indented. As in a - hledger journal, there must be at least two spaces between the category - (account name) and the quantity. - - Quantities can be written as: - - o a sequence of dots (.) representing quarter hours. Spaces may - optionally be used for grouping and readability. Eg: .... .. - - o an integral or decimal number, representing hours. Eg: 1.5 - - o an integral or decimal number immediately followed by a unit symbol - s, m, h, d, w, mo, or y, representing seconds, minutes, hours, days - weeks, months or years respectively. Eg: 90m. The following equiva- - lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = - 7d, 1mo = 30d, 1y=365d. - - Blank lines and lines beginning with #, ; or * are ignored. An exam- - ple: - - # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. - 2016/2/1 - inc:client1 .... .... .... .... .... .... - fos:haskell .... .. - biz:research . - - 2016/2/2 - inc:client1 .... .... - biz:research . - - Or with numbers: - - 2016/2/3 - inc:client1 4 - fos:hledger 3 - biz:research 1 - - Reporting: - - $ hledger -f t.timedot print date:2016/2/2 - 2016/02/02 * - (inc:client1) 2.00 - - 2016/02/02 * - (biz:research) 0.25 - - $ hledger -f t.timedot bal --daily --tree - Balance changes in 2016/02/01-2016/02/03: - - || 2016/02/01d 2016/02/02d 2016/02/03d - ============++======================================== - biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 - ------------++---------------------------------------- - || 7.75 2.25 8.00 - - I prefer to use period for separating account components. We can make - this work with an account alias: - - 2016/2/4 - fos.hledger.timedot 4 - fos.ledger .. - - $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4 - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger - -------------------- - 4.50 - - Here is a sample.timedot. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger 1.5 December 2017 hledger_timedot(5) diff --git a/CHANGES b/CHANGES --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,72 @@ -User-visible changes in the hledger CLI tool. See also hledger-lib. +User-visible changes in the hledger command line tool. + + +# 1.9 (2018/3/31) + +* support ghc 8.4, latest deps + +* journal: account directives can define a numeric account code to +customize sorting. bal/bs/cf/is will sort accounts by account code, +if any, then account name. + +* journal: support scientific number notation (#704, #706) + +* csv: reading a CSV file containing no records is no longer an error + +* cli: when the system text encoding is UTF-8, ignore any UTF-8 BOM +prefix found when reading files. (Paypal's new CSV has this BOM +prefix, causing a confusing parse error.) + +* cli: tabular reports no longer have a trailing blank line added. +(This allows omitting the ">=0" delimiters in our functional tests, +making them easier to read and maintain.) + +* acc: the accounts command now has --declared and --used flags + +* bal: the --invert flag flips all signs + +* bal: --drop now works with CSV output + +* bal/bs/bse/cf/is: show overall report span in title + +* bal/bs/bse/cf/is: show short month names as headings in monthly reports + +* bal/bs/bse/cf/is: these commands can now generate HTML output + +* bal/bs/is/cf: drop short name and indent fields from multicolumn CSV + +* bs/bse/cf/is: these, the "financial statement" commands, now show +normal income, liability and equity balances as positive numbers. +Negative numbers now indicate a contra-balance (eg an overdrawn +checking account), a net loss, or a negative net worth. This makes +these reports more like conventional financial statements, and easier +to read and share with others. (Other commands, like balance, have not +changed.) (experimental) + +* bs/cf/is: always show a tabular report, even with no report +interval. Previously you would get a simple borderless report like +the original balance command. Less code, fewer bugs. + +* bs/bse/cf/is: in CSV output, don't repeat the headings row for each subreport + +* budget: warn that CSV output with bal --budget is unimplemented + +* budget: bal --budget shows budget goals even with no or zero actual amounts. +Makes budget reports more intuitive, at the cost of a temporary hack +which may misorder columns in some cases (if actual and budget +activity occur in a different range of columns). + +* budget: --budget uses only periodic txns with the selected interval. +Budgets with different interval, eg a daily and weekly budget, are independent. + +* budget: show mostly fixed-width columns for readability + +* budget: fix bug where a budget report could include budget goals +ending on the day before the report start date (splitSpan issue) + +* close: the equity command has been renamed to close. It now ignores +any begin date (it always closes historical end balances). It also +ignores --date2. # 1.5 (2017/12/31) diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs --- a/Hledger/Cli/CliOptions.hs +++ b/Hledger/Cli/CliOptions.hs @@ -152,7 +152,7 @@ ,flagNone ["cleared","C"] (setboolopt "cleared") "include only cleared postings/txns" ,flagNone ["real","R"] (setboolopt "real") "include only non-virtual postings" ,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "NUM" "(or -NUM): hide accounts/postings deeper than this" - ,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden" + ,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web)" ,flagNone ["cost","B"] (setboolopt "cost") "convert amounts to their cost at transaction time (using the transaction price, if any)" ,flagNone ["value","V"] (setboolopt "value") "convert amounts to their market value on the report end date (using the most recent applicable market price, if any)" ,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions" @@ -161,7 +161,7 @@ -- | Common output-related flags: --output-file, --output-format... outputflags = [outputFormatFlag, outputFileFlag] -outputFormatFlag = flagReq ["output-format","O"] (\s opts -> Right $ setopt "output-format" s opts) "FMT" "select the output format. Supported formats:\ntxt, csv." +outputFormatFlag = flagReq ["output-format","O"] (\s opts -> Right $ setopt "output-format" s opts) "FMT" "select the output format. Supported formats:\ntxt, csv, html." outputFileFlag = flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE. A file extension matching one of the above formats selects that format." argsFlag :: FlagHelp -> Arg RawOpts @@ -286,7 +286,7 @@ ,("web", "start the web interface") ,("accounts", "list account names") ,("balance-csv", "output a balance report as CSV") - ,("equity", "show a transaction entry zeroing all accounts") + ,("close", "show a transaction entry zeroing all accounts") ,("print-unique", "print only transactions with unique descriptions") ,("register-csv", "output a register report as CSV") ,("rewrite", "add specified postings to matched transaction entries") @@ -524,6 +524,7 @@ outputFormats = [defaultOutputFormat] ++ ["csv" + ,"html" ] -- | Get the output format from the --output-format option, diff --git a/Hledger/Cli/Commands.hs b/Hledger/Cli/Commands.hs --- a/Hledger/Cli/Commands.hs +++ b/Hledger/Cli/Commands.hs @@ -4,6 +4,7 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE CPP #-} module Hledger.Cli.Commands ( findCommand @@ -20,7 +21,7 @@ ,module Hledger.Cli.Commands.Cashflow ,module Hledger.Cli.Commands.Checkdates ,module Hledger.Cli.Commands.Checkdupes - ,module Hledger.Cli.Commands.Equity + ,module Hledger.Cli.Commands.Close ,module Hledger.Cli.Commands.Help ,module Hledger.Cli.Commands.Import ,module Hledger.Cli.Commands.Incomestatement @@ -38,7 +39,9 @@ import Control.Monad import Data.List import Data.List.Split (splitOn) +#if !(MIN_VERSION_base(4,11,0)) import Data.Monoid ((<>)) +#endif import Data.String.Here import Data.Text (Text) import qualified Data.Text as T @@ -59,7 +62,7 @@ import Hledger.Cli.Commands.Cashflow import Hledger.Cli.Commands.Checkdates import Hledger.Cli.Commands.Checkdupes -import Hledger.Cli.Commands.Equity +import Hledger.Cli.Commands.Close import Hledger.Cli.Commands.Help import Hledger.Cli.Commands.Import import Hledger.Cli.Commands.Incomestatement @@ -86,7 +89,7 @@ ,(cashflowmode , cashflow) ,(checkdatesmode , checkdates) ,(checkdupesmode , checkdupes) - ,(equitymode , equity) + ,(closemode , close) ,(helpmode , help') ,(importmode , importcmd) ,(incomestatementmode , incomestatement) @@ -152,7 +155,7 @@ web start web ui Generating data: - equity generate balance-resetting transactions + close generate balance-resetting transactions interest generate interest transactions rewrite generate automated postings on matched transactions diff --git a/Hledger/Cli/Commands/Accounts.hs b/Hledger/Cli/Commands/Accounts.hs --- a/Hledger/Cli/Commands/Accounts.hs +++ b/Hledger/Cli/Commands/Accounts.hs @@ -11,6 +11,7 @@ -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE CPP #-} module Hledger.Cli.Commands.Accounts ( accountsmode @@ -19,7 +20,9 @@ ) where import Data.List +#if !(MIN_VERSION_base(4,11,0)) import Data.Monoid +#endif -- import Data.Text (Text) import qualified Data.Text as T import System.Console.CmdArgs.Explicit as C @@ -35,11 +38,20 @@ accountsmode = (defCommandMode $ ["accounts"] ++ aliases) { modeHelp = "show account names" `withAliases` aliases ,modeHelpSuffix = [ - "This command lists the accounts referenced by matched postings (and in tree mode, their parents as well). The accounts can be depth-clipped (--depth N) or have their leading parts trimmed (--drop N)." + "This command lists account names, either declared with account directives" + ,"(--declared), posted to (--used), or both (default)." + ,"With query arguments, only matched account names and account names" + ,"referenced by matched postings are shown." + ,"It shows a flat list by default. With `--tree`, it uses indentation to" + ,"show the account hierarchy." + ,"In flat mode you can add `--drop N` to omit the first few account name components." + ,"Account names can be depth-clipped with `--depth N` or depth:N." ] ,modeGroupFlags = C.Group { groupUnnamed = [ - flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree" + flagNone ["declared"] (\opts -> setboolopt "declared" opts) "show account names declared with account directives" + ,flagNone ["used"] (\opts -> setboolopt "used" opts) "show account names referenced by transactions" + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree" ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)" ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" ] @@ -51,13 +63,19 @@ -- | The accounts command. accounts :: CliOpts -> Journal -> IO () -accounts CliOpts{reportopts_=ropts} j = do +accounts CliOpts{rawopts_=rawopts, reportopts_=ropts} j = do d <- getCurrentDay let q = queryFromOpts d ropts nodepthq = dbg1 "nodepthq" $ filterQuery (not . queryIsDepth) q depth = dbg1 "depth" $ queryDepth $ filterQuery queryIsDepth q - ps = dbg1 "ps" $ journalPostings $ filterJournalPostings nodepthq j - as = dbg1 "as" $ nub $ filter (not . T.null) $ map (clipAccountName depth) $ sort $ map paccount ps + matcheddeclaredaccts = dbg1 "matcheddeclaredaccts" $ nub $ sort $ filter (matchesAccount q) $ map fst $ jaccounts j + matchedps = dbg1 "ps" $ journalPostings $ filterJournalPostings nodepthq j + matchedusedaccts = dbg1 "matchedusedaccts" $ nub $ sort $ filter (not . T.null) $ map (clipAccountName depth) $ map paccount matchedps + used = boolopt "used" rawopts + declared = boolopt "declared" rawopts + as | declared && not used = matcheddeclaredaccts + | not declared && used = matchedusedaccts + | otherwise = nub $ sort $ matcheddeclaredaccts ++ matchedusedaccts as' | tree_ ropts = expandAccountNames as | otherwise = as render a | tree_ ropts = T.replicate (2 * (accountNameLevel a - 1)) " " <> accountLeafName a diff --git a/Hledger/Cli/Commands/Add.hs b/Hledger/Cli/Commands/Add.hs --- a/Hledger/Cli/Commands/Add.hs +++ b/Hledger/Cli/Commands/Add.hs @@ -197,7 +197,7 @@ dateandcodep = do d <- smartdate c <- optional codep - many spacenonewline + skipMany spacenonewline eof return (d, T.pack $ fromMaybe "" c) -- defday = fixSmartDate today $ fromparse $ (parse smartdate "" . lowercase) defdate @@ -294,7 +294,7 @@ amountandcommentp :: JournalParser Identity (Amount, Text) amountandcommentp = do a <- amountp - lift (many spacenonewline) + lift (skipMany spacenonewline) c <- T.pack <$> fromMaybe "" `fmap` optional (char ';' >> many anyChar) -- eof return (a,c) diff --git a/Hledger/Cli/Commands/Balance.hs b/Hledger/Cli/Commands/Balance.hs --- a/Hledger/Cli/Commands/Balance.hs +++ b/Hledger/Cli/Commands/Balance.hs @@ -233,6 +233,8 @@ -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE ExtendedDefaultRules #-} +{-# LANGUAGE ScopedTypeVariables #-} module Hledger.Cli.Commands.Balance ( balancemode @@ -241,18 +243,22 @@ ,balanceReportItemAsText ,multiBalanceReportAsText ,multiBalanceReportAsCsv + ,multiBalanceReportAsHtml + ,multiBalanceReportHtmlRows ,renderBalanceReportTable ,balanceReportAsTable ,tests_Hledger_Cli_Commands_Balance ) where -import Data.List (intercalate, nub) +import Data.Decimal +import Data.List import Data.Maybe import qualified Data.Map as Map --- import Data.Monoid import qualified Data.Text as T +import qualified Data.Text.Lazy as TL import System.Console.CmdArgs.Explicit as C import Data.Decimal (roundTo) +import Lucid as L import Text.CSV import Test.HUnit import Text.Printf (printf) @@ -284,9 +290,10 @@ ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode to display prettier tables" - ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." + ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed." ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" ,flagNone ["show-unbudgeted"] (setboolopt "show-unbudgeted") "with --budget, show unbudgeted accounts also" + ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign" ] ++ outputflags ,groupHidden = [] @@ -304,47 +311,47 @@ Right _ -> do let format = outputFormatFromOpts opts interval = interval_ ropts - -- XXX shenanigans: use singleBalanceReport or multiBalanceReport when we must, - -- ie when there's a report interval, or when --historical or --cumulative - -- are used (balanceReport doesn't handle those). - -- Otherwise prefer the older balanceReport since it can elide boring parents. - -- See also compoundBalanceCommandSingleColumnReport, singleBalanceReport etc. case interval of NoInterval -> do + -- single column balance report let report - -- For --historical/--cumulative, we must use multiBalanceReport. - -- (This forces --no-elide.) | balancetype_ ropts `elem` [HistoricalBalance, CumulativeChange] = let ropts' | flat_ ropts = ropts | otherwise = ropts{accountlistmode_=ALTree} - in singleBalanceReport ropts' (queryFromOpts d ropts) j - | otherwise = balanceReport ropts (queryFromOpts d ropts) j + in balanceReportFromMultiBalanceReport ropts' (queryFromOpts d ropts) j + -- for historical balances we must use balanceReportFromMultiBalanceReport (also forces --no-elide) + | otherwise = balanceReport ropts (queryFromOpts d ropts) j -- simple Ledger-style balance report render = case format of - "csv" -> \ropts r -> (++ "\n") $ printCSV $ balanceReportAsCsv ropts r - _ -> balanceReportAsText + "csv" -> \ropts r -> (++ "\n") $ printCSV $ balanceReportAsCsv ropts r + "html" -> \_ _ -> error' "Sorry, HTML output is not yet implemented for this kind of report." -- TODO + _ -> balanceReportAsText writeOutput opts $ render ropts report _ | boolopt "budget" rawopts -> do - let budget = budgetJournal opts j + -- multi column budget report + reportspan <- reportSpan j ropts + let budget = budgetJournal opts reportspan j j' = budgetRollUp opts budget j - report = multiBalanceReport ropts (queryFromOpts d ropts) j' - budgetReport = multiBalanceReport ropts (queryFromOpts d ropts) budget + report = dbg1 "report" $ multiBalanceReport ropts (queryFromOpts d ropts) j' + budgetReport = dbg1 "budgetreport" $ multiBalanceReport ropts (queryFromOpts d ropts) budget render = case format of - -- XXX: implement csv rendering - "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv ropts + "csv" -> const $ error' "Sorry, CSV output is not yet implemented for this kind of report." -- TODO + "html" -> const $ error' "Sorry, HTML output is not yet implemented for this kind of report." -- TODO _ -> multiBalanceReportWithBudgetAsText ropts budgetReport writeOutput opts $ render report | otherwise -> do + -- multi column balance report let report = multiBalanceReport ropts (queryFromOpts d ropts) j render = case format of - "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv ropts - _ -> multiBalanceReportAsText ropts + "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv ropts + "html" -> (++ "\n") . TL.unpack . L.renderText . multiBalanceReportAsHtml ropts + _ -> multiBalanceReportAsText ropts writeOutput opts $ render report --- | Re-map account names to closet parent with periodic transaction from budget. --- Accounts that dont have suitable parent are either remapped to ":topAccount" --- or left as-is if --show-unbudgeted is provided +-- | Re-map account names to closest parent with periodic transaction from budget. +-- Accounts that don't have suitable parent are either remapped to ":topAccount" +-- or left as-is if --show-unbudgeted is provided. budgetRollUp :: CliOpts -> Journal -> Journal -> Journal budgetRollUp CliOpts{rawopts_=rawopts} budget j = j { jtxns = remapTxn <$> jtxns j } where @@ -356,20 +363,29 @@ | otherwise = case parentAccountName acctName of "" | boolopt "show-unbudgeted" rawopts -> origAcctName - | otherwise -> T.append (T.pack ":") acctName + | otherwise -> T.append (T.pack ":") acctName -- TODO: --drop should not remove this parent -> remapAccount' parent remapPosting p = p { paccount = remapAccount $ paccount p, porigin = Just . fromMaybe p $ porigin p } remapTxn = mapPostings (map remapPosting) mapPostings f t = txnTieKnot $ t { tpostings = f $ tpostings t } --- | Generate journal of all periodic transactions in the given journal for the --- entireity of its history or reporting period, whatever is smaller -budgetJournal :: CliOpts -> Journal -> Journal -budgetJournal opts j = journalBalanceTransactions' opts j { jtxns = budget } +-- | Select all periodic transactions from the given journal which +-- match the requested report interval, and use them to generate +-- budget transactions (like forecast transactions) in the specified +-- report period (calculated in IO and passed in). +budgetJournal :: CliOpts -> DateSpan -> Journal -> Journal +budgetJournal opts reportspan j = journalBalanceTransactions' opts j { jtxns = budgetts } where - dates = spanIntersect (jdatespan j) (periodAsDateSpan $ period_ $ reportopts_ opts) - budget = [makeBudget t | pt <- jperiodictxns j, t <- runPeriodicTransaction pt dates] - makeBudget t = txnTieKnot $ t { tdescription = T.pack "Budget transaction" } + budgetinterval = dbg2 "budgetinterval" $ intervalFromRawOpts $ rawopts_ opts + budgetspan = dbg2 "budgetspan" $ reportspan + budgetts = + dbg1 "budgetts" $ + [makeBudgetTxn t + | pt <- jperiodictxns j + , periodTransactionInterval pt == Just budgetinterval + , t <- runPeriodicTransaction pt budgetspan + ] + makeBudgetTxn t = txnTieKnot $ t { tdescription = T.pack "Budget transaction" } journalBalanceTransactions' opts j = let assrt = not . ignore_assertions_ $ inputopts_ opts in @@ -390,7 +406,7 @@ balanceReportAsCsv :: ReportOpts -> BalanceReport -> CSV balanceReportAsCsv opts (items, total) = ["account","balance"] : - [[T.unpack a, showMixedAmountOneLineWithoutPrice b] | (a, _, _, b) <- items] + [[T.unpack (maybeAccountNameDrop opts a), showMixedAmountOneLineWithoutPrice b] | (a, _, _, b) <- items] ++ if no_total_ opts then [] @@ -503,122 +519,249 @@ TotalField -> fitStringMulti min max True False $ ((intercalate ", " . map strip . lines) (showamt total)) where showamt | color_ opts = cshowMixedAmountWithoutPrice - | otherwise = showMixedAmountWithoutPrice + | otherwise = showMixedAmountWithoutPrice _ -> "" -- multi-column balance reports -- | Render a multi-column balance report as CSV. +-- The CSV will always include the initial headings row, +-- and will include the final totals row unless --no-total is set. multiBalanceReportAsCsv :: ReportOpts -> MultiBalanceReport -> CSV multiBalanceReportAsCsv opts (MultiBalanceReport (colspans, items, (coltotals,tot,avg))) = - ("account" : "short account" : "indent" : map showDateSpan colspans - ++ (if row_total_ opts then ["total"] else []) - ++ (if average_ opts then ["average"] else []) + ("Account" : map showDateSpan colspans + ++ (if row_total_ opts then ["Total"] else []) + ++ (if average_ opts then ["Average"] else []) ) : - [T.unpack a : T.unpack a' : show i : + [T.unpack (maybeAccountNameDrop opts a) : map showMixedAmountOneLineWithoutPrice (amts ++ (if row_total_ opts then [rowtot] else []) ++ (if average_ opts then [rowavg] else [])) - | (a,a',i, amts, rowtot, rowavg) <- items] + | (a, _, _, amts, rowtot, rowavg) <- items] ++ if no_total_ opts then [] - else [["totals", "", ""] + else [["Total:"] ++ map showMixedAmountOneLineWithoutPrice ( coltotals ++ (if row_total_ opts then [tot] else []) ++ (if average_ opts then [avg] else []) )] +-- | Render a multi-column balance report as HTML. +multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html () +multiBalanceReportAsHtml ropts mbr = + let + (headingsrow,bodyrows,mtotalsrow) = multiBalanceReportHtmlRows ropts mbr + in + table_ $ mconcat $ + [headingsrow] + ++ bodyrows + ++ maybe [] (:[]) mtotalsrow + +-- | Render the HTML table rows for a MultiBalanceReport. +-- Returns the heading row, 0 or more body rows, and the totals row if enabled. +multiBalanceReportHtmlRows :: ReportOpts -> MultiBalanceReport -> (Html (), [Html ()], Maybe (Html ())) +multiBalanceReportHtmlRows ropts mbr = + let + headingsrow:rest = multiBalanceReportAsCsv ropts mbr + (bodyrows, mtotalsrow) | no_total_ ropts = (rest, Nothing) + | otherwise = (init rest, Just $ last rest) + in + (multiBalanceReportHtmlHeadRow ropts headingsrow + ,map (multiBalanceReportHtmlBodyRow ropts) bodyrows + ,multiBalanceReportHtmlFootRow ropts <$> mtotalsrow -- TODO pad totals row with zeros when there are + ) + +-- | Render one MultiBalanceReport heading row as a HTML table row. +multiBalanceReportHtmlHeadRow :: ReportOpts -> [String] -> Html () +multiBalanceReportHtmlHeadRow _ [] = mempty -- shouldn't happen +multiBalanceReportHtmlHeadRow ropts (acct:rest) = + let + defstyle = style_ "" + (amts,tot,avg) + | row_total_ ropts && average_ ropts = (init $ init rest, [last $ init rest], [last rest]) + | row_total_ ropts = (init rest, [last rest], []) + | average_ ropts = (init rest, [], [last rest]) + | otherwise = (rest, [], []) + in + tr_ $ mconcat $ + td_ [class_ "account"] (toHtml acct) + : [td_ [class_ "", defstyle] (toHtml a) | a <- amts] + ++ [td_ [class_ "rowtotal", defstyle] (toHtml a) | a <- tot] + ++ [td_ [class_ "rowaverage", defstyle] (toHtml a) | a <- avg] + +-- | Render one MultiBalanceReport data row as a HTML table row. +multiBalanceReportHtmlBodyRow :: ReportOpts -> [String] -> Html () +multiBalanceReportHtmlBodyRow _ [] = mempty -- shouldn't happen +multiBalanceReportHtmlBodyRow ropts (label:rest) = + let + defstyle = style_ "text-align:right" + (amts,tot,avg) + | row_total_ ropts && average_ ropts = (init $ init rest, [last $ init rest], [last rest]) + | row_total_ ropts = (init rest, [last rest], []) + | average_ ropts = (init rest, [], [last rest]) + | otherwise = (rest, [], []) + in + tr_ $ mconcat $ + td_ [class_ "account", style_ "text-align:left"] (toHtml label) + : [td_ [class_ "amount", defstyle] (toHtml a) | a <- amts] + ++ [td_ [class_ "amount rowtotal", defstyle] (toHtml a) | a <- tot] + ++ [td_ [class_ "amount rowaverage", defstyle] (toHtml a) | a <- avg] + +-- | Render one MultiBalanceReport totals row as a HTML table row. +multiBalanceReportHtmlFootRow :: ReportOpts -> [String] -> Html () +multiBalanceReportHtmlFootRow _ropts [] = mempty +-- TODO pad totals row with zeros when subreport is empty +-- multiBalanceReportHtmlFootRow ropts $ +-- "" +-- : repeat nullmixedamt zeros +-- ++ (if row_total_ ropts then [nullmixedamt] else []) +-- ++ (if average_ ropts then [nullmixedamt] else []) +multiBalanceReportHtmlFootRow ropts (acct:rest) = + let + defstyle = style_ "text-align:right" + (amts,tot,avg) + | row_total_ ropts && average_ ropts = (init $ init rest, [last $ init rest], [last rest]) + | row_total_ ropts = (init rest, [last rest], []) + | average_ ropts = (init rest, [], [last rest]) + | otherwise = (rest, [], []) + in + tr_ $ mconcat $ + th_ [style_ "text-align:left"] (toHtml acct) + : [th_ [class_ "amount coltotal", defstyle] (toHtml a) | a <- amts] + ++ [th_ [class_ "amount coltotal", defstyle] (toHtml a) | a <- tot] + ++ [th_ [class_ "amount colaverage", defstyle] (toHtml a) | a <- avg] + +--thRow :: [String] -> Html () +--thRow = tr_ . mconcat . map (th_ . toHtml) + -- | Render a multi-column balance report as plain text suitable for console output. multiBalanceReportAsText :: ReportOpts -> MultiBalanceReport -> String multiBalanceReportAsText opts r = - printf "%s in %s:\n\n" typeStr (showDateSpan $ multiBalanceReportSpan r) + printf "%s in %s:\n\n" desc (showDateSpan $ multiBalanceReportSpan r) ++ renderBalanceReportTable opts tabl where tabl = balanceReportAsTable opts r - typeStr :: String - typeStr = case balancetype_ opts of + desc = case balancetype_ opts of PeriodChange -> "Balance changes" CumulativeChange -> "Ending balances (cumulative)" HistoricalBalance -> "Ending balances (historical)" --- | Render two multi-column balance reports as plain text suitable for console output. --- They are assumed to have same number of columns, one of them representing --- a budget -multiBalanceReportWithBudgetAsText :: ReportOpts -> MultiBalanceReport -> MultiBalanceReport -> String -multiBalanceReportWithBudgetAsText opts budget r = - printf "%s in %s:\n\n" typeStr (showDateSpan $ multiBalanceReportSpan r) - ++ renderBalanceReportTable' opts showcell tabl +type ActualAmount = MixedAmount +type BudgetAmount = MixedAmount +type ActualAmountsReport = MultiBalanceReport +type BudgetAmountsReport = MultiBalanceReport +type ActualAmountsTable = Table String String MixedAmount +type BudgetAmountsTable = Table String String MixedAmount +type ActualAndBudgetAmountsTable = Table String String (Maybe MixedAmount, Maybe MixedAmount) +type Percentage = Decimal + +-- | Given two multi-column balance reports, the first representing a budget +-- (target change amounts) and the second representing actual change amounts, +-- render a budget report as plain text suitable for console output. +-- The reports should have the same number of columns. +multiBalanceReportWithBudgetAsText :: ReportOpts -> BudgetAmountsReport -> ActualAmountsReport -> String +multiBalanceReportWithBudgetAsText opts budgetr actualr = + printf "%s in %s:\n\n" desc (showDateSpan $ multiBalanceReportSpan actualr) + ++ renderBalanceReportTable' opts showcell actualandbudgetamts where - tabl = combine (balanceReportAsTable opts r) (balanceReportAsTable opts budget) - typeStr :: String - typeStr = case balancetype_ opts of + desc :: String + desc = case balancetype_ opts of PeriodChange -> "Balance changes" CumulativeChange -> "Ending balances (cumulative)" HistoricalBalance -> "Ending balances (historical)" - showcell (real, Nothing) = showamt real - showcell (real, Just budget) = - case percentage real budget of - Just pct -> printf "%s [%s%% of %s]" (showamt real) (show $ roundTo 0 pct) (showamt budget) - Nothing -> printf "%s [%s]" (showamt real) (showamt budget) - percentage real budget = + + actualandbudgetamts :: ActualAndBudgetAmountsTable + actualandbudgetamts = combineTables (balanceReportAsTable opts actualr) (balanceReportAsTable opts budgetr) + + showcell :: (Maybe ActualAmount, Maybe BudgetAmount) -> String + showcell (mactual, mbudget) = actualstr ++ " " ++ budgetstr + where + actualwidth = 7 + percentwidth = 4 + budgetwidth = 5 + actualstr = printf ("%"++show actualwidth++"s") (maybe "" showamt mactual) + budgetstr = case (mactual, mbudget) of + (_, Nothing) -> replicate (percentwidth + 7 + budgetwidth) ' ' + (mactual, Just budget) -> + case percentage mactual budget of + Just pct -> + printf ("[%"++show percentwidth++"s%% of %"++show budgetwidth++"s]") + (show $ roundTo 0 pct) (showamt budget) + Nothing -> + printf ("["++replicate (percentwidth+5) ' '++"%"++show budgetwidth++"s]") + (showamt budget) + + percentage :: Maybe ActualAmount -> BudgetAmount -> Maybe Percentage + percentage Nothing _ = Nothing + percentage (Just actual) budget = -- percentage of budget consumed is always computed in the cost basis - case (toCost real, toCost budget) of - (Mixed [a1], Mixed [a2]) + case (toCost actual, toCost budget) of + (Mixed [a1], Mixed [a2]) | isReallyZeroAmount a1 -> Just 0 -- if there are no postings, we consumed 0% of budget - | acommodity a1 == acommodity a2 && aquantity a2 /= 0 -> + | acommodity a1 == acommodity a2 && aquantity a2 /= 0 -> Just $ 100 * aquantity a1 / aquantity a2 _ -> Nothing where toCost = normaliseMixedAmount . costOfMixedAmount + + showamt :: MixedAmount -> String showamt | color_ opts = cshowMixedAmountOneLineWithoutPrice | otherwise = showMixedAmountOneLineWithoutPrice - -- combine reportTable budgetTable will combine them into a single table where cells - -- are tuples of (actual, Maybe budget) numbers. Main assumptions is that - -- row/column titles of budgetTable are subset of row/column titles or reportTable, - -- and there are now row/column titles in budgetTable that are not mentioned in reporTable. - -- Both of these are satisfied by construction of budget report and process of rolling up - -- account names. - combine (Table l t d) (Table l' t' d') = Table l t combinedRows - where - -- For all accounts that are present in the budget, zip real amounts with budget amounts - combinedRows = [ combineRow row budgetRow - | (acct, row) <- zip (headerContents l) d - , let budgetRow = - if acct == "" then [] -- "" is totals row - else fromMaybe [] $ Map.lookup acct budgetAccts - ] - -- Budget could cover smaller interval of time than the whole journal. - -- Headers for budget row will always be a sublist of headers of row - combineRow r br = - let reportRow = zip (headerContents t) r - budgetRow = Map.fromList $ zip (headerContents t') br - findBudgetVal hdr = Map.lookup hdr budgetRow - in map (\(hdr, val) -> (val, findBudgetVal hdr)) reportRow - budgetAccts = Map.fromList $ zip (headerContents l') d' - + + -- Combine a table of actual amounts and a table of budgeted amounts into + -- a single table of (Maybe actualamount, Maybe budgetamount) tuples. + -- The actual and budget table need not have the same account rows or date columns. + -- Every row and column from either table will appear in the combined table. + -- TODO better to combine the reports, not these tables which are just rendering helpers + combineTables :: ActualAmountsTable -> BudgetAmountsTable -> ActualAndBudgetAmountsTable + combineTables (Table aaccthdrs adatehdrs arows) (Table baccthdrs bdatehdrs brows) = + addtotalrow $ Table caccthdrs cdatehdrs crows + where + [aaccts, adates, baccts, bdates] = map headerContents [aaccthdrs, adatehdrs, baccthdrs, bdatehdrs] + -- combined account names + -- TODO Can't sort these or things will fall apart. + caccts = dbg2 "caccts" $ init $ (dbg2 "aaccts" $ filter (not . null) aaccts) `union` (dbg2 "baccts" baccts) + caccthdrs = T.Group NoLine $ map Header $ caccts + -- Actual column dates and budget column dates could be different. + -- TODO Can't easily combine these preserving correct order, will go wrong on monthly reports probably. + cdates = dbg2 "cdates" $ sort $ (dbg2 "adates" adates) `union` (dbg2 "bdates" bdates) + cdatehdrs = T.Group NoLine $ map Header cdates + -- corresponding rows of combined actual and/or budget amounts + crows = [ combineRow (actualRow a) (budgetRow a) | a <- caccts ] + -- totals row + addtotalrow | no_total_ opts = id + | otherwise = (+----+ (row "" $ combineRow (actualRow "") (budgetRow ""))) + -- helpers + combineRow arow brow = + dbg1 "row" $ [(actualAmt d, budgetAmt d) | d <- cdates] + where + actualAmt date = Map.lookup date $ Map.fromList $ zip adates arow + budgetAmt date = Map.lookup date $ Map.fromList $ zip bdates brow + + actualRow acct = fromMaybe [] $ Map.lookup acct $ Map.fromList $ zip aaccts arows + budgetRow acct = fromMaybe [] $ Map.lookup acct $ Map.fromList $ zip baccts brows + -- | Given a table representing a multi-column balance report (for example, -- made using 'balanceReportAsTable'), render it in a format suitable for -- console output. renderBalanceReportTable :: ReportOpts -> Table String String MixedAmount -> String -renderBalanceReportTable ropts = +renderBalanceReportTable ropts = renderBalanceReportTable' ropts showamt where showamt | color_ ropts = cshowMixedAmountOneLineWithoutPrice | otherwise = showMixedAmountOneLineWithoutPrice - + renderBalanceReportTable' :: ReportOpts -> (a -> String) -> Table String String a -> String -renderBalanceReportTable' (ReportOpts { pretty_tables_ = pretty}) showCell = +renderBalanceReportTable' (ReportOpts { pretty_tables_ = pretty}) showamt = unlines - . addtrailingblank - . trimborder + . trimborder . lines - . render pretty id id showCell + . render pretty id id showamt . align where - addtrailingblank = (++[""]) trimborder = drop 1 . init . map (drop 1 . init) align (Table l t d) = Table l' t d where @@ -634,7 +777,7 @@ (map rowvals items) where mkDate = case balancetype_ opts of - PeriodChange -> showDateSpan + PeriodChange -> showDateSpanMonthAbbrev _ -> maybe "" (showDate . prevday) . spanEnd colheadings = map mkDate colspans ++ (if row_total_ opts then [" Total"] else []) diff --git a/Hledger/Cli/Commands/Balancesheet.hs b/Hledger/Cli/Commands/Balancesheet.hs --- a/Hledger/Cli/Commands/Balancesheet.hs +++ b/Hledger/Cli/Commands/Balancesheet.hs @@ -27,11 +27,26 @@ balances of asset and liability accounts (ignoring any report begin date). It assumes that these accounts are under a top-level `asset` or `liability` account (case insensitive, plural forms also allowed). + +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). |], cbctitle = "Balance Sheet", - cbcqueries = [ ("Assets" , journalAssetAccountQuery, Just NormalPositive), - ("Liabilities", journalLiabilityAccountQuery, Just NormalNegative) - ], + cbcqueries = [ + CBCSubreportSpec{ + cbcsubreporttitle="Assets" + ,cbcsubreportquery=journalAssetAccountQuery + ,cbcsubreportnormalsign=NormallyPositive + ,cbcsubreportincreasestotal=True + } + ,CBCSubreportSpec{ + cbcsubreporttitle="Liabilities" + ,cbcsubreportquery=journalLiabilityAccountQuery + ,cbcsubreportnormalsign=NormallyNegative + ,cbcsubreportincreasestotal=False + } + ], cbctype = HistoricalBalance } diff --git a/Hledger/Cli/Commands/Balancesheetequity.hs b/Hledger/Cli/Commands/Balancesheetequity.hs --- a/Hledger/Cli/Commands/Balancesheetequity.hs +++ b/Hledger/Cli/Commands/Balancesheetequity.hs @@ -24,12 +24,32 @@ balances of asset, liability and equity accounts (ignoring any report begin date). It assumes that these accounts are under a top-level `asset`, `liability` and `equity` account (plural forms also allowed). + +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). |], cbctitle = "Balance Sheet With Equity", - cbcqueries = [("Assets", journalAssetAccountQuery, Just NormalPositive), - ("Liabilities", journalLiabilityAccountQuery, Just NormalNegative), - ("Equity", journalEquityAccountQuery, Just NormalNegative) - ], + cbcqueries = [ + CBCSubreportSpec{ + cbcsubreporttitle="Assets" + ,cbcsubreportquery=journalAssetAccountQuery + ,cbcsubreportnormalsign=NormallyPositive + ,cbcsubreportincreasestotal=True + } + ,CBCSubreportSpec{ + cbcsubreporttitle="Liabilities" + ,cbcsubreportquery=journalLiabilityAccountQuery + ,cbcsubreportnormalsign=NormallyNegative + ,cbcsubreportincreasestotal=False + } + ,CBCSubreportSpec{ + cbcsubreporttitle="Equity" + ,cbcsubreportquery=journalEquityAccountQuery + ,cbcsubreportnormalsign=NormallyNegative + ,cbcsubreportincreasestotal=False + } + ], cbctype = HistoricalBalance } diff --git a/Hledger/Cli/Commands/Cashflow.hs b/Hledger/Cli/Commands/Cashflow.hs --- a/Hledger/Cli/Commands/Cashflow.hs +++ b/Hledger/Cli/Commands/Cashflow.hs @@ -30,9 +30,20 @@ in "cash" accounts. It assumes that these accounts are under a top-level `asset` account (case insensitive, plural forms also allowed) and do not contain `receivable` or `A/R` in their name. + +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). |], cbctitle = "Cashflow Statement", - cbcqueries = [("Cash flows", journalCashAccountQuery, Just NormalPositive)], + cbcqueries = [ + CBCSubreportSpec{ + cbcsubreporttitle="Cash flows" + ,cbcsubreportquery=journalCashAccountQuery + ,cbcsubreportnormalsign=NormallyPositive + ,cbcsubreportincreasestotal=True + } + ], cbctype = PeriodChange } diff --git a/Hledger/Cli/Commands/Close.hs b/Hledger/Cli/Commands/Close.hs new file mode 100644 --- /dev/null +++ b/Hledger/Cli/Commands/Close.hs @@ -0,0 +1,92 @@ +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE QuasiQuotes #-} + +module Hledger.Cli.Commands.Close ( + closemode + ,close +) +where + +import Data.Maybe +import Data.String.Here +import Data.Time.Calendar +import Hledger +import Hledger.Cli.CliOptions + +closemode = hledgerCommandMode + [here| close equity +Print a "closing balances" transaction that brings all accounts (or with +query arguments, just the matched accounts) to a zero (historical) balance, +followed by an opposite "opening balances" transaction that restores the +balances from zero. + +FLAGS + +The opening transaction is useful to carry over asset/liability balances +if you choose to start a new journal file, eg yearly. The closing transaction +can be a useful complement, allowing you to optionally include old files +(for more history) without disturbing the asset/liability balances +(since the closing/opening pairs cancel out). + +This command may also be useful for closing out expense/income accounts +for a period (ie "closing the books" in accounting). + +Both transactions include balance assertions for the closed/reopened accounts. +You probably shouldn't use status or realness queries (eg -C or -R) with this +command, or the balance assertions will require that query to pass. + +By default, the closing transaction is dated yesterday, with balances +calculated as of end of yesterday, and the opening transaction is dated today. +To close on some other date, use: `hledger close -e OPENINGDATE ...`. +(-p or date: can also be used, the begin date is ignored.) + +For example, carrying asset/liability balances into a new file for 2018: +``` +$ hledger close -f 2017.journal -e 2018/1/1 ^assets ^liab >>2017.journal +# cut & paste the opening transaction from 2017.journal to a new 2018.journal +# now: +$ hledger bs -f 2018.journal # correct balances +$ hledger bs -f 2018.journal -f 2017.journal # still correct +$ hledger bs -f 2017.journal not:desc:closing # must exclude closing txn +``` + +Transactions spanning the closing date may complicate matters. Eg, if +closing at end of 2017: +``` +2017/12/31 + expenses:food 1 + assets:bank:checking -1 ; date:2018/1/1 +``` + |] + [] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") + +close CliOpts{reportopts_=ropts} j = do + today <- getCurrentDay + let + ropts_ = ropts{balancetype_=HistoricalBalance, accountlistmode_=ALFlat} + q = queryFromOpts today ropts_ + openingdate = fromMaybe today $ queryEndDate False q + closingdate = addDays (-1) openingdate + (acctbals,_) = balanceReportFromMultiBalanceReport ropts_ q j + balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmountSquashPricesForDisplay b) acctbals + ps = [posting{paccount=a + ,pamount=mixed [b] + ,pbalanceassertion=Just (b,nullsourcepos) + } + |(a,_,_,mb) <- acctbals + ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb + ] + ++ [posting{paccount="equity:opening balances", pamount=balancingamt}] + nps = [posting{paccount=a + ,pamount=mixed [negate b] + ,pbalanceassertion=Just (b{aquantity=0}, nullsourcepos) + } + |(a,_,_,mb) <- acctbals + ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb + ] + ++ [posting{paccount="equity:closing balances", pamount=negate balancingamt}] + putStr $ showTransaction (nulltransaction{tdate=closingdate, tdescription="closing balances", tpostings=nps}) + putStr $ showTransaction (nulltransaction{tdate=openingdate, tdescription="opening balances", tpostings=ps}) diff --git a/Hledger/Cli/Commands/Equity.hs b/Hledger/Cli/Commands/Equity.hs deleted file mode 100644 --- a/Hledger/Cli/Commands/Equity.hs +++ /dev/null @@ -1,85 +0,0 @@ -{-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} - -module Hledger.Cli.Commands.Equity ( - equitymode - ,equity -) -where - -import Data.Maybe -import Data.String.Here -import Data.Time.Calendar -import Hledger -import Hledger.Cli.CliOptions - -equitymode = hledgerCommandMode - [here| equity -Print a "closing balances" transaction that brings all accounts (or with -query arguments, just the matched accounts) to a zero balance, followed by an -opposite "opening balances" transaction that restores the balances from zero. -Such transactions can be useful, eg, for bringing account balances across -file boundaries. - -FLAGS - -The opening balances transaction is useful to carry over -asset/liability balances if you choose to start a new journal file, -eg at the beginning of the year. - -The closing balances transaction is useful to zero out balances in -the old file, which gives you the option of reporting on both files -at once while still seeing correct balances. - -Balances are calculated, and the opening transaction is dated, as of -the report end date, which you should specify with -e or date: (and -the closing transaction is dated one day earlier). If a report end -date is not specified, it defaults to today. - -Example: -```shell -$ hledger equity -f 2015.journal -e 2016/1/1 assets liabilities >>2015.journal -# move the opening balances transaction to 2016.journal -$ hledger -f 2015.journal bal assets liabilities not:desc:closing # shows correct 2015 balances -$ hledger -f 2016.journal bal assets liabilities # shows correct 2016 balances -$ hledger -f 2015.journal -f 2016.journal bal assets liabilities # still shows correct 2016 balances -``` -Open question: how to handle txns spanning a file boundary ? Eg: -```journal -2015/12/30 * food - expenses:food:dining $10 - assets:bank:checking -$10 ; date:2016/1/4 -``` -This command might or might not have some connection to the concept of -"closing the books" in accounting. - |] - [] - [generalflagsgroup1] - [] - ([], Just $ argsFlag "[QUERY]") - -equity CliOpts{reportopts_=ropts} j = do - today <- getCurrentDay - let ropts_ = ropts{accountlistmode_=ALFlat} - q = queryFromOpts today ropts_ - (acctbals,_) = balanceReport ropts_ q j - balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmountSquashPricesForDisplay b) acctbals - ps = [posting{paccount=a - ,pamount=mixed [b] - ,pbalanceassertion=Just (b,nullsourcepos) - } - |(a,_,_,mb) <- acctbals - ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb - ] - ++ [posting{paccount="equity:opening balances", pamount=balancingamt}] - enddate = fromMaybe today $ queryEndDate (date2_ ropts_) q - nps = [posting{paccount=a - ,pamount=mixed [negate b] - ,pbalanceassertion=Just (b{aquantity=0}, nullsourcepos) - } - |(a,_,_,mb) <- acctbals - ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb - ] - ++ [posting{paccount="equity:closing balances", pamount=negate balancingamt}] - putStr $ showTransaction (nulltransaction{tdate=addDays (-1) enddate, tdescription="closing balances", tpostings=nps}) - putStr $ showTransaction (nulltransaction{tdate=enddate, tdescription="opening balances", tpostings=ps}) diff --git a/Hledger/Cli/Commands/Incomestatement.hs b/Hledger/Cli/Commands/Incomestatement.hs --- a/Hledger/Cli/Commands/Incomestatement.hs +++ b/Hledger/Cli/Commands/Incomestatement.hs @@ -27,11 +27,26 @@ and expenses during a period. It assumes that these accounts are under a top-level `revenue` or `income` or `expense` account (case insensitive, plural forms also allowed). + +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). |], cbctitle = "Income Statement", - cbcqueries = [ ("Revenues", journalIncomeAccountQuery, Just NormalNegative), - ("Expenses", journalExpenseAccountQuery, Just NormalPositive) - ], + cbcqueries = [ + CBCSubreportSpec{ + cbcsubreporttitle="Revenues" + ,cbcsubreportquery=journalIncomeAccountQuery + ,cbcsubreportnormalsign=NormallyNegative + ,cbcsubreportincreasestotal=True + } + ,CBCSubreportSpec{ + cbcsubreporttitle="Expenses" + ,cbcsubreportquery=journalExpenseAccountQuery + ,cbcsubreportnormalsign=NormallyPositive + ,cbcsubreportincreasestotal=False + } + ], cbctype = PeriodChange } diff --git a/Hledger/Cli/Commands/Print.hs b/Hledger/Cli/Commands/Print.hs --- a/Hledger/Cli/Commands/Print.hs +++ b/Hledger/Cli/Commands/Print.hs @@ -59,8 +59,9 @@ let q = queryFromOpts d ropts fmt = outputFormatFromOpts opts (render, ropts') = case fmt of - "csv" -> ((++"\n") . printCSV . entriesReportAsCsv, ropts{accountlistmode_=ALFlat}) - _ -> (entriesReportAsText opts, ropts) + "csv" -> ((++"\n") . printCSV . entriesReportAsCsv, ropts{accountlistmode_=ALFlat}) + "html" -> (const $ error' "Sorry, HTML output is not yet implemented for this kind of report.", ropts{accountlistmode_=ALFlat}) -- TODO + _ -> (entriesReportAsText opts, ropts) writeOutput opts $ render $ entriesReport ropts' q j entriesReportAsText :: CliOpts -> EntriesReport -> String diff --git a/Hledger/Cli/Commands/Register.hs b/Hledger/Cli/Commands/Register.hs --- a/Hledger/Cli/Commands/Register.hs +++ b/Hledger/Cli/Commands/Register.hs @@ -61,8 +61,9 @@ register opts@CliOpts{reportopts_=ropts} j = do d <- getCurrentDay let fmt = outputFormatFromOpts opts - render | fmt=="csv" = const ((++"\n") . printCSV . postingsReportAsCsv) - | otherwise = postingsReportAsText + render | fmt=="csv" = const ((++"\n") . printCSV . postingsReportAsCsv) + | fmt=="html" = const $ error' "Sorry, HTML output is not yet implemented for this kind of report." -- TODO + | otherwise = postingsReportAsText writeOutput opts $ render opts $ postingsReport ropts (queryFromOpts d ropts) j postingsReportAsCsv :: PostingsReport -> CSV diff --git a/Hledger/Cli/Commands/Rewrite.hs b/Hledger/Cli/Commands/Rewrite.hs --- a/Hledger/Cli/Commands/Rewrite.hs +++ b/Hledger/Cli/Commands/Rewrite.hs @@ -1,4 +1,5 @@ {-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns, QuasiQuotes #-} +{-# LANGUAGE CPP #-} module Hledger.Cli.Commands.Rewrite ( rewritemode @@ -6,7 +7,9 @@ ) where +#if !(MIN_VERSION_base(4,11,0)) import Control.Monad.Writer +#endif import Data.List (sortOn, foldl') import Data.String.Here import qualified Data.Text as T diff --git a/Hledger/Cli/CompoundBalanceCommand.hs b/Hledger/Cli/CompoundBalanceCommand.hs --- a/Hledger/Cli/CompoundBalanceCommand.hs +++ b/Hledger/Cli/CompoundBalanceCommand.hs @@ -8,16 +8,18 @@ module Hledger.Cli.CompoundBalanceCommand ( CompoundBalanceCommandSpec(..) + ,CBCSubreportSpec(..) ,compoundBalanceCommandMode ,compoundBalanceCommand ) where -import Data.List (intercalate, foldl') +import Data.List (foldl') import Data.Maybe (fromMaybe) -import Data.Monoid (Sum(..), (<>)) -import Data.Tuple.HT (uncurry3) +import qualified Data.Text as TS +import qualified Data.Text.Lazy as TL import System.Console.CmdArgs.Explicit as C import Text.CSV +import Lucid as L import Text.Tabular as T import Hledger @@ -31,17 +33,53 @@ -- each with its own title and subtotals row, in a certain order, -- plus a grand totals row if there's more than one section. -- Examples are the balancesheet, cashflow and incomestatement commands. +-- +-- Compound balance reports do sign normalisation: they show all account balances +-- as normally positive, unlike the ordinary BalanceReport and most hledger commands +-- which show income/liability/equity balances as normally negative. +-- Each subreport specifies the normal sign of its amounts, and whether +-- it should be added to or subtracted from the grand total. +-- data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec { - cbcname :: String, -- ^ command name - cbcaliases :: [String], -- ^ command aliases - cbchelp :: String, -- ^ command line help - cbctitle :: String, -- ^ overall report title - cbcqueries :: [(String, Journal -> Query, Maybe NormalBalance)], - -- ^ title, journal-parameterised query, and expected normal balance for each subreport. - -- The normal balance helps --sort-amount know how to sort negative amounts. - cbctype :: BalanceType -- ^ the type of "balance" this report shows (overrides command line flags) + cbcname :: String, -- ^ command name + cbcaliases :: [String], -- ^ command aliases + cbchelp :: String, -- ^ command line help + cbctitle :: String, -- ^ overall report title + cbcqueries :: [CBCSubreportSpec], -- ^ subreport details + cbctype :: BalanceType -- ^ the "balance" type (change, cumulative, historical) + -- this report shows (overrides command line flags) } +-- | Description of one subreport within a compound balance report. +data CBCSubreportSpec = CBCSubreportSpec { + cbcsubreporttitle :: String + ,cbcsubreportquery :: Journal -> Query + ,cbcsubreportnormalsign :: NormalSign + ,cbcsubreportincreasestotal :: Bool +} + +-- | A compound balance report has: +-- +-- * an overall title +-- +-- * the period (date span) of each column +-- +-- * one or more named, normal-positive multi balance reports, +-- with columns corresponding to the above, and a flag indicating +-- whether they increased or decreased the overall totals +-- +-- * a list of overall totals for each column, and their grand total and average +-- +-- It is used in compound balance report commands like balancesheet, +-- cashflow and incomestatement. +type CompoundBalanceReport = + ( String + , [DateSpan] + , [(String, MultiBalanceReport, Bool)] + , ([MixedAmount], MixedAmount, MixedAmount) + ) + + -- | Generate a cmdargs option-parsing mode from a compound balance command -- specification. compoundBalanceCommandMode :: CompoundBalanceCommandSpec -> Mode RawOpts @@ -68,7 +106,7 @@ ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode when displaying tables" - ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account name" + ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name" ,outputFormatFlag ,outputFileFlag ] @@ -83,7 +121,7 @@ -- | Generate a runnable command from a compound balance command specification. compoundBalanceCommand :: CompoundBalanceCommandSpec -> (CliOpts -> Journal -> IO ()) -compoundBalanceCommand CompoundBalanceCommandSpec{..} opts@CliOpts{command_=cmd, reportopts_=ropts, rawopts_=rawopts} j = do +compoundBalanceCommand CompoundBalanceCommandSpec{..} opts@CliOpts{reportopts_=ropts, rawopts_=rawopts} j = do d <- getCurrentDay let -- use the default balance type for this report, unless the user overrides @@ -94,20 +132,20 @@ "change":_ -> Just PeriodChange _ -> Nothing balancetype = fromMaybe cbctype mBalanceTypeOverride - -- when user overrides, add an indication to the report title - title = cbctitle ++ maybe "" (' ':) mtitleclarification + title = cbctitle ++ " " ++ showDateSpan requestedspan ++ maybe "" (' ':) mtitleclarification where + requestedspan = queryDateSpan (date2_ ropts) userq `spanDefaultsFrom` journalDateSpan (date2_ ropts) j + -- when user overrides, add an indication to the report title mtitleclarification = flip fmap mBalanceTypeOverride $ \t -> case t of PeriodChange -> "(Balance Changes)" CumulativeChange -> "(Cumulative Ending Balances)" HistoricalBalance -> "(Historical Ending Balances)" -- Set balance type in the report options. - -- XXX Also, use tree mode (by default, at least?) if --cumulative/--historical + -- Also, use tree mode (by default, at least?) if --cumulative/--historical -- are used in single column mode, since in that situation we will be using - -- singleBalanceReport which does not support eliding boring parents, - -- and tree mode hides this.. or something.. - -- see also compoundBalanceCommandSingleColumnReport, #565 + -- balanceReportFromMultiBalanceReport which does not support eliding boring parents, + -- and tree mode hides this.. or something.. XXX ropts' | not (flat_ ropts) && interval_ ropts==NoInterval && @@ -118,114 +156,65 @@ userq = queryFromOpts d ropts' format = outputFormatFromOpts opts - case interval_ ropts' of - - -- single-column report - -- TODO refactor, support output format like multi column - NoInterval -> do - let - -- concatenate the rendering and sum the totals from each subreport - (subreportstr, total) = - foldMap (uncurry3 (compoundBalanceCommandSingleColumnReport ropts' userq j)) cbcqueries - - writeOutput opts $ unlines $ - [title ++ "\n"] ++ - subreportstr ++ - if (no_total_ ropts' || cmd=="cashflow") - then [] - else - [ "Total:" - , "--------------------" - , padLeftWide 20 $ showamt (getSum total) - , "" - ] - where - showamt | color_ ropts' = cshowMixedAmountWithoutPrice - | otherwise = showMixedAmountWithoutPrice - - -- multi-column report - _ -> do - let - -- make a CompoundBalanceReport - namedsubreports = - map (\(subreporttitle, subreportq, subreportnormalsign) -> - (subreporttitle, compoundBalanceSubreport ropts' userq j subreportq subreportnormalsign)) - cbcqueries - subtotalrows = [coltotals | MultiBalanceReport (_,_,(coltotals,_,_)) <- map snd namedsubreports] - overalltotals = case subtotalrows of - [] -> ([], nullmixedamt, nullmixedamt) - rs -> - -- Sum the subtotals in each column. - -- A subreport might be empty and have no subtotals, count those as zeros (#588). - -- Short subtotals rows are also implicitly padded with zeros, though that is not expected to happen. - let - numcols = maximum $ map length rs -- depends on non-null ts - zeros = replicate numcols nullmixedamt - rs' = [take numcols $ as ++ repeat nullmixedamt | as <- rs] - coltotals = foldl' (zipWith (+)) zeros rs' - grandtotal = sum coltotals - grandavg | null coltotals = nullmixedamt - | otherwise = grandtotal `divideMixedAmount` fromIntegral (length coltotals) - in - (coltotals, grandtotal, grandavg) - cbr = - (title - ,namedsubreports - ,overalltotals - ) - -- render appropriately - writeOutput opts $ - case format of - "csv" -> printCSV (compoundBalanceReportAsCsv ropts cbr) ++ "\n" - _ -> compoundBalanceReportAsText ropts' cbr - --- | Run one subreport for a compound balance command in single-column mode. --- Currently this returns the plain text rendering of the subreport, and its total. --- The latter is wrapped in a Sum for easy monoidal combining. -compoundBalanceCommandSingleColumnReport - :: ReportOpts - -> Query - -> Journal - -> String - -> (Journal -> Query) - -> Maybe NormalBalance - -> ([String], Sum MixedAmount) -compoundBalanceCommandSingleColumnReport ropts userq j subreporttitle subreportqfn subreportnormalsign = - ([subreportstr], Sum total) - where - q = And [subreportqfn j, userq] - ropts' = ropts{normalbalance_=subreportnormalsign} - r@(_,total) - -- XXX For --historical/--cumulative, we must use singleBalanceReport; - -- otherwise we use balanceReport -- because it supports eliding boring parents. - -- See also compoundBalanceCommand, Balance.hs -> balance. - | balancetype_ ropts `elem` [CumulativeChange, HistoricalBalance] = singleBalanceReport ropts' q j - | otherwise = balanceReport ropts' q j - subreportstr = intercalate "\n" [subreporttitle <> ":", balanceReportAsText ropts r] + -- make a CompoundBalanceReport + subreports = + map (\CBCSubreportSpec{..} -> + (cbcsubreporttitle + ,mbrNormaliseSign cbcsubreportnormalsign $ -- <- convert normal-negative to normal-positive + compoundBalanceSubreport ropts' userq j cbcsubreportquery cbcsubreportnormalsign + ,cbcsubreportincreasestotal + )) + cbcqueries + subtotalrows = + [(coltotals, increasesoveralltotal) + | (_, MultiBalanceReport (_,_,(coltotals,_,_)), increasesoveralltotal) <- subreports + ] + -- Sum the subreport totals by column. Handle these cases: + -- - no subreports + -- - empty subreports, having no subtotals (#588) + -- - subreports with a shorter subtotals row than the others + overalltotals = case subtotalrows of + [] -> ([], nullmixedamt, nullmixedamt) + rs -> + let + numcols = maximum $ map (length.fst) rs -- partial maximum is ok, rs is non-null + paddedsignedsubtotalrows = + [map (if increasesoveralltotal then id else negate) $ -- maybe flip the signs + take numcols $ as ++ repeat nullmixedamt -- pad short rows with zeros + | (as,increasesoveralltotal) <- rs + ] + coltotals = foldl' (zipWith (+)) zeros paddedsignedsubtotalrows -- sum the columns + where zeros = replicate numcols nullmixedamt + grandtotal = sum coltotals + grandavg | null coltotals = nullmixedamt + | otherwise = grandtotal `divideMixedAmount` fromIntegral (length coltotals) + in + (coltotals, grandtotal, grandavg) + colspans = + case subreports of + (_, MultiBalanceReport (ds,_,_), _):_ -> ds + [] -> [] + cbr = + (title + ,colspans + ,subreports + ,overalltotals + ) --- | A compound balance report has: --- --- * an overall title --- --- * one or more named multi balance reports, with the same column headings --- --- * a list of overall totals for each column, and their grand total and average --- --- It is used in compound balance report commands like balancesheet, --- cashflow and incomestatement. -type CompoundBalanceReport = - ( String - , [(String, MultiBalanceReport)] - , ([MixedAmount], MixedAmount, MixedAmount) - ) + -- render appropriately + writeOutput opts $ + case format of + "csv" -> printCSV (compoundBalanceReportAsCsv ropts cbr) ++ "\n" + "html" -> (++ "\n") $ TL.unpack $ L.renderText $ compoundBalanceReportAsHtml ropts cbr + _ -> compoundBalanceReportAsText ropts' cbr -- | Run one subreport for a compound balance command in multi-column mode. -- This returns a MultiBalanceReport. -compoundBalanceSubreport :: ReportOpts -> Query -> Journal -> (Journal -> Query) -> Maybe NormalBalance -> MultiBalanceReport +compoundBalanceSubreport :: ReportOpts -> Query -> Journal -> (Journal -> Query) -> NormalSign -> MultiBalanceReport compoundBalanceSubreport ropts userq j subreportqfn subreportnormalsign = r' where -- force --empty to ensure same columns in all sections - ropts' = ropts { empty_=True, normalbalance_=subreportnormalsign } + ropts' = ropts { empty_=True, normalbalance_=Just subreportnormalsign } -- run the report q = And [subreportqfn j, userq] r@(MultiBalanceReport (dates, rows, totals)) = multiBalanceReport ropts' q j @@ -258,7 +247,7 @@ -} compoundBalanceReportAsText :: ReportOpts -> CompoundBalanceReport -> String -compoundBalanceReportAsText ropts (title, subreports, (coltotals, grandtotal, grandavg)) = +compoundBalanceReportAsText ropts (title, _colspans, subreports, (coltotals, grandtotal, grandavg)) = title ++ "\n\n" ++ renderBalanceReportTable ropts bigtable' where @@ -273,7 +262,7 @@ | otherwise = bigtable +====+ - row "Total" ( + row "Net:" ( coltotals ++ (if row_total_ ropts then [grandtotal] else []) ++ (if average_ ropts then [grandavg] else []) @@ -281,7 +270,7 @@ -- | Convert a named multi balance report to a table suitable for -- concatenating with others to make a compound balance report table. - subreportAsTable ropts singlesubreport (title, r) = t + subreportAsTable ropts singlesubreport (title, r, _) = t where -- unless there's only one section, always show the subtotal row ropts' | singlesubreport = ropts @@ -296,30 +285,25 @@ Table (T.Group DoubleLine [hLeft, hLeft']) hTop (dat ++ dat') -- | Render a compound balance report as CSV. -{- Eg: -ghci> :main -f examples/sample.journal bs -Y -O csv -AT -"Balance Sheet","","","","","" -"Assets","","","","","" -"account","short account","indent","2008","total","average" -"assets:bank:saving","saving","3","$1","$1","$1" -"assets:cash","cash","2","$-2","$-2","$-2" -"totals","","","$-1","$-1","$-1" -"Liabilities","","","","","" -"account","short account","indent","2008","total","average" -"liabilities:debts","debts","2","$1","$1","$1" -"totals","","","$1","$1","$1" -"Total","0","0","0" --} +-- Subreports' CSV is concatenated, with the headings rows replaced by a +-- subreport title row, and an overall title row, one headings row, and an +-- optional overall totals row is added. compoundBalanceReportAsCsv :: ReportOpts -> CompoundBalanceReport -> CSV -compoundBalanceReportAsCsv ropts (title, subreports, (coltotals, grandtotal, grandavg)) = +compoundBalanceReportAsCsv ropts (title, colspans, subreports, (coltotals, grandtotal, grandavg)) = addtotals $ padRow title : + ("Account" : + map showDateSpanMonthAbbrev colspans + ++ (if row_total_ ropts then ["Total"] else []) + ++ (if average_ ropts then ["Average"] else []) + ) : concatMap (subreportAsCsv ropts singlesubreport) subreports where singlesubreport = length subreports == 1 - subreportAsCsv ropts singlesubreport (subreporttitle, multibalreport) = + -- | Add a subreport title row and drop the heading row. + subreportAsCsv ropts singlesubreport (subreporttitle, multibalreport, _) = padRow subreporttitle : - multiBalanceReportAsCsv ropts' multibalreport + tail (multiBalanceReportAsCsv ropts' multibalreport) where -- unless there's only one section, always show the subtotal row ropts' | singlesubreport = ropts @@ -334,14 +318,73 @@ (if average_ ropts then (1+) else id) $ maximum $ -- depends on non-null subreports map (\(MultiBalanceReport (amtcolheadings, _, _)) -> length amtcolheadings) $ - map snd subreports + map second3 subreports addtotals | no_total_ ropts || length subreports == 1 = id | otherwise = (++ - ["Total" : + ["Net:" : map showMixedAmountOneLineWithoutPrice ( coltotals ++ (if row_total_ ropts then [grandtotal] else []) ++ (if average_ ropts then [grandavg] else []) ) ]) + +-- | Render a compound balance report as HTML. +compoundBalanceReportAsHtml :: ReportOpts -> CompoundBalanceReport -> Html () +compoundBalanceReportAsHtml ropts cbr = + let + (title, colspans, subreports, (coltotals, grandtotal, grandavg)) = cbr + colspanattr = colspan_ $ TS.pack $ show $ + 1 + length colspans + (if row_total_ ropts then 1 else 0) + (if average_ ropts then 1 else 0) + leftattr = style_ "text-align:left" + blankrow = tr_ $ td_ [colspanattr] $ toHtmlRaw (" "::String) + + titlerows = + [tr_ $ th_ [colspanattr, leftattr] $ h2_ $ toHtml title] + ++ [thRow $ + "" : + map showDateSpanMonthAbbrev colspans + ++ (if row_total_ ropts then ["Total"] else []) + ++ (if average_ ropts then ["Average"] else []) + ] + + thRow :: [String] -> Html () + thRow = tr_ . mconcat . map (th_ . toHtml) + + -- Make rows for a subreport: its title row, not the headings row, + -- the data rows, any totals row, and a blank row for whitespace. + subreportrows :: (String, MultiBalanceReport, Bool) -> [Html ()] + subreportrows (subreporttitle, mbr, _increasestotal) = + let + (_,bodyrows,mtotalsrow) = multiBalanceReportHtmlRows ropts mbr + in + [tr_ $ th_ [colspanattr, leftattr] $ toHtml subreporttitle] + ++ bodyrows + ++ maybe [] (:[]) mtotalsrow + ++ [blankrow] + + totalrows | no_total_ ropts || length subreports == 1 = [] + | otherwise = + let defstyle = style_ "text-align:right" + in + [tr_ $ mconcat $ + th_ [class_ "", style_ "text-align:left"] "Net:" + : [th_ [class_ "amount coltotal", defstyle] (toHtml $ showMixedAmountOneLineWithoutPrice a) | a <- coltotals] + ++ (if row_total_ ropts then [th_ [class_ "amount coltotal", defstyle] $ toHtml $ showMixedAmountOneLineWithoutPrice $ grandtotal] else []) + ++ (if average_ ropts then [th_ [class_ "amount colaverage", defstyle] $ toHtml $ showMixedAmountOneLineWithoutPrice $ grandavg] else []) + ] + + in do + style_ (TS.unlines ["" + ,"td { padding:0 0.5em; }" + ,"td:nth-child(1) { white-space:nowrap; }" + ,"tr:nth-child(even) td { background-color:#eee; }" + ]) + link_ [rel_ "stylesheet", href_ "hledger.css"] + table_ $ mconcat $ + titlerows + ++ [blankrow] + ++ concatMap subreportrows subreports + ++ totalrows + diff --git a/Hledger/Cli/DocFiles.hs b/Hledger/Cli/DocFiles.hs --- a/Hledger/Cli/DocFiles.hs +++ b/Hledger/Cli/DocFiles.hs @@ -35,44 +35,44 @@ docFiles :: IsString a => [(Topic, (a, a, a))] docFiles = [ ("hledger", - ($(makeRelativeToProject "hledger.1" >>= embedStringFile) - ,$(makeRelativeToProject "hledger.txt" >>= embedStringFile) - ,$(makeRelativeToProject "hledger.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger.1" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger.info" >>= embedStringFile) )) ,("hledger-ui", - ($(makeRelativeToProject ".otherdocs/hledger-ui.1" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger-ui.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger-ui.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger-ui.1" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger-ui.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger-ui.info" >>= embedStringFile) )) ,("hledger-web", - ($(makeRelativeToProject ".otherdocs/hledger-web.1" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger-web.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger-web.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger-web.1" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger-web.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger-web.info" >>= embedStringFile) )) ,("hledger-api", - ($(makeRelativeToProject ".otherdocs/hledger-api.1" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger-api.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger-api.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger-api.1" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger-api.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger-api.info" >>= embedStringFile) )) ,("journal", - ($(makeRelativeToProject ".otherdocs/hledger_journal.5" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_journal.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_journal.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger_journal.5" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_journal.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_journal.info" >>= embedStringFile) )) ,("csv", - ($(makeRelativeToProject ".otherdocs/hledger_csv.5" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_csv.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_csv.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger_csv.5" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_csv.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_csv.info" >>= embedStringFile) )) ,("timeclock", - ($(makeRelativeToProject ".otherdocs/hledger_timeclock.5" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_timeclock.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_timeclock.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger_timeclock.5" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_timeclock.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_timeclock.info" >>= embedStringFile) )) ,("timedot", - ($(makeRelativeToProject ".otherdocs/hledger_timedot.5" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_timedot.txt" >>= embedStringFile) - ,$(makeRelativeToProject ".otherdocs/hledger_timedot.info" >>= embedStringFile) + ($(makeRelativeToProject "embeddedfiles/hledger_timedot.5" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_timedot.txt" >>= embedStringFile) + ,$(makeRelativeToProject "embeddedfiles/hledger_timedot.info" >>= embedStringFile) )) ] diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs --- a/Hledger/Cli/Utils.hs +++ b/Hledger/Cli/Utils.hs @@ -249,7 +249,7 @@ -- indicating whether we did anything. writeFileWithBackupIfChanged :: FilePath -> T.Text -> IO Bool writeFileWithBackupIfChanged f t = do - s <- readFile' f + s <- readFilePortably f if t == s then return False else backUpFile f >> T.writeFile f t >> return True @@ -259,7 +259,7 @@ writeFileWithBackup f t = backUpFile f >> writeFile f t readFileStrictly :: FilePath -> IO T.Text -readFileStrictly f = readFile' f >>= \s -> C.evaluate (T.length s) >> return s +readFileStrictly f = readFilePortably f >>= \s -> C.evaluate (T.length s) >> return s -- | Back up this file with a (incrementing) numbered suffix, or give an error. backUpFile :: FilePath -> IO () diff --git a/embeddedfiles/hledger-api.1 b/embeddedfiles/hledger-api.1 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-api.1 @@ -0,0 +1,143 @@ + +.TH "hledger\-api" "1" "March 2018" "hledger\-api 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +hledger\-api \- web API server for the hledger accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\-api\ [OPTIONS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ api\ \-\-\ [OPTIONS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PP +hledger\-api is a simple web API server, intended to support +client\-side web apps operating on hledger data. +It comes with a series of simple client\-side app examples, which drive +its evolution. +.PP +Like hledger, it reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +For more about this see hledger(1), hledger_journal(5) etc. +.PP +The server listens on IP address 127.0.0.1, accessible only to local +requests, by default. +You can change this with \f[C]\-\-host\f[], eg +\f[C]\-\-host\ 0.0.0.0\f[] to listen on all addresses. +Note there is no other access control, and hledger\-api allows file +browsing, so on shared machines you will certainly need to put it behind +an authenticating proxy to restrict access. +.PP +You can change the TCP port it listens on (default: 8001) with +\f[C]\-p\ PORT\f[]. +.PP +API methods look like: +.IP +.nf +\f[C] +/api/v1/accountnames +/api/v1/transactions +/api/v1/prices +/api/v1/commodities +/api/v1/accounts +/api/v1/accounts/ACCTNAME +\f[] +.fi +.PP +See \f[C]/api/swagger.json\f[] for a full list in Swagger 2.0 format. +(Or you can run \f[C]hledger\-api\ \-\-swagger\f[] to print this in the +console.) +.PP +hledger\-api also serves files, from the current directory by default, +and the \f[C]/\f[] path will also show a directory listing. +This is convenient for serving client\-side web code, in addition to the +server\-side api. +.SH OPTIONS +.PP +Note: if invoking hledger\-api as a hledger subcommand, write +\f[C]\-\-\f[] before options as shown above. +.TP +.B \f[C]\-f\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or +\f[C]$HOME/.hledger.journal\f[]) +.RS +.RE +.TP +.B \f[C]\-d\ \-\-static\-dir=DIR\f[] +serve files from a different directory (default: \f[C]\&.\f[]) +.RS +.RE +.TP +.B \f[C]\-\-host=IPADDR\f[] +listen on this IP address (default: 127.0.0.1) +.RS +.RE +.TP +.B \f[C]\-p\ \-\-port=PORT\f[] +listen on this TCP port (default: 8001) +.RS +.RE +.TP +.B \f[C]\-\-swagger\f[] +print API docs in Swagger 2.0 format, and exit +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version +.RS +.RE +.TP +.B \f[C]\-h\ \-\-help\f[] +show usage +.RS +.RE +.SH ENVIRONMENT +.PP +\f[B]LEDGER_FILE\f[] The journal file path when not specified with +\f[C]\-f\f[]. +Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps +\f[C]C:/Users/USER/.hledger.journal\f[]). +.SH FILES +.PP +Reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger-api.info b/embeddedfiles/hledger-api.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-api.info @@ -0,0 +1,86 @@ +This is hledger-api.info, produced by makeinfo version 6.5 from stdin. + + +File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir) + +hledger-api(1) hledger-api 1.9 +****************************** + +hledger-api is a simple web API server, intended to support client-side +web apps operating on hledger data. It comes with a series of simple +client-side app examples, which drive its evolution. + + Like hledger, it reads data from one or more files in hledger +journal, timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), +hledger_journal(5) etc. + + The server listens on IP address 127.0.0.1, accessible only to local +requests, by default. You can change this with '--host', eg '--host +0.0.0.0' to listen on all addresses. Note there is no other access +control, and hledger-api allows file browsing, so on shared machines you +will certainly need to put it behind an authenticating proxy to restrict +access. + + You can change the TCP port it listens on (default: 8001) with '-p +PORT'. + + API methods look like: + +/api/v1/accountnames +/api/v1/transactions +/api/v1/prices +/api/v1/commodities +/api/v1/accounts +/api/v1/accounts/ACCTNAME + + See '/api/swagger.json' for a full list in Swagger 2.0 format. (Or +you can run 'hledger-api --swagger' to print this in the console.) + + hledger-api also serves files, from the current directory by default, +and the '/' path will also show a directory listing. This is convenient +for serving client-side web code, in addition to the server-side api. +* Menu: + +* OPTIONS:: + + +File: hledger-api.info, Node: OPTIONS, Prev: Top, Up: Top + +1 OPTIONS +********* + +Note: if invoking hledger-api as a hledger subcommand, write '--' before +options as shown above. + +'-f --file=FILE' + + use a different input file. For stdin, use - (default: + '$LEDGER_FILE' or '$HOME/.hledger.journal') +'-d --static-dir=DIR' + + serve files from a different directory (default: '.') +'--host=IPADDR' + + listen on this IP address (default: 127.0.0.1) +'-p --port=PORT' + + listen on this TCP port (default: 8001) +'--swagger' + + print API docs in Swagger 2.0 format, and exit +'--version' + + show version +'-h --help' + + show usage + + +Tag Table: +Node: Top72 +Node: OPTIONS1658 +Ref: #options1743 + +End Tag Table diff --git a/embeddedfiles/hledger-api.txt b/embeddedfiles/hledger-api.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-api.txt @@ -0,0 +1,120 @@ + +hledger-api(1) hledger User Manuals hledger-api(1) + + + +NAME + hledger-api - web API server for the hledger accounting tool + +SYNOPSIS + hledger-api [OPTIONS] + hledger api -- [OPTIONS] + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any + other commodity, using double-entry accounting and a simple, editable + file format. hledger is inspired by and largely compatible with + ledger(1). + + hledger-api is a simple web API server, intended to support client-side + web apps operating on hledger data. It comes with a series of simple + client-side app examples, which drive its evolution. + + Like hledger, it reads data from one or more files in hledger journal, + timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, + or $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). For more about this see hledger(1), + hledger_journal(5) etc. + + The server listens on IP address 127.0.0.1, accessible only to local + requests, by default. You can change this with --host, eg + --host 0.0.0.0 to listen on all addresses. Note there is no other + access control, and hledger-api allows file browsing, so on shared + machines you will certainly need to put it behind an authenticating + proxy to restrict access. + + You can change the TCP port it listens on (default: 8001) with -p PORT. + + API methods look like: + + /api/v1/accountnames + /api/v1/transactions + /api/v1/prices + /api/v1/commodities + /api/v1/accounts + /api/v1/accounts/ACCTNAME + + See /api/swagger.json for a full list in Swagger 2.0 format. (Or you + can run hledger-api --swagger to print this in the console.) + + hledger-api also serves files, from the current directory by default, + and the / path will also show a directory listing. This is convenient + for serving client-side web code, in addition to the server-side api. + +OPTIONS + Note: if invoking hledger-api as a hledger subcommand, write -- before + options as shown above. + + -f --file=FILE + use a different input file. For stdin, use - (default: + $LEDGER_FILE or $HOME/.hledger.journal) + + -d --static-dir=DIR + serve files from a different directory (default: .) + + --host=IPADDR + listen on this IP address (default: 127.0.0.1) + + -p --port=PORT + listen on this TCP port (default: 8001) + + --swagger + print API docs in Swagger 2.0 format, and exit + + --version + show version + + -h --help + show usage + +ENVIRONMENT + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede options with -- when invoked from hledger is awk- + ward. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger-api 1.9 March 2018 hledger-api(1) diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-ui.1 @@ -0,0 +1,486 @@ + +.TH "hledger\-ui" "1" "March 2018" "hledger\-ui 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +hledger\-ui \- curses\-style interface for the hledger accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PP +hledger\-ui is hledger's curses\-style interface, providing an efficient +full\-window text UI for viewing accounts and transactions, and some +limited data entry capability. +It is easier than hledger's command\-line interface, and sometimes +quicker and more convenient than the web interface. +.PP +Like hledger, it reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +For more about this see hledger(1), hledger_journal(5) etc. +.SH OPTIONS +.PP +Note: if invoking hledger\-ui as a hledger subcommand, write +\f[C]\-\-\f[] before options as shown above. +.PP +Any QUERYARGS are interpreted as a hledger search query which filters +the data. +.TP +.B \f[C]\-\-watch\f[] +watch for data and date changes and reload automatically +.RS +.RE +.TP +.B \f[C]\-\-theme=default|terminal|greenterm\f[] +use this custom display theme +.RS +.RE +.TP +.B \f[C]\-\-register=ACCTREGEX\f[] +start in the (first) matched account's register screen +.RS +.RE +.TP +.B \f[C]\-\-change\f[] +show period balances (changes) at startup instead of historical balances +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show full account names, unindented +.RS +.RE +.PP +hledger input options: +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or +\f[C]$HOME/.hledger.journal\f[]) +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +rename accounts named OLD to NEW +.RS +.RE +.TP +.B \f[C]\-\-anon\f[] +anonymize accounts and payees +.RS +.RE +.TP +.B \f[C]\-\-pivot\ FIELDNAME\f[] +use some other field or tag for the account name +.RS +.RE +.TP +.B \f[C]\-I\ \-\-ignore\-assertions\f[] +ignore any failing balance assertions +.RS +.RE +.PP +hledger reporting options: +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once using +period expressions syntax (overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\f[] +match the secondary date instead (see command help for other effects) +.RS +.RE +.TP +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) +.RS +.RE +.TP +.B \f[C]\-P\ \-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-NUM\ \-\-depth=NUM\f[] +hide/aggregate accounts or postings more than NUM levels deep +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show items with zero amount, normally hidden (and vice\-versa in +hledger\-ui/hledger\-web) +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +convert amounts to their cost at transaction time (using the transaction +price, if any) +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +convert amounts to their market value on the report end date (using the +most recent applicable market price, if any) +.RS +.RE +.TP +.B \f[C]\-\-auto\f[] +apply automated posting rules to modify transactions. +.RS +.RE +.TP +.B \f[C]\-\-forecast\f[] +apply periodic transaction rules to generate future transactions, to 6 +months from now or report end date. +.RS +.RE +.PP +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 +.B \f[C]\-h\ \-\-help\f[] +show general usage (or after COMMAND, command usage) +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version +.RS +.RE +.TP +.B \f[C]\-\-debug[=N]\f[] +show debug output (levels 1\-9, default: 1) +.RS +.RE +.PP +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 \f[C]\-\-\f[] argument before.) +.SH KEYS +.PP +\f[C]?\f[] shows a help dialog listing all keys. +(Some of these also appear in the quick help at the bottom of each +screen.) Press \f[C]?\f[] again (or \f[C]ESCAPE\f[], or \f[C]LEFT\f[]) +to close it. +The following keys work on most screens: +.PP +The cursor keys navigate: \f[C]right\f[] (or \f[C]enter\f[]) goes +deeper, \f[C]left\f[] returns to the previous screen, +\f[C]up\f[]/\f[C]down\f[]/\f[C]page\ up\f[]/\f[C]page\ down\f[]/\f[C]home\f[]/\f[C]end\f[] +move up and down through lists. +Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style +(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[]) +movement keys are also supported. +A tip: movement speed is limited by your keyboard repeat rate, to move +faster you may want to adjust it. +(If you're on a mac, the Karabiner app is one way to do that.) +.PP +With shift pressed, the cursor keys adjust the report period, limiting +the transactions to be shown (by default, all are shown). +\f[C]shift\-down/up\f[] steps downward and upward through these standard +report period durations: year, quarter, month, week, day. +Then, \f[C]shift\-left/right\f[] moves to the previous/next period. +\f[C]t\f[] sets the report period to today. +With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq] +period (the current day, week, month, quarter, or year), the period will +move automatically to track the current date. +To set a non\-standard period, you can use \f[C]/\f[] and a +\f[C]date:\f[] query. +.PP +\f[C]/\f[] lets you set a general filter query limiting the data shown, +using the same query terms as in hledger and hledger\-web. +While editing the query, you can use CTRL\-a/e/d/k, BS, cursor keys; +press \f[C]ENTER\f[] to set it, or \f[C]ESCAPE\f[]to cancel. +There are also keys for quickly adjusting some common filters like +account depth and transaction status (see below). +\f[C]BACKSPACE\f[] or \f[C]DELETE\f[] removes all filters, showing all +transactions. +.PP +\f[C]ESCAPE\f[] removes all filters and jumps back to the top screen. +Or, it cancels a minibuffer edit or help dialog in progress. +.PP +\f[C]CTRL\-l\f[] redraws the screen and centers the selection if +possible (selections near the top won't be centered, since we don't +scroll above the top). +.PP +\f[C]g\f[] reloads from the data file(s) and updates the current screen +and any previous screens. +(With large files, this could cause a noticeable pause.) +.PP +\f[C]I\f[] toggles balance assertion checking. +Disabling balance assertions temporarily can be useful for +troubleshooting. +.PP +\f[C]a\f[] runs command\-line hledger's add command, and reloads the +updated file. +This allows some basic data entry. +.PP +\f[C]A\f[] is like \f[C]a\f[], but runs the hledger\-iadd tool, which +provides a curses\-style interface. +This key will be available if \f[C]hledger\-iadd\f[] is installed in +$PATH. +.PP +\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default +(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file. +With some editors (emacs, vi), the cursor will be positioned at the +current transaction when invoked from the register and transaction +screens, and at the error location (if possible) when invoked from the +error screen. +.PP +\f[C]q\f[] quits the application. +.PP +Additional screen\-specific keys are described below. +.SH SCREENS +.SS Accounts screen +.PP +This is normally the first screen displayed. +It lists accounts and their balances, like hledger's balance command. +By default, it shows all accounts and their latest ending balances +(including the balances of subaccounts). +if you specify a query on the command line, it shows just the matched +accounts and the balances from matched transactions. +.PP +Account names are normally indented to show the hierarchy (tree mode). +To see less detail, set a depth limit by pressing a number key, +\f[C]1\f[] to \f[C]9\f[]. +\f[C]0\f[] shows even less detail, collapsing all accounts to a single +total. +\f[C]\-\f[] and \f[C]+\f[] (or \f[C]=\f[]) decrease and increase the +depth limit. +To remove the depth limit, set it higher than the maximum account depth, +or press \f[C]ESCAPE\f[]. +.PP +\f[C]F\f[] toggles flat mode, in which accounts are shown as a flat +list, with their full names. +In this mode, account balances exclude subaccounts, except for accounts +at the depth limit (as with hledger's balance command). +.PP +\f[C]H\f[] toggles between showing historical balances or period +balances. +Historical balances (the default) are ending balances at the end of the +report period, taking into account all transactions before that date +(filtered by the filter query if any), including transactions before the +start of the report period. +In other words, historical balances are what you would see on a bank +statement for that account (unless disturbed by a filter query). +Period balances ignore transactions before the report start date, so +they show the change in balance during the report period. +They are more useful eg when viewing a time log. +.PP +\f[C]U\f[] toggles filtering by unmarked status, including or excluding +unmarked postings in the balances. +Similarly, \f[C]P\f[] toggles pending postings, and \f[C]C\f[] toggles +cleared postings. +(By default, balances include all postings; if you activate one or two +status filters, only those postings are included; and if you activate +all three, the filter is removed.) +.PP +\f[C]R\f[] toggles real mode, in which virtual postings are ignored. +.PP +\f[C]Z\f[] toggles nonzero mode, in which only accounts with nonzero +balances are shown (hledger\-ui shows zero items by default, unlike +command\-line hledger). +.PP +Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions +register. +.SS Register screen +.PP +This screen shows the transactions affecting a particular account, like +a check register. +Each line represents one transaction and shows: +.IP \[bu] 2 +the other account(s) involved, in abbreviated form. +(If there are both real and virtual postings, it shows only the accounts +affected by real postings.) +.IP \[bu] 2 +the overall change to the current account's balance; positive for an +inflow to this account, negative for an outflow. +.IP \[bu] 2 +the running historical total or period total for the current account, +after the transaction. +This can be toggled with \f[C]H\f[]. +Similar to the accounts screen, the historical total is affected by +transactions (filtered by the filter query) before the report start +date, while the period total is not. +If the historical total is not disturbed by a filter query, it will be +the running historical balance you would see on a bank register for the +current account. +.PP +If the accounts screen was in tree mode, the register screen will +include transactions from both the current account and its subaccounts. +If the accounts screen was in flat mode, and a non\-depth\-clipped +account was selected, the register screen will exclude transactions from +subaccounts. +In other words, the register always shows the transactions responsible +for the period balance shown on the accounts screen. +As on the accounts screen, this can be toggled with \f[C]F\f[]. +.PP +\f[C]U\f[] toggles filtering by unmarked status, showing or hiding +unmarked transactions. +Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[] +toggles cleared transactions. +(By default, transactions with all statuses are shown; if you activate +one or two status filters, only those transactions are shown; and if you +activate all three, the filter is removed.)q +.PP +\f[C]R\f[] toggles real mode, in which virtual postings are ignored. +.PP +\f[C]Z\f[] toggles nonzero mode, in which only transactions posting a +nonzero change are shown (hledger\-ui shows zero items by default, +unlike command\-line hledger). +.PP +Press \f[C]right\f[] (or \f[C]enter\f[]) to view the selected +transaction in detail. +.SS Transaction screen +.PP +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format +(hledger_journal(5)). +.PP +The transaction's date(s) and any cleared flag, transaction code, +description, comments, along with all of its account postings are shown. +Simple transactions have two postings, but there can be more (or in +certain cases, fewer). +.PP +\f[C]up\f[] and \f[C]down\f[] will step through all transactions listed +in the previous account register screen. +In the title bar, the numbers in parentheses show your position within +that account register. +They will vary depending on which account register you came from +(remember most transactions appear in multiple account registers). +The #N number preceding them is the transaction's position within the +complete unfiltered journal, which is a more stable id (at least until +the next reload). +.SS Error screen +.PP +This screen will appear if there is a problem, such as a parse error, +when you press g to reload. +Once you have fixed the problem, press g again to reload and resume +normal operation. +(Or, you can press escape to cancel the reload attempt.) +.SH ENVIRONMENT +.PP +\f[B]COLUMNS\f[] The screen width to use. +Default: the full terminal width. +.PP +\f[B]LEDGER_FILE\f[] The journal file path when not specified with +\f[C]\-f\f[]. +Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps +\f[C]C:/Users/USER/.hledger.journal\f[]). +.SH FILES +.PP +Reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. +.PP +\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin). +.PP +\f[C]\-V\f[] affects only the accounts screen. +.PP +When you press \f[C]g\f[], the current and all previous screens are +regenerated, which may cause a noticeable pause with large files. +Also there is no visual indication that this is in progress. +.PP +\f[C]\-\-watch\f[] is not yet fully robust. +It works well for normal usage, but many file changes in a short time +(eg saving the file thousands of times with an editor macro) can cause +problems at least on OSX. +Symptoms include: unresponsive UI, periodic resetting of the cursor +position, momentary display of parse errors, high CPU usage eventually +subsiding, and possibly a small but persistent build\-up of CPU usage +until the program is restarted. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-ui.info @@ -0,0 +1,395 @@ +This is hledger-ui.info, produced by makeinfo version 6.5 from stdin. + + +File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) + +hledger-ui(1) hledger-ui 1.9 +**************************** + +hledger-ui is hledger's curses-style interface, providing an efficient +full-window text UI for viewing accounts and transactions, and some +limited data entry capability. It is easier than hledger's command-line +interface, and sometimes quicker and more convenient than the web +interface. + + Like hledger, it reads data from one or more files in hledger +journal, timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), +hledger_journal(5) etc. +* Menu: + +* OPTIONS:: +* KEYS:: +* SCREENS:: + + +File: hledger-ui.info, Node: OPTIONS, Next: KEYS, 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 +the data. + +'--watch' + + watch for data and date changes and reload automatically +'--theme=default|terminal|greenterm' + + use this custom display theme +'--register=ACCTREGEX' + + start in the (first) matched account's register screen +'--change' + + show period balances (changes) at startup instead of historical + balances +'--flat' + + show full account names, unindented + + hledger 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: FILE.rules) +'--alias=OLD=NEW' + + rename accounts named OLD to NEW +'--anon' + + anonymize accounts and payees +'--pivot FIELDNAME' + + use some other field or tag for the account name +'-I --ignore-assertions' + + ignore any failing balance assertions + + hledger reporting options: + +'-b --begin=DATE' + + include postings/txns on or after this date +'-e --end=DATE' + + include postings/txns before this date +'-D --daily' + + multiperiod/multicolumn report by day +'-W --weekly' + + multiperiod/multicolumn report by week +'-M --monthly' + + multiperiod/multicolumn report by month +'-Q --quarterly' + + multiperiod/multicolumn report by quarter +'-Y --yearly' + + multiperiod/multicolumn report by year +'-p --period=PERIODEXP' + + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) +'--date2' + + match the secondary date instead (see command help for other + effects) +'-U --unmarked' + + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' + + include only pending postings/txns +'-C --cleared' + + include only cleared postings/txns +'-R --real' + + include only non-virtual postings +'-NUM --depth=NUM' + + hide/aggregate accounts or postings more than NUM levels deep +'-E --empty' + + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) +'-B --cost' + + convert amounts to their cost at transaction time (using the + transaction price, if any) +'-V --value' + + convert amounts to their market value on the report end date (using + the most recent applicable market price, if any) +'--auto' + + apply automated posting rules to modify transactions. +'--forecast' + + apply periodic transaction rules to generate future transactions, + to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, +the last one takes precedence. + + Some reporting options can also be written as query arguments. + + hledger help options: + +'-h --help' + + show general usage (or after COMMAND, command usage) +'--version' + + show 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: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top + +2 KEYS +****** + +'?' shows a help dialog listing all keys. (Some of these also appear in +the quick help at the bottom of each screen.) Press '?' again (or +'ESCAPE', or 'LEFT') to close it. The following keys work on most +screens: + + The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' +returns to the previous screen, 'up'/'down'/'page up'/'page +down'/'home'/'end' move up and down through lists. Vi-style +('h'/'j'/'k'/'l') and Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') +movement keys are also supported. A tip: movement speed is limited by +your keyboard repeat rate, to move faster you may want to adjust it. +(If you're on a mac, the Karabiner app is one way to do that.) + + With shift pressed, the cursor keys adjust the report period, +limiting the transactions to be shown (by default, all are shown). +'shift-down/up' steps downward and upward through these standard report +period durations: year, quarter, month, week, day. Then, +'shift-left/right' moves to the previous/next period. 't' sets the +report period to today. With the '--watch' option, when viewing a +"current" period (the current day, week, month, quarter, or year), the +period will move automatically to track the current date. To set a +non-standard period, you can use '/' and a 'date:' query. + + '/' lets you set a general filter query limiting the data shown, +using the same query terms as in hledger and hledger-web. While editing +the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to +set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting +some common filters like account depth and transaction status (see +below). 'BACKSPACE' or 'DELETE' removes all filters, showing all +transactions. + + 'ESCAPE' removes all filters and jumps back to the top screen. Or, +it cancels a minibuffer edit or help dialog in progress. + + 'CTRL-l' redraws the screen and centers the selection if possible +(selections near the top won't be centered, since we don't scroll above +the top). + + 'g' reloads from the data file(s) and updates the current screen and +any previous screens. (With large files, this could cause a noticeable +pause.) + + 'I' toggles balance assertion checking. Disabling balance assertions +temporarily can be useful for troubleshooting. + + 'a' runs command-line hledger's add command, and reloads the updated +file. This allows some basic data entry. + + 'A' is like 'a', but runs the hledger-iadd tool, which provides a +curses-style interface. This key will be available if 'hledger-iadd' is +installed in $PATH. + + 'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient +-a "" -nw') on the journal file. With some editors (emacs, vi), the +cursor will be positioned at the current transaction when invoked from +the register and transaction screens, and at the error location (if +possible) when invoked from the error screen. + + 'q' quits the application. + + Additional screen-specific keys are described below. + + +File: hledger-ui.info, Node: SCREENS, Prev: KEYS, Up: Top + +3 SCREENS +********* + +* Menu: + +* Accounts screen:: +* Register screen:: +* Transaction screen:: +* Error screen:: + + +File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCREENS + +3.1 Accounts screen +=================== + +This is normally the first screen displayed. It lists accounts and +their balances, like hledger's balance command. By default, it shows +all accounts and their latest ending balances (including the balances of +subaccounts). if you specify a query on the command line, it shows just +the matched accounts and the balances from matched transactions. + + Account names are normally indented to show the hierarchy (tree +mode). To see less detail, set a depth limit by pressing a number key, +'1' to '9'. '0' shows even less detail, collapsing all accounts to a +single total. '-' and '+' (or '=') decrease and increase the depth +limit. To remove the depth limit, set it higher than the maximum +account depth, or press 'ESCAPE'. + + 'F' toggles flat mode, in which accounts are shown as a flat list, +with their full names. In this mode, account balances exclude +subaccounts, except for accounts at the depth limit (as with hledger's +balance command). + + 'H' toggles between showing historical balances or period balances. +Historical balances (the default) are ending balances at the end of the +report period, taking into account all transactions before that date +(filtered by the filter query if any), including transactions before the +start of the report period. In other words, historical balances are +what you would see on a bank statement for that account (unless +disturbed by a filter query). Period balances ignore transactions +before the report start date, so they show the change in balance during +the report period. They are more useful eg when viewing a time log. + + 'U' toggles filtering by unmarked status, including or excluding +unmarked postings in the balances. Similarly, 'P' toggles pending +postings, and 'C' toggles cleared postings. (By default, balances +include all postings; if you activate one or two status filters, only +those postings are included; and if you activate all three, the filter +is removed.) + + 'R' toggles real mode, in which virtual postings are ignored. + + 'Z' toggles nonzero mode, in which only accounts with nonzero +balances are shown (hledger-ui shows zero items by default, unlike +command-line hledger). + + Press 'right' or 'enter' to view an account's transactions register. + + +File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS + +3.2 Register screen +=================== + +This screen shows the transactions affecting a particular account, like +a check register. Each line represents one transaction and shows: + + * the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected + by real postings.) + + * the overall change to the current account's balance; positive for + an inflow to this account, negative for an outflow. + + * the running historical total or period total for the current + account, after the transaction. This can be toggled with 'H'. + Similar to the accounts screen, the historical total is affected by + transactions (filtered by the filter query) before the report start + date, while the period total is not. If the historical total is + not disturbed by a filter query, it will be the running historical + balance you would see on a bank register for the current account. + + If the accounts screen was in tree mode, the register screen will +include transactions from both the current account and its subaccounts. +If the accounts screen was in flat mode, and a non-depth-clipped account +was selected, the register screen will exclude transactions from +subaccounts. In other words, the register always shows the transactions +responsible for the period balance shown on the accounts screen. As on +the accounts screen, this can be toggled with 'F'. + + 'U' toggles filtering by unmarked status, showing or hiding unmarked +transactions. Similarly, 'P' toggles pending transactions, and 'C' +toggles cleared transactions. (By default, transactions with all +statuses are shown; if you activate one or two status filters, only +those transactions are shown; and if you activate all three, the filter +is removed.)q + + 'R' toggles real mode, in which virtual postings are ignored. + + 'Z' toggles nonzero mode, in which only transactions posting a +nonzero change are shown (hledger-ui shows zero items by default, unlike +command-line hledger). + + Press 'right' (or 'enter') to view the selected transaction in +detail. + + +File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS + +3.3 Transaction screen +====================== + +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format +(hledger_journal(5)). + + The transaction's date(s) and any cleared flag, transaction code, +description, comments, along with all of its account postings are shown. +Simple transactions have two postings, but there can be more (or in +certain cases, fewer). + + 'up' and 'down' will step through all transactions listed in the +previous account register screen. In the title bar, the numbers in +parentheses show your position within that account register. They will +vary depending on which account register you came from (remember most +transactions appear in multiple account registers). The #N number +preceding them is the transaction's position within the complete +unfiltered journal, which is a more stable id (at least until the next +reload). + + +File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS + +3.4 Error screen +================ + +This screen will appear if there is a problem, such as a parse error, +when you press g to reload. Once you have fixed the problem, press g +again to reload and resume normal operation. (Or, you can press escape +to cancel the reload attempt.) + + +Tag Table: +Node: Top71 +Node: OPTIONS821 +Ref: #options918 +Node: KEYS4135 +Ref: #keys4230 +Node: SCREENS7189 +Ref: #screens7274 +Node: Accounts screen7364 +Ref: #accounts-screen7492 +Node: Register screen9722 +Ref: #register-screen9877 +Node: Transaction screen11951 +Ref: #transaction-screen12109 +Node: Error screen12979 +Ref: #error-screen13101 + +End Tag Table diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-ui.txt @@ -0,0 +1,387 @@ + +hledger-ui(1) hledger User Manuals hledger-ui(1) + + + +NAME + hledger-ui - curses-style interface for the hledger accounting tool + +SYNOPSIS + hledger-ui [OPTIONS] [QUERYARGS] + hledger ui -- [OPTIONS] [QUERYARGS] + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any + other commodity, using double-entry accounting and a simple, editable + file format. hledger is inspired by and largely compatible with + ledger(1). + + hledger-ui is hledger's curses-style interface, providing an efficient + full-window text UI for viewing accounts and transactions, and some + limited data entry capability. It is easier than hledger's com- + mand-line interface, and sometimes quicker and more convenient than the + web interface. + + Like hledger, it reads data from one or more files in hledger journal, + timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, + or $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). For more about this see hledger(1), + hledger_journal(5) etc. + +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 + the data. + + --watch + watch for data and date changes and reload automatically + + --theme=default|terminal|greenterm + use this custom display theme + + --register=ACCTREGEX + start in the (first) matched account's register screen + + --change + show period balances (changes) at startup instead of historical + balances + + --flat show full account names, unindented + + hledger 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: + FILE.rules) + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot FIELDNAME + use some other field or tag for the account name + + -I --ignore-assertions + ignore any failing balance assertions + + hledger reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) + + --date2 + match the secondary date instead (see command help for other + effects) + + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) + + -P --pending + include only pending postings/txns + + -C --cleared + include only cleared postings/txns + + -R --real + include only non-virtual postings + + -NUM --depth=NUM + hide/aggregate accounts or postings more than NUM levels deep + + -E --empty + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + --auto apply automated posting rules to modify transactions. + + --forecast + apply periodic transaction rules to generate future transac- + tions, to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, the + last one takes precedence. + + Some reporting options can also be written as query arguments. + + hledger help options: + + -h --help + show general usage (or after COMMAND, command usage) + + --version + show 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.) + +KEYS + ? shows a help dialog listing all keys. (Some of these also appear in + the quick help at the bottom of each screen.) Press ? again (or ESCAPE, + or LEFT) to close it. The following keys work on most screens: + + The cursor keys navigate: right (or enter) goes deeper, left returns to + the previous screen, up/down/page up/page down/home/end move up and + down through lists. Vi-style (h/j/k/l) and Emacs-style + (CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: + movement speed is limited by your keyboard repeat rate, to move faster + you may want to adjust it. (If you're on a mac, the Karabiner app is + one way to do that.) + + With shift pressed, the cursor keys adjust the report period, limiting + the transactions to be shown (by default, all are shown). + shift-down/up steps downward and upward through these standard report + period durations: year, quarter, month, week, day. Then, + shift-left/right moves to the previous/next period. t sets the report + period to today. With the --watch option, when viewing a "current" + period (the current day, week, month, quarter, or year), the period + will move automatically to track the current date. To set a non-stan- + dard period, you can use / and a date: query. + + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + it, or ESCAPEto cancel. There are also keys for quickly adjusting some + common filters like account depth and transaction status (see below). + BACKSPACE or DELETE removes all filters, showing all transactions. + + ESCAPE removes all filters and jumps back to the top screen. Or, it + cancels a minibuffer edit or help dialog in progress. + + CTRL-l redraws the screen and centers the selection if possible (selec- + tions near the top won't be centered, since we don't scroll above the + top). + + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable + pause.) + + I toggles balance assertion checking. Disabling balance assertions + temporarily can be useful for troubleshooting. + + a runs command-line hledger's add command, and reloads the updated + file. This allows some basic data entry. + + A is like a, but runs the hledger-iadd tool, which provides a + curses-style interface. This key will be available if hledger-iadd is + installed in $PATH. + + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- + sclient -a "" -nw) on the journal file. With some editors (emacs, vi), + the cursor will be positioned at the current transaction when invoked + from the register and transaction screens, and at the error location + (if possible) when invoked from the error screen. + + q quits the application. + + Additional screen-specific keys are described below. + +SCREENS + Accounts screen + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). if you specify a query on the command line, it shows + just the matched accounts and the balances from matched transactions. + + Account names are normally indented to show the hierarchy (tree mode). + To see less detail, set a depth limit by pressing a number key, 1 to 9. + 0 shows even less detail, collapsing all accounts to a single total. - + and + (or =) decrease and increase the depth limit. To remove the + depth limit, set it higher than the maximum account depth, or press + ESCAPE. + + F toggles flat mode, in which accounts are shown as a flat list, with + their full names. In this mode, account balances exclude subaccounts, + except for accounts at the depth limit (as with hledger's balance com- + mand). + + H toggles between showing historical balances or period balances. His- + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions + before the report start date, so they show the change in balance during + the report period. They are more useful eg when viewing a time log. + + U toggles filtering by unmarked status, including or excluding unmarked + postings in the balances. Similarly, P toggles pending postings, and C + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are + included; and if you activate all three, the filter is removed.) + + R toggles real mode, in which virtual postings are ignored. + + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line + hledger). + + Press right or enter to view an account's transactions register. + + Register screen + This screen shows the transactions affecting a particular account, like + a check register. Each line represents one transaction and shows: + + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected + by real postings.) + + o the overall change to the current account's balance; positive for an + inflow to this account, negative for an outflow. + + o the running historical total or period total for the current account, + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while + the period total is not. If the historical total is not disturbed by + a filter query, it will be the running historical balance you would + see on a bank register for the current account. + + If the accounts screen was in tree mode, the register screen will + include transactions from both the current account and its subaccounts. + If the accounts screen was in flat mode, and a non-depth-clipped + account was selected, the register screen will exclude transactions + from subaccounts. In other words, the register always shows the trans- + actions responsible for the period balance shown on the accounts + screen. As on the accounts screen, this can be toggled with F. + + U toggles filtering by unmarked status, showing or hiding unmarked + transactions. Similarly, P toggles pending transactions, and C toggles + cleared transactions. (By default, transactions with all statuses are + shown; if you activate one or two status filters, only those transac- + tions are shown; and if you activate all three, the filter is + removed.)q + + R toggles real mode, in which virtual postings are ignored. + + Z toggles nonzero mode, in which only transactions posting a nonzero + change are shown (hledger-ui shows zero items by default, unlike com- + mand-line hledger). + + Press right (or enter) to view the selected transaction in detail. + + Transaction screen + This screen shows a single transaction, as a general journal entry, + similar to hledger's print command and journal format (hledger_jour- + nal(5)). + + The transaction's date(s) and any cleared flag, transaction code, + description, comments, along with all of its account postings are + shown. Simple transactions have two postings, but there can be more + (or in certain cases, fewer). + + up and down will step through all transactions listed in the previous + account register screen. In the title bar, the numbers in parentheses + show your position within that account register. They will vary + depending on which account register you came from (remember most trans- + actions appear in multiple account registers). The #N number preceding + them is the transaction's position within the complete unfiltered jour- + nal, which is a more stable id (at least until the next reload). + + Error screen + This screen will appear if there is a problem, such as a parse error, + when you press g to reload. Once you have fixed the problem, press g + again to reload and resume normal operation. (Or, you can press escape + to cancel the reload attempt.) + +ENVIRONMENT + COLUMNS The screen width to use. Default: the full terminal width. + + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede options with -- when invoked from hledger is awk- + ward. + + -f- doesn't work (hledger-ui can't read from stdin). + + -V affects only the accounts screen. + + When you press g, the current and all previous screens are regenerated, + which may cause a noticeable pause with large files. Also there is no + visual indication that this is in progress. + + --watch is not yet fully robust. It works well for normal usage, but + many file changes in a short time (eg saving the file thousands of + times with an editor macro) can cause problems at least on OSX. Symp- + toms include: unresponsive UI, periodic resetting of the cursor posi- + tion, momentary display of parse errors, high CPU usage eventually sub- + siding, and possibly a small but persistent build-up of CPU usage until + the program is restarted. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger-ui 1.9 March 2018 hledger-ui(1) diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-web.1 @@ -0,0 +1,327 @@ + +.TH "hledger\-web" "1" "March 2018" "hledger\-web 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +hledger\-web \- web interface for the hledger accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\-web\ [OPTIONS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PP +hledger\-web is hledger's web interface. +It starts a simple web application for browsing and adding transactions, +and optionally opens it in a web browser window if possible. +It provides a more user\-friendly UI than the hledger CLI or hledger\-ui +interface, showing more at once (accounts, the current account register, +balance charts) and allowing history\-aware data entry, interactive +searching, and bookmarking. +.PP +hledger\-web also lets you share a ledger with multiple users, or even +the public web. +There is no access control, so if you need that you should put it behind +a suitable web proxy. +As a small protection against data loss when running an unprotected +instance, it writes a numbered backup of the main journal file (only ?) +on every edit. +.PP +Like hledger, it reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +For more about this see hledger(1), hledger_journal(5) etc. +.PP +By default, hledger\-web starts the web app in \[lq]transient mode\[rq] +and also opens it in your default web browser if possible. +In this mode the web app will keep running for as long as you have it +open in a browser window, and will exit after two minutes of inactivity +(no requests and no browser windows viewing it). +With \f[C]\-\-serve\f[], it just runs the web app without exiting, and +logs requests to the console. +.PP +By default the server listens on IP address 127.0.0.1, accessible only +to local requests. +You can use \f[C]\-\-host\f[] to change this, eg +\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses. +.PP +Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg +if you are running multiple hledger\-web instances. +.PP +You can use \f[C]\-\-base\-url\f[] 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[C]http://HOST:PORT/\f[] using the server's configured +host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80). +.PP +With \f[C]\-\-file\-url\f[] you can set a different base url for static +files, eg for better caching or cookie\-less serving on high performance +websites. +.PP +Note there is no built\-in access control (aside from listening on +127.0.0.1 by default). +So you will need to hide hledger\-web behind an authenticating proxy +(such as apache or nginx) if you want to restrict who can see and add +entries to your journal. +.PP +Command\-line options and arguments may be used to set an initial filter +on the data. +This is not shown in the web UI, but it will be applied in addition to +any search query entered there. +.PP +With journal and timeclock files (but not CSV files, currently) the web +app detects changes made by other means and will show the new data on +the next request. +If a change makes the file unparseable, hledger\-web will show an error +until the file has been fixed. +.SH OPTIONS +.PP +Note: if invoking hledger\-web as a hledger subcommand, write +\f[C]\-\-\f[] before options as shown above. +.TP +.B \f[C]\-\-serve\f[] +serve and log requests, don't browse or auto\-exit +.RS +.RE +.TP +.B \f[C]\-\-host=IPADDR\f[] +listen on this IP address (default: 127.0.0.1) +.RS +.RE +.TP +.B \f[C]\-\-port=PORT\f[] +listen on this TCP port (default: 5000) +.RS +.RE +.TP +.B \f[C]\-\-base\-url=URL\f[] +set the base url (default: http://IPADDR:PORT). +You would change this when sharing over the network, or integrating +within a larger website. +.RS +.RE +.TP +.B \f[C]\-\-file\-url=URL\f[] +set the static files url (default: BASEURL/static). +hledger\-web normally serves static files itself, but if you wanted to +serve them from another server for efficiency, you would set the url +with this. +.RS +.RE +.PP +hledger input options: +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or +\f[C]$HOME/.hledger.journal\f[]) +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +rename accounts named OLD to NEW +.RS +.RE +.TP +.B \f[C]\-\-anon\f[] +anonymize accounts and payees +.RS +.RE +.TP +.B \f[C]\-\-pivot\ FIELDNAME\f[] +use some other field or tag for the account name +.RS +.RE +.TP +.B \f[C]\-I\ \-\-ignore\-assertions\f[] +ignore any failing balance assertions +.RS +.RE +.PP +hledger reporting options: +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once using +period expressions syntax (overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\f[] +match the secondary date instead (see command help for other effects) +.RS +.RE +.TP +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) +.RS +.RE +.TP +.B \f[C]\-P\ \-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-NUM\ \-\-depth=NUM\f[] +hide/aggregate accounts or postings more than NUM levels deep +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show items with zero amount, normally hidden (and vice\-versa in +hledger\-ui/hledger\-web) +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +convert amounts to their cost at transaction time (using the transaction +price, if any) +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +convert amounts to their market value on the report end date (using the +most recent applicable market price, if any) +.RS +.RE +.TP +.B \f[C]\-\-auto\f[] +apply automated posting rules to modify transactions. +.RS +.RE +.TP +.B \f[C]\-\-forecast\f[] +apply periodic transaction rules to generate future transactions, to 6 +months from now or report end date. +.RS +.RE +.PP +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 +.B \f[C]\-h\ \-\-help\f[] +show general usage (or after COMMAND, command usage) +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version +.RS +.RE +.TP +.B \f[C]\-\-debug[=N]\f[] +show debug output (levels 1\-9, default: 1) +.RS +.RE +.PP +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 \f[C]\-\-\f[] argument before.) +.SH ENVIRONMENT +.PP +\f[B]LEDGER_FILE\f[] The journal file path when not specified with +\f[C]\-f\f[]. +Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps +\f[C]C:/Users/USER/.hledger.journal\f[]). +.SH FILES +.PP +Reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. +.PP +\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin). +.PP +Query arguments and some hledger options are ignored. +.PP +Does not work in text\-mode browsers. +.PP +Does not work well on small screens. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-web.info @@ -0,0 +1,215 @@ +This is hledger-web.info, produced by makeinfo version 6.5 from stdin. + + +File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) + +hledger-web(1) hledger-web 1.9 +****************************** + +hledger-web is hledger's web interface. It starts a simple web +application for browsing and adding transactions, and optionally opens +it in a web browser window if possible. It provides a more +user-friendly UI than the hledger CLI or hledger-ui interface, showing +more at once (accounts, the current account register, balance charts) +and allowing history-aware data entry, interactive searching, and +bookmarking. + + hledger-web also lets you share a ledger with multiple users, or even +the public web. There is no access control, so if you need that you +should put it behind a suitable web proxy. As a small protection +against data loss when running an unprotected instance, it writes a +numbered backup of the main journal file (only ?) on every edit. + + Like hledger, it reads data from one or more files in hledger +journal, timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), +hledger_journal(5) etc. + + By default, hledger-web starts the web app in "transient mode" and +also opens it in your default web browser if possible. In this mode the +web app will keep running for as long as you have it open in a browser +window, and will exit after two minutes of inactivity (no requests and +no browser windows viewing it). With '--serve', it just runs the web +app without exiting, and logs requests to the console. + + 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. + + 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. + + Note there is no built-in access control (aside from listening on +127.0.0.1 by default). So you will need to hide hledger-web behind an +authenticating proxy (such as apache or nginx) if you want to restrict +who can see and add entries to your journal. + + Command-line options and arguments may be used to set an initial +filter on the data. This is not shown in the web UI, but it will be +applied in addition to any search query entered there. + + With journal and timeclock files (but not CSV files, currently) the +web app detects changes made by other means and will show the new data +on the next request. If a change makes the file unparseable, +hledger-web will show an error until the file has been fixed. +* Menu: + +* OPTIONS:: + + +File: hledger-web.info, Node: OPTIONS, Prev: Top, Up: Top + +1 OPTIONS +********* + +Note: if invoking hledger-web as a hledger subcommand, write '--' before +options as shown above. + +'--serve' + + serve and log requests, don't browse or auto-exit +'--host=IPADDR' + + listen on this IP address (default: 127.0.0.1) +'--port=PORT' + + listen on this TCP port (default: 5000) +'--base-url=URL' + + set the base url (default: http://IPADDR:PORT). You would change + this when sharing over the network, or integrating within a larger + website. +'--file-url=URL' + + set the static files url (default: BASEURL/static). hledger-web + normally serves static files itself, but if you wanted to serve + them from another server for efficiency, you would set the url with + this. + + hledger 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: FILE.rules) +'--alias=OLD=NEW' + + rename accounts named OLD to NEW +'--anon' + + anonymize accounts and payees +'--pivot FIELDNAME' + + use some other field or tag for the account name +'-I --ignore-assertions' + + ignore any failing balance assertions + + hledger reporting options: + +'-b --begin=DATE' + + include postings/txns on or after this date +'-e --end=DATE' + + include postings/txns before this date +'-D --daily' + + multiperiod/multicolumn report by day +'-W --weekly' + + multiperiod/multicolumn report by week +'-M --monthly' + + multiperiod/multicolumn report by month +'-Q --quarterly' + + multiperiod/multicolumn report by quarter +'-Y --yearly' + + multiperiod/multicolumn report by year +'-p --period=PERIODEXP' + + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) +'--date2' + + match the secondary date instead (see command help for other + effects) +'-U --unmarked' + + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' + + include only pending postings/txns +'-C --cleared' + + include only cleared postings/txns +'-R --real' + + include only non-virtual postings +'-NUM --depth=NUM' + + hide/aggregate accounts or postings more than NUM levels deep +'-E --empty' + + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) +'-B --cost' + + convert amounts to their cost at transaction time (using the + transaction price, if any) +'-V --value' + + convert amounts to their market value on the report end date (using + the most recent applicable market price, if any) +'--auto' + + apply automated posting rules to modify transactions. +'--forecast' + + apply periodic transaction rules to generate future transactions, + to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, +the last one takes precedence. + + Some reporting options can also be written as query arguments. + + hledger help options: + +'-h --help' + + show general usage (or after COMMAND, command usage) +'--version' + + show 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.) + + +Tag Table: +Node: Top72 +Node: OPTIONS3152 +Ref: #options3237 + +End Tag Table diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger-web.txt @@ -0,0 +1,251 @@ + +hledger-web(1) hledger User Manuals hledger-web(1) + + + +NAME + hledger-web - web interface for the hledger accounting tool + +SYNOPSIS + hledger-web [OPTIONS] + hledger web -- [OPTIONS] + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any + other commodity, using double-entry accounting and a simple, editable + file format. hledger is inspired by and largely compatible with + ledger(1). + + hledger-web is hledger's web interface. It starts a simple web appli- + cation for browsing and adding transactions, and optionally opens it in + a web browser window if possible. It provides a more user-friendly UI + than the hledger CLI or hledger-ui interface, showing more at once + (accounts, the current account register, balance charts) and allowing + history-aware data entry, interactive searching, and bookmarking. + + hledger-web also lets you share a ledger with multiple users, or even + the public web. There is no access control, so if you need that you + should put it behind a suitable web proxy. As a small protection + against data loss when running an unprotected instance, it writes a + numbered backup of the main journal file (only ?) on every edit. + + Like hledger, it reads data from one or more files in hledger journal, + timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, + or $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). For more about this see hledger(1), + hledger_journal(5) etc. + + By default, hledger-web starts the web app in "transient mode" and also + opens it in your default web browser if possible. In this mode the web + app will keep running for as long as you have it open in a browser win- + dow, and will exit after two minutes of inactivity (no requests and no + browser windows viewing it). With --serve, it just runs the web app + without exiting, and logs requests to the console. + + 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. + + 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. + + Note there is no built-in access control (aside from listening on + 127.0.0.1 by default). So you will need to hide hledger-web behind an + authenticating proxy (such as apache or nginx) if you want to restrict + who can see and add entries to your journal. + + Command-line options and arguments may be used to set an initial filter + on the data. This is not shown in the web UI, but it will be applied + in addition to any search query entered there. + + With journal and timeclock files (but not CSV files, currently) the web + app detects changes made by other means and will show the new data on + the next request. If a change makes the file unparseable, hledger-web + will show an error until the file has been fixed. + +OPTIONS + Note: if invoking hledger-web as a hledger subcommand, write -- before + options as shown above. + + --serve + serve and log requests, don't browse or auto-exit + + --host=IPADDR + listen on this IP address (default: 127.0.0.1) + + --port=PORT + listen on this TCP port (default: 5000) + + --base-url=URL + set the base url (default: http://IPADDR:PORT). You would + change this when sharing over the network, or integrating within + a larger website. + + --file-url=URL + set the static files url (default: BASEURL/static). hledger-web + normally serves static files itself, but if you wanted to serve + them from another server for efficiency, you would set the url + with this. + + hledger 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: + FILE.rules) + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot FIELDNAME + use some other field or tag for the account name + + -I --ignore-assertions + ignore any failing balance assertions + + hledger reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) + + --date2 + match the secondary date instead (see command help for other + effects) + + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) + + -P --pending + include only pending postings/txns + + -C --cleared + include only cleared postings/txns + + -R --real + include only non-virtual postings + + -NUM --depth=NUM + hide/aggregate accounts or postings more than NUM levels deep + + -E --empty + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + --auto apply automated posting rules to modify transactions. + + --forecast + apply periodic transaction rules to generate future transac- + tions, to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, the + last one takes precedence. + + Some reporting options can also be written as query arguments. + + hledger help options: + + -h --help + show general usage (or after COMMAND, command usage) + + --version + show 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.) + +ENVIRONMENT + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede options with -- when invoked from hledger is awk- + ward. + + -f- doesn't work (hledger-web can't read from stdin). + + Query arguments and some hledger options are ignored. + + Does not work in text-mode browsers. + + Does not work well on small screens. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger-web 1.9 March 2018 hledger-web(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger.1 @@ -0,0 +1,2981 @@ +.\"t + +.TH "hledger" "1" "March 2018" "hledger 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +hledger \- a command\-line accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PD 0 +.P +.PD +Tested on unix, mac, windows, hledger aims to be a reliable, practical +tool for daily use. +.PP +This is hledger's command\-line interface (there are also curses and web +interfaces). +Its basic function is to read a plain text file describing financial +transactions (in accounting terms, a general journal) and print useful +reports on standard output, or export them as CSV. +hledger can also read some other file formats such as CSV files, +translating them to journal format. +Additionally, hledger lists other hledger\-* executables found in the +user's $PATH and can invoke them as subcommands. +.PP +hledger reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +If using \f[C]$LEDGER_FILE\f[], note this must be a real environment +variable, not a shell variable. +You can specify standard input with \f[C]\-f\-\f[]. +.PP +Transactions are dated movements of money between two (or more) named +accounts, and are recorded with journal entries like this: +.IP +.nf +\f[C] +2015/10/16\ bought\ food +\ expenses:food\ \ \ \ \ \ \ \ \ \ $10 +\ assets:cash +\f[] +.fi +.PP +For more about this format, see hledger_journal(5). +.PP +Most users use a text editor to edit the journal, usually with an editor +mode such as ledger\-mode for added convenience. +hledger's interactive add command is another way to record new +transactions. +hledger never changes existing transactions. +.PP +To get started, you can either save some entries like the above in +\f[C]~/.hledger.journal\f[], or run \f[C]hledger\ add\f[] and follow the +prompts. +Then try some commands like \f[C]hledger\ print\f[] or +\f[C]hledger\ balance\f[]. +Run \f[C]hledger\f[] with no arguments for a list of commands. +.SH EXAMPLES +.PP +Two simple transactions in hledger journal format: +.IP +.nf +\f[C] +2015/9/30\ gift\ received +\ \ assets:cash\ \ \ $20 +\ \ income:gifts + +2015/10/16\ farmers\ market +\ \ expenses:food\ \ \ \ $10 +\ \ assets:cash +\f[] +.fi +.PP +Some basic reports: +.IP +.nf +\f[C] +$\ hledger\ print +2015/09/30\ gift\ received +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $20 +\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ $\-20 + +2015/10/16\ farmers\ market +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ $10 +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ accounts\ \-\-tree +assets +\ \ cash +expenses +\ \ food +income +\ \ gifts +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ balance +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ assets:cash +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ expenses:food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20\ \ income:gifts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ register\ cash +2015/09/30\ gift\ received\ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ $20 +2015/10/16\ farmers\ market\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ \ $10 +\f[] +.fi +.PP +More commands: +.IP +.nf +\f[C] +$\ hledger\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ available\ commands +$\ hledger\ add\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ add\ more\ transactions\ to\ the\ journal\ file +$\ hledger\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ all\ accounts\ with\ aggregated\ balances +$\ hledger\ balance\ \-\-help\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ detailed\ help\ for\ balance\ command +$\ hledger\ balance\ \-\-depth\ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ only\ top\-level\ accounts +$\ hledger\ register\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ account\ postings,\ with\ running\ total +$\ hledger\ reg\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ postings\ to/from\ income\ accounts +$\ hledger\ reg\ \[aq]assets:some\ bank:checking\[aq]\ #\ show\ postings\ to/from\ this\ checking\ account +$\ hledger\ print\ desc:shop\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transactions\ with\ shop\ in\ the\ description +$\ hledger\ activity\ \-W\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ transaction\ counts\ per\ week\ as\ a\ bar\ chart +\f[] +.fi +.SH OPTIONS +.SS General options +.PP +To see general usage help, including general options which are supported +by most hledger commands, run \f[C]hledger\ \-h\f[]. +.PP +General help options: +.TP +.B \f[C]\-h\ \-\-help\f[] +show general usage (or after COMMAND, command usage) +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version +.RS +.RE +.TP +.B \f[C]\-\-debug[=N]\f[] +show debug output (levels 1\-9, default: 1) +.RS +.RE +.PP +General input options: +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or +\f[C]$HOME/.hledger.journal\f[]) +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +rename accounts named OLD to NEW +.RS +.RE +.TP +.B \f[C]\-\-anon\f[] +anonymize accounts and payees +.RS +.RE +.TP +.B \f[C]\-\-pivot\ FIELDNAME\f[] +use some other field or tag for the account name +.RS +.RE +.TP +.B \f[C]\-I\ \-\-ignore\-assertions\f[] +ignore any failing balance assertions +.RS +.RE +.PP +General reporting options: +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once using +period expressions syntax (overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\f[] +match the secondary date instead (see command help for other effects) +.RS +.RE +.TP +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) +.RS +.RE +.TP +.B \f[C]\-P\ \-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-NUM\ \-\-depth=NUM\f[] +hide/aggregate accounts or postings more than NUM levels deep +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show items with zero amount, normally hidden (and vice\-versa in +hledger\-ui/hledger\-web) +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +convert amounts to their cost at transaction time (using the transaction +price, if any) +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +convert amounts to their market value on the report end date (using the +most recent applicable market price, if any) +.RS +.RE +.TP +.B \f[C]\-\-auto\f[] +apply automated posting rules to modify transactions. +.RS +.RE +.TP +.B \f[C]\-\-forecast\f[] +apply periodic transaction rules to generate future transactions, to 6 +months from now or report end date. +.RS +.RE +.PP +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. +.SS Command options +.PP +To see options for a particular command, including command\-specific +options, run: \f[C]hledger\ COMMAND\ \-h\f[]. +.PP +Command\-specific options must be written after the command name, eg: +\f[C]hledger\ print\ \-x\f[]. +.PP +Additionally, if the command is an addon, you may need to put its +options after a double\-hyphen, eg: +\f[C]hledger\ ui\ \-\-\ \-\-watch\f[]. +Or, you can run the addon executable directly: +\f[C]hledger\-ui\ \-\-watch\f[]. +.SS Command arguments +.PP +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. +.SS Argument files +.PP +You can save a set of command line options/arguments in a file, one per +line, and then reuse them by writing \f[C]\@FILENAME\f[] in a command +line. +To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a +\f[C]\-\-\f[] argument. +For more, see Save frequently used options. +.SS Special characters +.PP +Option and argument values which contain problematic characters should +be escaped with double quotes, backslashes, or (best) single quotes. +Problematic characters means spaces, and also characters which are +significant to your command shell, such as less\-than/greater\-than. +Eg: +\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. +.PP +Characters which are significant both to the shell and in regular +expressions sometimes need to be double\-escaped. +These include parentheses, the pipe symbol and the dollar sign. +Eg, to match the dollar symbol, bash users should do: +\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or +\f[C]hledger\ balance\ cur:\\\\$\f[]. +.PP +When hledger is invoking an addon executable (like hledger\-ui), options +and arguments get de\-escaped once more, so you might need +\f[I]triple\f[]\-escaping. +Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or +\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] in bash. +(The number of backslashes in fish shell is left as an exercise for the +reader.) +.PP +Inside a file used for argument expansion, one less level of escaping is +enough. +(And in this case, backslashes seem to work better than quotes. +Eg: \f[C]cur:\\$\f[]). +.PP +If in doubt, keep things simple: +.IP \[bu] 2 +run add\-on executables directly +.IP \[bu] 2 +write options after the command +.IP \[bu] 2 +enclose problematic args in single quotes +.IP \[bu] 2 +if needed, also add a backslash to escape regexp metacharacters +.PP +If you're really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot. +.SS Input files +.PP +hledger reads transactions from a data file (and the add command writes +to it). +By default this file is \f[C]$HOME/.hledger.journal\f[] (or on Windows, +something like \f[C]C:/Users/USER/.hledger.journal\f[]). +You can override this with the \f[C]$LEDGER_FILE\f[] environment +variable: +.IP +.nf +\f[C] +$\ setenv\ LEDGER_FILE\ ~/finance/2016.journal +$\ hledger\ stats +\f[] +.fi +.PP +or with the \f[C]\-f/\-\-file\f[] option: +.IP +.nf +\f[C] +$\ hledger\ \-f\ /some/file\ stats +\f[] +.fi +.PP +The file name \f[C]\-\f[] (hyphen) means standard input: +.IP +.nf +\f[C] +$\ cat\ some.journal\ |\ hledger\ \-f\- +\f[] +.fi +.PP +Usually the data file is in hledger's journal format, but it can also be +one of several other formats, listed below. +hledger detects the format automatically based on the file extension, or +if that is not recognised, by trying each built\-in \[lq]reader\[rq] in +turn: +.PP +.TS +tab(@); +lw(10.3n) lw(33.5n) lw(26.2n). +T{ +Reader: +T}@T{ +Reads: +T}@T{ +Used for file extensions: +T} +_ +T{ +\f[C]journal\f[] +T}@T{ +hledger's journal format, also some Ledger journals +T}@T{ +\f[C]\&.journal\f[] \f[C]\&.j\f[] \f[C]\&.hledger\f[] \f[C]\&.ledger\f[] +T} +T{ +\f[C]timeclock\f[] +T}@T{ +timeclock files (precise time logging) +T}@T{ +\f[C]\&.timeclock\f[] +T} +T{ +\f[C]timedot\f[] +T}@T{ +timedot files (approximate time logging) +T}@T{ +\f[C]\&.timedot\f[] +T} +T{ +\f[C]csv\f[] +T}@T{ +comma\-separated values (data interchange) +T}@T{ +\f[C]\&.csv\f[] +T} +.TE +.PP +If needed (eg to ensure correct error messages when a file has the +\[lq]wrong\[rq] extension), you can force a specific reader/format by +prepending it to the file path with a colon. +Examples: +.IP +.nf +\f[C] +$\ hledger\ \-f\ csv:/some/csv\-file.dat\ stats +$\ echo\ \[aq]i\ 2009/13/1\ 08:00:00\[aq]\ |\ hledger\ print\ \-ftimeclock:\- +\f[] +.fi +.PP +You can also specify multiple \f[C]\-f\f[] options, to read multiple +files as one big journal. +There are some limitations with this: +.IP \[bu] 2 +directives in one file will not affect the other files +.IP \[bu] 2 +balance assertions will not see any account balances from previous files +.PP +If you need those, either use the include directive, or concatenate the +files, eg: \f[C]cat\ a.journal\ b.journal\ |\ hledger\ \-f\-\ CMD\f[]. +.SS Smart dates +.PP +hledger's user interfaces accept a flexible \[lq]smart date\[rq] syntax +(unlike dates in the journal file). +Smart dates allow some english words, can be relative to today's date, +and can have less\-significant date parts omitted (defaulting to 1). +.PP +Examples: +.PP +.TS +tab(@); +l l. +T{ +\f[C]2009/1/1\f[], \f[C]2009/01/01\f[], \f[C]2009\-1\-1\f[], +\f[C]2009.1.1\f[] +T}@T{ +simple dates, several separators allowed +T} +T{ +\f[C]2009/1\f[], \f[C]2009\f[] +T}@T{ +same as above \- a missing day or month defaults to 1 +T} +T{ +\f[C]1/1\f[], \f[C]january\f[], \f[C]jan\f[], \f[C]this\ year\f[] +T}@T{ +relative dates, meaning january 1 of the current year +T} +T{ +\f[C]next\ year\f[] +T}@T{ +january 1 of next year +T} +T{ +\f[C]this\ month\f[] +T}@T{ +the 1st of the current month +T} +T{ +\f[C]this\ week\f[] +T}@T{ +the most recent monday +T} +T{ +\f[C]last\ week\f[] +T}@T{ +the monday of the week before this one +T} +T{ +\f[C]lastweek\f[] +T}@T{ +spaces are optional +T} +T{ +\f[C]today\f[], \f[C]yesterday\f[], \f[C]tomorrow\f[] +T}@T{ +T} +.TE +.SS Report start & end date +.PP +Most hledger reports show the full span of time represented by the +journal data, by default. +So, the effective report start and end dates will be the earliest and +latest transaction or posting dates found in the journal. +.PP +Often you will want to see a shorter time span, such as the current +month. +You can specify a start and/or end date using \f[C]\-b/\-\-begin\f[], +\f[C]\-e/\-\-end\f[], \f[C]\-p/\-\-period\f[] or a \f[C]date:\f[] query +(described below). +All of these accept the smart date syntax. +One important thing to be aware of when specifying end dates: as in +Ledger, end dates are exclusive, so you need to write the date +\f[I]after\f[] the last day you want to include. +.PP +Examples: +.PP +.TS +tab(@); +l l. +T{ +\f[C]\-b\ 2016/3/17\f[] +T}@T{ +begin on St.\ Patrick's day 2016 +T} +T{ +\f[C]\-e\ 12/1\f[] +T}@T{ +end at the start of december 1st of the current year (11/30 will be the +last date included) +T} +T{ +\f[C]\-b\ thismonth\f[] +T}@T{ +all transactions on or after the 1st of the current month +T} +T{ +\f[C]\-p\ thismonth\f[] +T}@T{ +all transactions in the current month +T} +T{ +\f[C]date:2016/3/17\-\f[] +T}@T{ +the above written as queries instead +T} +T{ +\f[C]date:\-12/1\f[] +T}@T{ +T} +T{ +\f[C]date:thismonth\-\f[] +T}@T{ +T} +T{ +\f[C]date:thismonth\f[] +T}@T{ +T} +.TE +.SS Report intervals +.PP +A report interval can be specified so that commands like register, +balance and activity will divide their reports into multiple subperiods. +The basic intervals can be selected with one of \f[C]\-D/\-\-daily\f[], +\f[C]\-W/\-\-weekly\f[], \f[C]\-M/\-\-monthly\f[], +\f[C]\-Q/\-\-quarterly\f[], or \f[C]\-Y/\-\-yearly\f[]. +More complex intervals may be specified with a period expression. +Report intervals can not be specified with a query, currently. +.SS Period expressions +.PP +The \f[C]\-p/\-\-period\f[] option accepts period expressions, a +shorthand way of expressing a start date, end date, and/or report +interval all at once. +.PP +Here's a basic period expression specifying the first quarter of 2009. +Note, hledger always treats start dates as inclusive and end dates as +exclusive: +.PP +\f[C]\-p\ "from\ 2009/1/1\ to\ 2009/4/1"\f[] +.PP +Keywords like \[lq]from\[rq] and \[lq]to\[rq] are optional, and so are +the spaces, as long as you don't run two dates together. +\[lq]to\[rq] can also be written as \[lq]\-\[rq]. +These are equivalent to the above: +.PP +.TS +tab(@); +l. +T{ +\f[C]\-p\ "2009/1/1\ 2009/4/1"\f[] +T} +T{ +\f[C]\-p2009/1/1to2009/4/1\f[] +T} +T{ +\f[C]\-p2009/1/1\-2009/4/1\f[] +T} +.TE +.PP +Dates are smart dates, so if the current year is 2009, the above can +also be written as: +.PP +.TS +tab(@); +l. +T{ +\f[C]\-p\ "1/1\ 4/1"\f[] +T} +T{ +\f[C]\-p\ "january\-apr"\f[] +T} +T{ +\f[C]\-p\ "this\ year\ to\ 4/1"\f[] +T} +.TE +.PP +If you specify only one date, the missing start or end date will be the +earliest or latest transaction in your journal: +.PP +.TS +tab(@); +l l. +T{ +\f[C]\-p\ "from\ 2009/1/1"\f[] +T}@T{ +everything after january 1, 2009 +T} +T{ +\f[C]\-p\ "from\ 2009/1"\f[] +T}@T{ +the same +T} +T{ +\f[C]\-p\ "from\ 2009"\f[] +T}@T{ +the same +T} +T{ +\f[C]\-p\ "to\ 2009"\f[] +T}@T{ +everything before january 1, 2009 +T} +.TE +.PP +A single date with no \[lq]from\[rq] or \[lq]to\[rq] defines both the +start and end date like so: +.PP +.TS +tab(@); +l l. +T{ +\f[C]\-p\ "2009"\f[] +T}@T{ +the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq] +T} +T{ +\f[C]\-p\ "2009/1"\f[] +T}@T{ +the month of jan; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq] +T} +T{ +\f[C]\-p\ "2009/1/1"\f[] +T}@T{ +just that day; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq] +T} +.TE +.PP +The argument of \f[C]\-p\f[] can also begin with, or be, a report +interval expression. +The basic report intervals are \f[C]daily\f[], \f[C]weekly\f[], +\f[C]monthly\f[], \f[C]quarterly\f[], or \f[C]yearly\f[], which have the +same effect as the \f[C]\-D\f[],\f[C]\-W\f[],\f[C]\-M\f[],\f[C]\-Q\f[], +or \f[C]\-Y\f[] flags. +Between report interval and start/end dates (if any), the word +\f[C]in\f[] is optional. +Examples: +.PP +.TS +tab(@); +l. +T{ +\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] +T} +T{ +\f[C]\-p\ "monthly\ in\ 2008"\f[] +T} +T{ +\f[C]\-p\ "quarterly"\f[] +T} +.TE +.PP +Note that \f[C]weekly\f[], \f[C]monthly\f[], \f[C]quarterly\f[] and +\f[C]yearly\f[] intervals will always start on the first day on week, +month, quarter or year accordingly, and will end on the last day of same +period, even if associated period expression specifies different +explicit start and end date. +.PP +For example: +.PP +.TS +tab(@); +l. +T{ +\f[C]\-p\ "weekly\ from\ 2009/1/1\ to\ 2009/4/1"\f[] \[en] starts on +2008/12/29, closest preceeding Monday +T} +T{ +\f[C]\-p\ "monthly\ in\ 2008/11/25"\f[] \[en] starts on 2018/11/01 +T} +T{ +\f[C]\-p\ "quarterly\ from\ 2009\-05\-05\ to\ 2009\-06\-01"\f[] \- +starts on 2009/04/01, ends on 2009/06/30, which are first and last days +of Q2 2009 +T} +T{ +\f[C]\-p\ "yearly\ from\ 2009\-12\-29"\f[] \- starts on 2009/01/01, +first day of 2009 +T} +.TE +.PP +The following more complex report intervals are also supported: +\f[C]biweekly\f[], \f[C]bimonthly\f[], +\f[C]every\ day|week|month|quarter|year\f[], +\f[C]every\ N\ days|weeks|months|quarters|years\f[]. +.PP +All of these will start on the first day of the requested period and end +on the last one, as described above. +.PP +Examples: +.PP +.TS +tab(@); +l. +T{ +\f[C]\-p\ "bimonthly\ from\ 2008"\f[] \[en] periods will have boundaries +on 2008/01/01, 2008/03/01, \&... +T} +T{ +\f[C]\-p\ "every\ 2\ weeks"\f[] \[en] starts on closest preceeding +Monday +T} +T{ +\f[C]\-p\ "every\ 5\ month\ from\ 2009/03"\f[] \[en] periods will have +boundaries on 2009/03/01, 2009/08/01, \&... +T} +.TE +.PP +If you want intervals that start on arbitrary day of your choosing and +span a week, month or year, you need to use any of the following: +.PP +\f[C]every\ Nth\ day\ of\ week\f[], \f[C]every\ \f[], +\f[C]every\ Nth\ day\ [of\ month]\f[], +\f[C]every\ Nth\ weekday\ [of\ month]\f[], +\f[C]every\ MM/DD\ [of\ year]\f[], \f[C]every\ Nth\ MMM\ [of\ year]\f[], +\f[C]every\ MMM\ Nth\ [of\ year]\f[]. +.PP +Examples: +.PP +.TS +tab(@); +l. +T{ +\f[C]\-p\ "every\ 2nd\ day\ of\ week"\f[] \[en] periods will go from Tue +to Tue +T} +T{ +\f[C]\-p\ "every\ Tue"\f[] \[en] same +T} +T{ +\f[C]\-p\ "every\ 15th\ day"\f[] \[en] period boundaries will be on 15th +of each month +T} +T{ +\f[C]\-p\ "every\ 2nd\ Monday"\f[] \[en] period boundaries will be on +second Monday of each month +T} +T{ +\f[C]\-p\ "every\ 11/05"\f[] \[en] yearly periods with boundaries on 5th +of Nov +T} +T{ +\f[C]\-p\ "every\ 5th\ Nov"\f[] \[en] same +T} +T{ +\f[C]\-p\ "every\ Nov\ 5th"\f[] \[en] same +T} +.TE +.PP +Show historical balances at end of 15th each month (N is exclusive end +date): +.PP +\f[C]hledger\ balance\ \-H\ \-p\ "every\ 16th\ day"\f[] +.PP +Group postings from start of wednesday to end of next tuesday (N is +start date and exclusive end date): +.PP +\f[C]hledger\ register\ checking\ \-p\ "every\ 3rd\ day\ of\ week"\f[] +.SS Depth limiting +.PP +With the \f[C]\-\-depth\ N\f[] option (short form: \f[C]\-N\f[]), +commands like account, balance and register will show only the uppermost +accounts in the account tree, down to level N. +Use this when you want a summary with less detail. +This flag has the same effect as a \f[C]depth:\f[] query argument (so +\f[C]\-2\f[], \f[C]\-\-depth=2\f[] or \f[C]depth:2\f[] are basically +equivalent). +.SS Pivoting +.PP +Normally hledger sums amounts, and organizes them in a hierarchy, based +on account name. +The \f[C]\-\-pivot\ FIELD\f[] option causes it to sum and organize +hierarchy based on the value of some other field instead. +FIELD can be: \f[C]code\f[], \f[C]description\f[], \f[C]payee\f[], +\f[C]note\f[], or the full name (case insensitive) of any tag. +As with account names, values containing \f[C]colon:separated:parts\f[] +will be displayed hierarchically in reports. +.PP +\f[C]\-\-pivot\f[] is a general option affecting all reports; you can +think of hledger transforming the journal before any other processing, +replacing every posting's account name with the value of the specified +field on that posting, inheriting it from the transaction or using a +blank value if it's not present. +.PP +An example: +.IP +.nf +\f[C] +2016/02/16\ Member\ Fee\ Payment +\ \ \ \ assets:bank\ account\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR +\ \ \ \ income:member\ fees\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ ;\ member:\ John\ Doe +\f[] +.fi +.PP +Normal balance report showing account names: +.IP +.nf +\f[C] +$\ hledger\ balance +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR\ \ assets:bank\ account +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ income:member\ fees +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +Pivoted balance report, using member: tag values instead: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-pivot\ member +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ EUR +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +One way to show only amounts with a member: value (using a query, +described below): +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-pivot\ member\ tag:member=. +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR +\f[] +.fi +.PP +Another way (the acct: query matches against the pivoted \[lq]account +name\[rq]): +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-pivot\ member\ acct:. +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR\ \ John\ Doe +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \-2\ EUR +\f[] +.fi +.SS Cost +.PP +The \f[C]\-B/\-\-cost\f[] flag converts amounts to their cost at +transaction time, if they have a transaction price specified. +.SS Market value +.PP +The \f[C]\-V/\-\-value\f[] flag converts reported amounts to their +current market value. +Specifically, when there is a market price (P directive) for the +amount's commodity, dated on or before today's date (or the report end +date if specified), the amount will be converted to the price's +commodity. +.PP +When there are multiple applicable P directives, \-V chooses the most +recent one, or in case of equal dates, the last\-parsed one. +.PP +For example: +.IP +.nf +\f[C] +#\ one\ euro\ is\ worth\ this\ many\ dollars\ from\ nov\ 1 +P\ 2016/11/01\ €\ $1.10 + +#\ purchase\ some\ euros\ on\ nov\ 3 +2016/11/3 +\ \ \ \ assets:euros\ \ \ \ \ \ \ \ €100 +\ \ \ \ assets:checking + +#\ the\ euro\ is\ worth\ fewer\ dollars\ by\ dec\ 21 +P\ 2016/12/21\ €\ $1.03 +\f[] +.fi +.PP +How many euros do I have ? +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ euros +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi +.PP +What are they worth on nov 3 ? +(no report end date specified, defaults to the last date in the journal) +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ euros\ \-V +\ \ \ \ \ \ \ \ \ \ \ \ \ $110.00\ \ assets:euros +\f[] +.fi +.PP +What are they worth on dec 21 ? +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ bal\ euros\ \-V\ \-e\ 2016/12/21 +\ \ \ \ \ \ \ \ \ \ \ \ \ $103.00\ \ assets:euros +\f[] +.fi +.PP +Currently, hledger's \-V only uses market prices recorded with P +directives, not transaction prices (unlike Ledger). +.SS Combining \-B and \-V +.PP +Using \-B/\[en]cost and \-V/\[en]value together is currently allowed, +but the results are probably not meaningful. +Let us know if you find a use for this. +.SS Output destination +.PP +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. +This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) +$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE +\f[] +.fi +.SS Output format +.PP +Some commands can write their output in other formats. +Eg print and register can output CSV, and the balance commands can +output CSV or HTML. +This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by +specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with +\f[C]\-o/\-\-output\-file\f[]. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout +$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv +\f[] +.fi +.SS Regular expressions +.PP +hledger uses regular expressions in a number of places: +.IP \[bu] 2 +query terms, on the command line and in the hledger\-web search form: +\f[C]REGEX\f[], \f[C]desc:REGEX\f[], \f[C]cur:REGEX\f[], +\f[C]tag:...=REGEX\f[] +.IP \[bu] 2 +CSV rules conditional blocks: \f[C]if\ REGEX\ ...\f[] +.IP \[bu] 2 +account alias directives and options: +\f[C]alias\ /REGEX/\ =\ REPLACEMENT\f[], +\f[C]\-\-alias\ /REGEX/=REPLACEMENT\f[] +.PP +hledger's regular expressions come from the regex\-tdfa library. +In general they: +.IP \[bu] 2 +are case insensitive +.IP \[bu] 2 +are infix matching (do not need to match the entire thing being matched) +.IP \[bu] 2 +are POSIX extended regular expressions +.IP \[bu] 2 +also support GNU word boundaries (\\<, \\>, \\b, \\B) +.IP \[bu] 2 +and parenthesised capturing groups and numeric backreferences in +replacement strings +.IP \[bu] 2 +do not support mode modifiers like (?s) +.PP +Some things to note: +.IP \[bu] 2 +In the \f[C]alias\f[] directive and \f[C]\-\-alias\f[] option, regular +expressions must be enclosed in forward slashes (\f[C]/REGEX/\f[]). +Elsewhere in hledger, these are not required. +.IP \[bu] 2 +In queries, to match a regular expression metacharacter like \f[C]$\f[] +as a literal character, prepend a backslash. +Eg to search for amounts with the dollar sign in hledger\-web, write +\f[C]cur:\\$\f[]. +.IP \[bu] 2 +On the command line, some metacharacters like \f[C]$\f[] have a special +meaning to the shell and so must be escaped at least once more. +See Special characters. +.SH QUERIES +.PP +One of hledger's strengths is being able to quickly report on precise +subsets of your data. +Most commands accept an optional query expression, written as arguments +after the command name, to filter the data by date, account name or +other criteria. +The syntax is similar to a web search: one or more space\-separated +search terms, quotes to enclose whitespace, prefixes to match specific +fields, a not: prefix to negate the match. +.PP +We do not yet support arbitrary boolean combinations of search terms; +instead most commands show transactions/postings/accounts which match +(or negatively match): +.IP \[bu] 2 +any of the description terms AND +.IP \[bu] 2 +any of the account terms AND +.IP \[bu] 2 +any of the status terms AND +.IP \[bu] 2 +all the other terms. +.PP +The print command instead shows transactions which: +.IP \[bu] 2 +match any of the description terms AND +.IP \[bu] 2 +have any postings matching any of the positive account terms AND +.IP \[bu] 2 +have no postings matching any of the negative account terms AND +.IP \[bu] 2 +match all the other terms. +.PP +The following kinds of search terms can be used. +Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to +exclude a particular subaccount. +.TP +.B \f[B]\f[BC]REGEX\f[B]\f[] +match account names by this regular expression. +(No prefix is equivalent to \f[C]acct:\f[]). +.RS +.RE +.TP +.B \f[B]\f[BC]acct:REGEX\f[B]\f[] +same as above +.RS +.RE +.TP +.B \f[B]\f[BC]amt:N,\ amt:N,\ amt:>=N\f[B]\f[] +match postings with a single\-commodity amount that is equal to, less +than, or greater than N. +(Multi\-commodity amounts are not tested, and will always match.) The +comparison has two modes: if N is preceded by a + or \- sign (or is 0), +the two signed numbers are compared. +Otherwise, the absolute magnitudes are compared, ignoring sign. +.RS +.RE +.TP +.B \f[B]\f[BC]code:REGEX\f[B]\f[] +match by transaction code (eg check number) +.RS +.RE +.TP +.B \f[B]\f[BC]cur:REGEX\f[B]\f[] +match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. +(For a partial match, use \f[C]\&.*REGEX.*\f[]). +Note, to match characters which are regex\-significant, like the dollar +sign (\f[C]$\f[]), you need to prepend \f[C]\\\f[]. +And when using the command line you need to add one more level of +quoting to hide it from the shell, so eg do: +\f[C]hledger\ print\ cur:\[aq]\\$\[aq]\f[] or +\f[C]hledger\ print\ cur:\\\\$\f[]. +.RS +.RE +.TP +.B \f[B]\f[BC]desc:REGEX\f[B]\f[] +match transaction descriptions. +.RS +.RE +.TP +.B \f[B]\f[BC]date:PERIODEXPR\f[B]\f[] +match dates within the specified period. +PERIODEXPR is a period expression (with no report interval). +Examples: \f[C]date:2016\f[], \f[C]date:thismonth\f[], +\f[C]date:2000/2/1\-2/15\f[], \f[C]date:lastweek\-\f[]. +If the \f[C]\-\-date2\f[] command line flag is present, this matches +secondary dates instead. +.RS +.RE +.TP +.B \f[B]\f[BC]date2:PERIODEXPR\f[B]\f[] +match secondary dates within the specified period. +.RS +.RE +.TP +.B \f[B]\f[BC]depth:N\f[B]\f[] +match (or display, depending on command) accounts at or above this depth +.RS +.RE +.TP +.B \f[B]\f[BC]note:REGEX\f[B]\f[] +match transaction notes (part of description right of \f[C]|\f[], or +whole description when there's no \f[C]|\f[]) +.RS +.RE +.TP +.B \f[B]\f[BC]payee:REGEX\f[B]\f[] +match transaction payee/payer names (part of description left of +\f[C]|\f[], or whole description when there's no \f[C]|\f[]) +.RS +.RE +.TP +.B \f[B]\f[BC]real:,\ real:0\f[B]\f[] +match real or virtual postings respectively +.RS +.RE +.TP +.B \f[B]\f[BC]status:,\ status:!,\ status:*\f[B]\f[] +match unmarked, pending, or cleared transactions respectively +.RS +.RE +.TP +.B \f[B]\f[BC]tag:REGEX[=REGEX]\f[B]\f[] +match by tag name, and optionally also by tag value. +Note a tag: query is considered to match a transaction if it matches any +of the postings. +Also remember that postings inherit the tags of their parent +transaction. +.RS +.RE +.PP +The following special search term is used automatically in hledger\-web, +only: +.TP +.B \f[B]\f[BC]inacct:ACCTNAME\f[B]\f[] +tells hledger\-web to show the transaction register for this account. +Can be filtered further with \f[C]acct\f[] etc. +.RS +.RE +.PP +Some of these can also be expressed as command\-line options (eg +\f[C]depth:2\f[] is equivalent to \f[C]\-\-depth\ 2\f[]). +Generally you can mix options and query arguments, and the resulting +query will be their intersection (perhaps excluding the +\f[C]\-p/\-\-period\f[] option). +.SH COMMANDS +.PP +hledger provides a number of subcommands; \f[C]hledger\f[] with no +arguments shows a list. +.PP +If you install additional \f[C]hledger\-*\f[] packages, or if you put +programs or scripts named \f[C]hledger\-NAME\f[] in your PATH, these +will also be listed as subcommands. +.PP +Run a subcommand by writing its name as first argument (eg +\f[C]hledger\ incomestatement\f[]). +You can also write one of the standard short aliases displayed in +parentheses in the command list (\f[C]hledger\ b\f[]), or any any +unambiguous prefix of a command name (\f[C]hledger\ inc\f[]). +.PP +Here are all the builtin commands in alphabetical order. +See also \f[C]hledger\f[] for a more organised command list, and +\f[C]hledger\ CMD\ \-h\f[] for detailed command help. +.SS accounts +.PP +Show account names. +Alias: a. +.TP +.B \f[C]\-\-declared\f[] +show account names declared with account directives +.RS +.RE +.TP +.B \f[C]\-\-used\f[] +show account names posted to by transactions +.RS +.RE +.TP +.B \f[C]\-\-tree\f[] +show short account names and their parents, as a tree +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show full account names, as a list (default) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +in flat mode: omit N leading account name parts +.RS +.RE +.PP +This command lists account names, either declared with account +directives (\[en]declared), posted to (\[en]used), or both (default). +With query arguments, only matched account names and account names +referenced by matched postings are shown. +It shows a flat list by default. +With \f[C]\-\-tree\f[], it uses indentation to show the account +hierarchy. +In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few +account name components. +Account names can be depth\-clipped with \f[C]\-\-depth\ N\f[] or +depth:N. +.PP +Examples: +.IP +.nf +\f[C] +$\ hledger\ accounts\ \-\-tree +assets +\ \ bank +\ \ \ \ checking +\ \ \ \ saving +\ \ cash +expenses +\ \ food +\ \ supplies +income +\ \ gifts +\ \ salary +liabilities +\ \ debts +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ accounts\ \-\-drop\ 1 +bank:checking +bank:saving +cash +food +supplies +gifts +salary +debts +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts +\f[] +.fi +.SS activity +.PP +Show an ascii barchart of posting counts per interval. +.PP +The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). +With query arguments, it counts only matched transactions. +.IP +.nf +\f[C] +$\ hledger\ activity\ \-\-quarterly +2008\-01\-01\ ** +2008\-04\-01\ ******* +2008\-07\-01\ +2008\-10\-01\ ** +\f[] +.fi +.SS add +.PP +Prompt for transactions and add them to the journal. +.TP +.B \f[C]\-\-no\-new\-accounts\f[] +don't allow creating new accounts; helps prevent typos when entering +account names +.RS +.RE +.PP +Many hledger users edit their journals directly with a text editor, or +generate them from CSV. +For more interactive data entry, there is the \f[C]add\f[] command, +which prompts interactively on the console for new transactions, and +appends them to the journal file (if there are multiple +\f[C]\-f\ FILE\f[] options, the first file is used.) Existing +transactions are not changed. +This is the only hledger command that writes to the journal file. +.PP +To use it, just run \f[C]hledger\ add\f[] and follow the prompts. +You can add as many transactions as you like; when you are finished, +enter \f[C]\&.\f[] or press control\-d or control\-c to exit. +.PP +Features: +.IP \[bu] 2 +add tries to provide useful defaults, using the most similar recent +transaction (by description) as a template. +.IP \[bu] 2 +You can also set the initial defaults with command line arguments. +.IP \[bu] 2 +Readline\-style edit keys can be used during data entry. +.IP \[bu] 2 +The tab key will auto\-complete whenever possible \- accounts, +descriptions, dates (\f[C]yesterday\f[], \f[C]today\f[], +\f[C]tomorrow\f[]). +If the input area is empty, it will insert the default value. +.IP \[bu] 2 +If the journal defines a default commodity, it will be added to any bare +numbers entered. +.IP \[bu] 2 +A parenthesised transaction code may be entered following a date. +.IP \[bu] 2 +Comments and tags may be entered following a description or amount. +.IP \[bu] 2 +If you make a mistake, enter \f[C]<\f[] at any prompt to restart the +transaction. +.IP \[bu] 2 +Input prompts are displayed in a different colour when the terminal +supports it. +.PP +Example (see the tutorial for a detailed explanation): +.IP +.nf +\f[C] +$\ hledger\ add +Adding\ transactions\ to\ journal\ file\ /src/hledger/examples/sample.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. +An\ optional\ ;\ COMMENT\ may\ follow\ descriptions\ or\ amounts. +If\ you\ make\ a\ mistake,\ enter\ <\ at\ any\ prompt\ to\ restart\ the\ transaction. +To\ end\ a\ transaction,\ enter\ .\ when\ prompted. +To\ quit,\ enter\ .\ at\ a\ date\ prompt\ or\ press\ control\-d\ or\ control\-c. +Date\ [2015/05/22]:\ +Description:\ supermarket +Account\ 1:\ expenses:food +Amount\ \ 1:\ $10 +Account\ 2:\ assets:checking +Amount\ \ 2\ [$\-10.0]:\ +Account\ 3\ (or\ .\ or\ enter\ to\ finish\ this\ transaction):\ . +2015/05/22\ supermarket +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ $10 +\ \ \ \ assets:checking\ \ \ \ \ \ \ \ $\-10.0 + +Save\ this\ transaction\ to\ the\ journal\ ?\ [y]:\ +Saved. +Starting\ the\ next\ transaction\ (.\ or\ ctrl\-D/ctrl\-C\ to\ quit) +Date\ [2015/05/22]:\ \ $ +\f[] +.fi +.SS balance +.PP +Show accounts and their balances. +Aliases: b, bal. +.TP +.B \f[C]\-\-change\f[] +show balance change in each period (default) +.RS +.RE +.TP +.B \f[C]\-\-cumulative\f[] +show balance change accumulated across periods (in multicolumn reports) +.RS +.RE +.TP +.B \f[C]\-H\ \-\-historical\f[] +show historical ending balance in each period (includes postings before +report start date) +.RS +.RE +.TP +.B \f[C]\-\-tree\f[] +show accounts as a tree; amounts include subaccounts (default in simple +reports) +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show accounts as a list; amounts exclude subaccounts except when account +is depth\-clipped (default in multicolumn reports) +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +show a row average column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-T\ \-\-row\-total\f[] +show a row total column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-N\ \-\-no\-total\f[] +don't show the final total row +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +omit N leading account name parts (in flat mode) +.RS +.RE +.TP +.B \f[C]\-\-no\-elide\f[] +don't squash boring parent accounts (in tree mode) +.RS +.RE +.TP +.B \f[C]\-\-format=LINEFORMAT\f[] +in single\-column balance reports: use this custom line format +.RS +.RE +.TP +.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] +select the output format. +Supported formats: txt, csv, html. +.RS +.RE +.TP +.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] +write output to FILE. +A file extension matching one of the above formats selects that format. +.RS +.RE +.TP +.B \f[C]\-\-pretty\-tables\f[] +use unicode to display prettier tables. +.RS +.RE +.TP +.B \f[C]\-\-sort\-amount\f[] +sort by amount instead of account code/name (in flat mode). +With multiple columns, sorts by the row total, or by row average if that +is displayed. +.RS +.RE +.TP +.B \f[C]\-\-invert\f[] +display all amounts with reversed sign +.RS +.RE +.TP +.B \f[C]\-\-budget\f[] +show performance compared to budget goals defined by periodic +transactions +.RS +.RE +.TP +.B \f[C]\-\-show\-unbudgeted\f[] +with \[en]budget, show unbudgeted accounts also +.RS +.RE +.PP +The balance command displays accounts and balances. +It is hledger's most featureful and versatile command. +.IP +.nf +\f[C] +$\ hledger\ balance +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +More precisely, the balance command shows the \f[I]change\f[] to each +account's balance caused by all (matched) postings. +In the common case where you do not filter by date and your journal sets +the correct opening balances, this is the same as the account's ending +balance. +.PP +By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. +At each level of the tree, accounts are sorted by account code if any, +then by account name. +Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. +.PP +\[lq]Boring\[rq] accounts, which contain a single interesting subaccount +and no balance of their own, are elided into the following line for more +compact output. +(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to +prevent this. +.PP +Account balances are \[lq]inclusive\[rq] \- they include the balances of +any subaccounts. +.PP +Accounts which have zero balance (and no non\-zero subaccounts) are +omitted. +Use \f[C]\-E/\-\-empty\f[] to show them. +.PP +A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to +suppress it: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\f[] +.fi +.SS Flat mode +.PP +To see a flat list of full account names instead of the default +hierarchical display, use \f[C]\-\-flat\f[]. +In this mode, accounts (unless depth\-clipped) show their +\[lq]exclusive\[rq] balance, excluding any subaccount balances. +In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first +few account name components. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ supplies +\f[] +.fi +.SS Depth limited balance reports +.PP +With \f[C]\-\-depth\ N\f[], balance shows accounts only to the specified +depth. +This is very useful to show a complex charts of accounts in less detail. +In flat mode, balances from accounts below the depth limit will be shown +as part of a parent account at the depth limit. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-N\ \-\-depth\ 1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities +\f[] +.fi +.SS Multicolumn balance reports +.PP +With a reporting interval, multiple balance columns will be shown, one +for each report period. +There are three types of multi\-column balance report, showing different +information: +.IP "1." 3 +By default: each column shows the sum of postings in that period, ie the +account's change of balance in that period. +This is useful eg for a monthly income statement: +.RS 4 +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-quarterly\ income\ expenses\ \-E +Balance\ changes\ in\ 2008: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008q1\ \ 2008q2\ \ 2008q3\ \ 2008q4\ +===================++================================= +\ expenses:food\ \ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ +\ expenses:supplies\ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ +\ income:gifts\ \ \ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ +\ income:salary\ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ +\f[] +.fi +.RE +.IP "2." 3 +With \f[C]\-\-cumulative\f[]: each column shows the ending balance for +that period, accumulating the changes across periods, starting from 0 at +the report start date: +.RS 4 +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-quarterly\ income\ expenses\ \-E\ \-\-cumulative +Ending\ balances\ (cumulative)\ in\ 2008: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008/03/31\ \ 2008/06/30\ \ 2008/09/30\ \ 2008/12/31\ +===================++================================================= +\ expenses:food\ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ +\ expenses:supplies\ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ +\ income:gifts\ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ +\ income:salary\ \ \ \ \ ||\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ $\-1\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ +\f[] +.fi +.RE +.IP "3." 3 +With \f[C]\-\-historical/\-H\f[]: each column shows the actual +historical ending balance for that period, accumulating the changes +across periods, starting from the actual balance at the report start +date. +This is useful eg for a multi\-period balance sheet, and when you are +showing only the data after a certain start date: +.RS 4 +.IP +.nf +\f[C] +$\ hledger\ balance\ ^assets\ ^liabilities\ \-\-quarterly\ \-\-historical\ \-\-begin\ 2008/4/1 +Ending\ balances\ (historical)\ in\ 2008/04/01\-2008/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008/06/30\ \ 2008/09/30\ \ 2008/12/31\ +======================++===================================== +\ assets:bank:checking\ ||\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ 0\ +\ assets:bank:saving\ \ \ ||\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ $1\ +\ assets:cash\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ $\-2\ \ \ \ \ \ \ \ \ $\-2\ \ \ \ \ \ \ \ \ $\-2\ +\ liabilities:debts\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ $1\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ 0\ +\f[] +.fi +.RE +.PP +Multi\-column balance reports display accounts in flat mode by default; +to see the hierarchy, use \f[C]\-\-tree\f[]. +.PP +With a reporting interval (like \f[C]\-\-quarterly\f[] above), the +report start/end dates will be adjusted if necessary so that they +encompass the displayed report periods. +This is so that the first and last periods will be \[lq]full\[rq] and +comparable to the others. +.PP +The \f[C]\-E/\-\-empty\f[] flag does two things in multicolumn balance +reports: first, the report will show all columns within the specified +report period (without \-E, leading and trailing columns with all zeroes +are not shown). +Second, all accounts which existed at the report start date will be +considered, not just the ones with activity during the report period +(use \-E to include low\-activity accounts which would otherwise would +be omitted). +.PP +The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing +the total for each row. +.PP +The \f[C]\-A/\-\-average\f[] flag adds a column showing the average +value in each row. +.PP +Here's an example of all three: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-Q\ income\ expenses\ \-\-tree\ \-ETA +Balance\ changes\ in\ 2008: + +\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2008q1\ \ 2008q2\ \ 2008q3\ \ 2008q4\ \ \ \ Total\ \ Average\ +============++=================================================== +\ expenses\ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $2\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ $2\ \ \ \ \ \ \ $1\ +\ \ \ food\ \ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ 0\ +\ \ \ supplies\ ||\ \ \ \ \ \ \ 0\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ 0\ +\ income\ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ $\-2\ \ \ \ \ \ $\-1\ +\ \ \ gifts\ \ \ \ ||\ \ \ \ \ \ \ 0\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ 0\ +\ \ \ salary\ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ 0\ +\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $\-1\ \ \ \ \ \ $1\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ 0\ + +#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are +\f[] +.fi +.SS Budgets +.PP +With \f[C]\-\-budget\f[] and a report interval, all periodic +transactions in your journal with that interval, active during the +requested report period, are interpreted as recurring budget goals for +the specified accounts (and subaccounts), and the report will show the +difference between actual and budgeted balances. +.PP +For example, you can take average monthly expenses in the common expense +categories to construct a minimal monthly budget: +.IP +.nf +\f[C] +;;\ Budget +~\ monthly +\ \ income\ \ $2000 +\ \ expenses:food\ \ \ \ $400 +\ \ expenses:bus\ \ \ \ \ $50 +\ \ expenses:movies\ \ $30 +\ \ assets:bank:checking + +;;\ Two\ months\ worth\ of\ expenses +2017\-11\-01 +\ \ income\ \ $1950 +\ \ expenses:food\ \ \ \ $396 +\ \ expenses:bus\ \ \ \ \ $49 +\ \ expenses:movies\ \ $30 +\ \ expenses:supplies\ \ $20 +\ \ assets:bank:checking + +2017\-12\-01 +\ \ income\ \ $2100 +\ \ expenses:food\ \ \ \ $412 +\ \ expenses:bus\ \ \ \ \ $53 +\ \ expenses:gifts\ \ \ $100 +\ \ assets:bank:checking +\f[] +.fi +.PP +You can now see a monthly budget performance report: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget +Balance\ changes\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ +=======================++================================================= +\ :expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ +\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ +\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ +\f[] +.fi +.PP +You can roll over unspent budgets to next period with +\f[C]\-\-cumulative\f[]: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative +Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\ +=======================++================================================= +\ :expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\ +\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\ +\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\ +\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +Accounts with no budget goals (not mentioned in the periodic +transactions) will be aggregated under \f[C]\f[], unless you +add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted +Balance\ changes\ in\ 2017/11/01\-2017/12/31: + +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\ +======================++================================================= +\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\ +\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\ +\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\ +\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\ +\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\ +\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ +\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ +\f[] +.fi +.PP +Note \[en]budget first arrived in hledger in 1.5 and is still pretty +young; join the discussions on mail list and issue tracker to help us +refine it. +.PP +For more examples, see Budgeting and Forecasting. +.SS Custom balance output +.PP +You can customise the layout of simple (non\-tabular) balance reports +with \f[C]\-\-format\ FMT\f[]: +.IP +.nf +\f[C] +$\ hledger\ balance\ \-\-format\ "%20(account)\ %12(total)" +\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ \ \ \ \ \ \ bank:saving\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ cash\ \ \ \ \ \ \ \ \ \ $\-2 +\ \ \ \ \ \ \ \ \ \ \ \ expenses\ \ \ \ \ \ \ \ \ \ \ $2 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ food\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ supplies\ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ income\ \ \ \ \ \ \ \ \ \ $\-2 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ gifts\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ salary\ \ \ \ \ \ \ \ \ \ $\-1 +\ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ $1 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. +It may contain any suitable text, with data fields interpolated like so: +.PP +\f[C]%[MIN][.MAX](FIELDNAME)\f[] +.IP \[bu] 2 +MIN pads with spaces to at least this width (optional) +.IP \[bu] 2 +MAX truncates at this width (optional) +.IP \[bu] 2 +FIELDNAME must be enclosed in parentheses, and can be one of: +.RS 2 +.IP \[bu] 2 +\f[C]depth_spacer\f[] \- a number of spaces equal to the account's +depth, or if MIN is specified, MIN * depth spaces. +.IP \[bu] 2 +\f[C]account\f[] \- the account's name +.IP \[bu] 2 +\f[C]total\f[] \- the account's balance/posted total, right justified +.RE +.PP +Also, FMT can begin with an optional prefix to control how +multi\-commodity amounts are rendered: +.IP \[bu] 2 +\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default) +.IP \[bu] 2 +\f[C]%^\f[] \- render on multiple lines, top\-aligned +.IP \[bu] 2 +\f[C]%,\f[] \- render on one line, comma\-separated +.PP +There are some quirks. +Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead +\f[C]%(account)\f[] has indentation built in. + Experimentation may be needed to get pleasing results. +.PP +Some example formats: +.IP \[bu] 2 +\f[C]%(total)\f[] \- the account's total +.IP \[bu] 2 +\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded +to 20 characters and clipped at 20 characters +.IP \[bu] 2 +\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50 +characters, total padded to 20 characters, with multiple commodities +rendered on one line +.IP \[bu] 2 +\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default +format for the single\-column balance report +.PP +This command also supports output destination and output format +selection. +.SS Colour support +.PP +The balance command shows negative amounts in red, if: +.IP \[bu] 2 +the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[] +.IP \[bu] 2 +the output is not being redirected or piped anywhere +.SS balancesheet +.PP +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). +It assumes that these accounts are under a top\-level \f[C]asset\f[] or +\f[C]liability\f[] account (case insensitive, plural forms also +allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +(bs) +.TP +.B \f[C]\-\-change\f[] +show balance change in each period, instead of historical ending +balances +.RS +.RE +.TP +.B \f[C]\-\-cumulative\f[] +show balance change accumulated across periods (in multicolumn reports), +instead of historical ending balances +.RS +.RE +.TP +.B \f[C]\-H\ \-\-historical\f[] +show historical ending balance in each period (includes postings before +report start date) (default) +.RS +.RE +.TP +.B \f[C]\-\-tree\f[] +show accounts as a tree; amounts include subaccounts (default in simple +reports) +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show accounts as a list; amounts exclude subaccounts except when account +is depth\-clipped (default in multicolumn reports) +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +show a row average column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-T\ \-\-row\-total\f[] +show a row total column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-N\ \-\-no\-total\f[] +don't show the final total row +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +omit N leading account name parts (in flat mode) +.RS +.RE +.TP +.B \f[C]\-\-no\-elide\f[] +don't squash boring parent accounts (in tree mode) +.RS +.RE +.TP +.B \f[C]\-\-format=LINEFORMAT\f[] +in single\-column balance reports: use this custom line format +.RS +.RE +.TP +.B \f[C]\-\-sort\-amount\f[] +sort by amount instead of account code/name +.RS +.RE +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ balancesheet +Balance\ Sheet + +Assets: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +Liabilities: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +As with multicolumn balance reports, you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +Normally balancesheet shows historical ending balances, which is what +you need for a balance sheet; note this means it ignores report begin +dates. +.PP +This command also supports output destination and output format +selection. +.SS balancesheetequity +.PP +Just like balancesheet, but also reports Equity (which it assumes is +under a top\-level \f[C]equity\f[] account). +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ balancesheetequity +Balance\ Sheet\ With\ Equity + +Assets: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-3\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +Liabilities: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities:debts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 + +Equity: +\ \ \ \ \ \ \ \ \ \ $1\ \ equity:owner +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ $1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.SS cashflow +.PP +This command displays a simple cashflow statement, showing changes in +\[lq]cash\[rq] accounts. +It assumes that these accounts are under a top\-level \f[C]asset\f[] +account (case insensitive, plural forms also allowed) and do not contain +\f[C]receivable\f[] or \f[C]A/R\f[] in their name. +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +(cf) +.TP +.B \f[C]\-\-change\f[] +show balance change in each period (default) +.RS +.RE +.TP +.B \f[C]\-\-cumulative\f[] +show balance change accumulated across periods (in multicolumn reports), +instead of changes during periods +.RS +.RE +.TP +.B \f[C]\-H\ \-\-historical\f[] +show historical ending balance in each period (includes postings before +report start date), instead of changes during each period +.RS +.RE +.TP +.B \f[C]\-\-tree\f[] +show accounts as a tree; amounts include subaccounts (default in simple +reports) +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show accounts as a list; amounts exclude subaccounts except when account +is depth\-clipped (default in multicolumn reports) +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +show a row average column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-T\ \-\-row\-total\f[] +show a row total column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-N\ \-\-no\-total\f[] +don't show the final total row (in simple reports) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +omit N leading account name parts (in flat mode) +.RS +.RE +.TP +.B \f[C]\-\-no\-elide\f[] +don't squash boring parent accounts (in tree mode) +.RS +.RE +.TP +.B \f[C]\-\-format=LINEFORMAT\f[] +in single\-column balance reports: use this custom line format +.RS +.RE +.TP +.B \f[C]\-\-sort\-amount\f[] +sort by amount instead of account code/name +.RS +.RE +.PP +Example: +.IP +.nf +\f[C] +$\ hledger\ cashflow +Cashflow\ Statement + +Cash\ flows: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ bank:saving +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ \ \ cash +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +Normally cashflow shows changes in assets per period, though as with +multicolumn balance reports you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. +.SS check\-dates +.PP +Check that transactions are sorted by increasing date. +With a query, only matched transactions' dates are checked. +.SS check\-dupes +.PP +Report account names having the same leaf but different prefixes. +An example: http://stefanorodighiero.net/software/hledger\-dupes.html +.SS close +.PP +Print closing/opening transactions that bring some or all account +balances to zero and back. +Can be useful for bringing asset/liability balances across file +boundaries, or for closing out income/expenses for a period. +This was formerly called \[lq]equity\[rq], as in Ledger, and that alias +is also accepted. +See close \[en]help for more. +.SS help +.PP +Show any of the hledger manuals. +.PP +The \f[C]help\f[] command displays any of the main hledger manuals, in +one of several ways. +Run it with no argument to list the manuals, or provide a full or +partial manual name to select one. +.PP +hledger manuals are available in several formats. +hledger help will use the first of these display methods that it finds: +info, man, $PAGER, less, stdout (or when non\-interactive, just stdout). +You can force a particular viewer with the \f[C]\-\-info\f[], +\f[C]\-\-man\f[], \f[C]\-\-pager\f[], \f[C]\-\-cat\f[] flags. +.IP +.nf +\f[C] +$\ hledger\ help +Please\ choose\ a\ manual\ by\ typing\ "hledger\ help\ MANUAL"\ (a\ substring\ is\ ok). +Manuals:\ hledger\ hledger\-ui\ hledger\-web\ hledger\-api\ journal\ csv\ timeclock\ timedot +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ help\ h\ \-\-man + +hledger(1)\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger\ User\ Manuals\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ hledger(1) + +NAME +\ \ \ \ \ \ \ hledger\ \-\ a\ command\-line\ accounting\ tool + +SYNOPSIS +\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [ARGS] +\ \ \ \ \ \ \ hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [ARGS] +\ \ \ \ \ \ \ hledger + +DESCRIPTION +\ \ \ \ \ \ \ hledger\ \ is\ \ a\ \ cross\-platform\ \ program\ \ for\ tracking\ money,\ time,\ or\ any +\&... +\f[] +.fi +.SS import +.PP +Read new transactions added to each FILE since last run, and add them to +the main journal file. +.TP +.B \f[C]\-\-dry\-run\f[] +just show the transactions to be imported +.RS +.RE +.PP +The input files are specified as arguments \- no need to write \-f +before each one. +So eg to add new transactions from all CSV files to the main journal, +it's just: \f[C]hledger\ import\ *.csv\f[] +.PP +New transactions are detected in the same way as print \[en]new: by +assuming transactions are always added to the input files in increasing +date order, and by saving \f[C]\&.latest.FILE\f[] state files. +.PP +The \[en]dry\-run output is in journal format, so you can filter it, eg +to see only uncategorised transactions: +.IP +.nf +\f[C] +$\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\-assertions +\f[] +.fi +.SS incomestatement +.PP +This command displays a simple income statement, showing revenues and +expenses during a period. +It assumes that these accounts are under a top\-level \f[C]revenue\f[] +or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural +forms also allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +(is) +.TP +.B \f[C]\-\-change\f[] +show balance change in each period (default) +.RS +.RE +.TP +.B \f[C]\-\-cumulative\f[] +show balance change accumulated across periods (in multicolumn reports), +instead of changes during periods +.RS +.RE +.TP +.B \f[C]\-H\ \-\-historical\f[] +show historical ending balance in each period (includes postings before +report start date), instead of changes during each period +.RS +.RE +.TP +.B \f[C]\-\-tree\f[] +show accounts as a tree; amounts include subaccounts (default in simple +reports) +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show accounts as a list; amounts exclude subaccounts except when account +is depth\-clipped (default in multicolumn reports) +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +show a row average column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-T\ \-\-row\-total\f[] +show a row total column (in multicolumn mode) +.RS +.RE +.TP +.B \f[C]\-N\ \-\-no\-total\f[] +don't show the final total row +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +omit N leading account name parts (in flat mode) +.RS +.RE +.TP +.B \f[C]\-\-no\-elide\f[] +don't squash boring parent accounts (in tree mode) +.RS +.RE +.TP +.B \f[C]\-\-format=LINEFORMAT\f[] +in single\-column balance reports: use this custom line format +.RS +.RE +.TP +.B \f[C]\-\-sort\-amount\f[] +sort by amount instead of account code/name +.RS +.RE +.PP +This command displays a simple income statement. +It currently assumes that you have top\-level accounts named +\f[C]income\f[] (or \f[C]revenue\f[]) and \f[C]expense\f[] (plural forms +also allowed.) +.IP +.nf +\f[C] +$\ hledger\ incomestatement +Income\ Statement + +Revenues: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ gifts +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ salary +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +Expenses: +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2 + +Total: +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +With a reporting interval, multiple columns will be shown, one for each +report period. +Normally incomestatement shows revenues/expenses per period, though as +with multicolumn balance reports you can alter the report mode with +\f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. +.SS prices +.PP +Print all market prices from the journal. +.SS print +.PP +Show transactions from the journal. +Aliases: p, txns. +.TP +.B \f[C]\-m\ STR\ \-\-match=STR\f[] +show the transaction whose description is most similar to STR, and is +most recent +.RS +.RE +.TP +.B \f[C]\-\-new\f[] +show only newer\-dated transactions added in each file since last run +.RS +.RE +.TP +.B \f[C]\-x\ \ \ \ \ \-\-explicit\f[] +show all amounts explicitly +.RS +.RE +.TP +.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] +select the output format. +Supported formats: txt, csv. +.RS +.RE +.TP +.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] +write output to FILE. +A file extension matching one of the above formats selects that format. +.RS +.RE +.IP +.nf +\f[C] +$\ hledger\ print +2008/01/01\ income +\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +2008/06/01\ gift +\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1 + +2008/06/02\ save +\ \ \ \ assets:bank:saving\ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1 + +2008/06/03\ *\ eat\ &\ shop +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ expenses:supplies\ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2 + +2008/12/31\ *\ pay\ off +\ \ \ \ liabilities:debts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1 +\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1 +\f[] +.fi +.PP +The print command displays full journal entries (transactions) from the +journal file in date order, tidily formatted. +print's output is always a valid hledger journal. +It preserves all transaction information, but it does not preserve +directives or inter\-transaction comments +.PP +Normally, the journal entry's explicit or implicit amount style is +preserved. +Ie when an amount is omitted in the journal, it will be omitted in the +output. +You can use the \f[C]\-x\f[]/\f[C]\-\-explicit\f[] flag to make all +amounts explicit, which can be useful for troubleshooting or for making +your journal more readable and robust against data entry errors. +Note, \f[C]\-x\f[] will cause postings with a multi\-commodity amount +(these can arise when a multi\-commodity transaction has an implicit +amount) will be split into multiple single\-commodity postings, for +valid journal output. +.PP +With \f[C]\-B\f[]/\f[C]\-\-cost\f[], amounts with transaction prices are +converted to cost using that price. +This can be used for troubleshooting. +.PP +With \f[C]\-m\f[]/\f[C]\-\-match\f[] and a STR argument, print will show +at most one transaction: the one one whose description is most similar +to STR, and is most recent. +STR should contain at least two characters. +If there is no similar\-enough match, no transaction will be shown. +.PP +With \f[C]\-\-new\f[], for each FILE being read, hledger reads (and +writes) a special state file (\f[C]\&.latest.FILE\f[] in the same +directory), containing the latest transaction date(s) that were seen +last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. +This is useful for ignoring already\-seen entries in import data, such +as downloaded CSV files. +Eg: +.IP +.nf +\f[C] +$\ hledger\ \-f\ bank1.csv\ print\ \-\-new +#\ shows\ transactions\ added\ since\ last\ print\ \-\-new\ on\ this\ file +\f[] +.fi +.PP +This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. +See also the import command. +.PP +This command also supports output destination and output format +selection. +Here's an example of print's CSV output: +.IP +.nf +\f[C] +$\ hledger\ print\ \-Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting\-status","posting\-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","\-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","\-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","\-1","$","1","","","" +"4","2008/06/03","","*","","eat\ &\ shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat\ &\ shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat\ &\ shop","","assets:cash","\-2","$","2","","","" +"5","2008/12/31","","*","","pay\ off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay\ off","","assets:bank:checking","\-1","$","1","","","" +\f[] +.fi +.IP \[bu] 2 +There is one CSV record per posting, with the parent transaction's +fields repeated. +.IP \[bu] 2 +The \[lq]txnidx\[rq] (transaction index) field shows which postings +belong to the same transaction. +(This number might change if transactions are reordered within the file, +files are parsed/included in a different order, etc.) +.IP \[bu] 2 +The amount is separated into \[lq]commodity\[rq] (the symbol) and +\[lq]amount\[rq] (numeric quantity) fields. +.IP \[bu] 2 +The numeric amount is repeated in either the \[lq]credit\[rq] or +\[lq]debit\[rq] column, for convenience. +(Those names are not accurate in the accounting sense; it just puts +negative amounts under credit and zero or greater amounts under debit.) +.SS print\-unique +.PP +Print transactions which do not reuse an already\-seen description. +.SS register +.PP +Show postings and their running total. +Aliases: r, reg. +.TP +.B \f[C]\-\-cumulative\f[] +show running total from report start date (default) +.RS +.RE +.TP +.B \f[C]\-H\ \-\-historical\f[] +show historical running total/balance (includes postings before report +start date) +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +show running average of posting amounts instead of total (implies +\[en]empty) +.RS +.RE +.TP +.B \f[C]\-r\ \-\-related\f[] +show postings' siblings instead +.RS +.RE +.TP +.B \f[C]\-w\ N\ \-\-width=N\f[] +set output width (default: terminal width or COLUMNS. +\-wN,M sets description width as well) +.RS +.RE +.TP +.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] +select the output format. +Supported formats: txt, csv. +.RS +.RE +.TP +.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] +write output to FILE. +A file extension matching one of the above formats selects that format. +.RS +.RE +.PP +The register command displays postings, one per line, and their running +total. +This is typically used with a query selecting a particular account, to +see that account's activity: +.IP +.nf +\f[C] +$\ hledger\ register\ checking +2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1 +2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2 +2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1 +2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +The \f[C]\-\-historical\f[]/\f[C]\-H\f[] flag adds the balance from any +undisplayed prior postings to the running total. +This is useful when you want to see only recent activity, with a +historically accurate running balance: +.IP +.nf +\f[C] +$\ hledger\ register\ checking\ \-b\ 2008/6\ \-\-historical +2008/06/01\ gift\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $2 +2008/06/02\ save\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ $1 +2008/12/31\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.PP +The \f[C]\-\-depth\f[] option limits the amount of sub\-account detail +displayed. +.PP +The \f[C]\-\-average\f[]/\f[C]\-A\f[] flag shows the running average +posting amount instead of the running total (so, the final number +displayed is the average for the whole report period). +This flag implies \f[C]\-\-empty\f[] (see below). +It is affected by \f[C]\-\-historical\f[]. +It works best when showing just one account and one commodity. +.PP +The \f[C]\-\-related\f[]/\f[C]\-r\f[] flag shows the \f[I]other\f[] +postings in the transactions of the postings which would normally be +shown. +.PP +With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: +.IP +.nf +\f[C] +$\ hledger\ register\ \-\-monthly\ income +2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 +2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2 +\f[] +.fi +.PP +Periods with no activity, and summary postings with a zero amount, are +not shown by default; use the \f[C]\-\-empty\f[]/\f[C]\-E\f[] flag to +see them: +.IP +.nf +\f[C] +$\ hledger\ register\ \-\-monthly\ income\ \-E +2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:salary\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 +2008/02\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 +2008/03\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 +2008/04\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 +2008/05\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-1 +2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-2 +2008/07\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 +2008/08\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 +2008/09\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 +2008/10\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 +2008/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 +2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ $\-2 +\f[] +.fi +.PP +Often, you'll want to see just one line per interval. +The \f[C]\-\-depth\f[] option helps with this, causing subaccounts to be +aggregated: +.IP +.nf +\f[C] +$\ hledger\ register\ \-\-monthly\ assets\ \-\-depth\ 1h +2008/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ \ \ \ \ \ \ \ \ $1 +2008/06\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ \ \ 0 +2008/12\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ \ \ \ \ \ \ \ \ \ $\-1 +\f[] +.fi +.PP +Note when using report intervals, if you specify start/end dates these +will be adjusted outward if necessary to contain a whole number of +intervals. +This ensures that the first and last intervals are full length and +comparable to the others in the report. +.SS Custom register output +.PP +register uses the full terminal width by default, except on windows. +You can override this by setting the \f[C]COLUMNS\f[] environment +variable (not a bash shell variable) or by using the +\f[C]\-\-width\f[]/\f[C]\-w\f[] option. +.PP +The description and account columns normally share the space equally +(about half of (width \- 40) each). +You can adjust this by adding a description width as part of +\[en]width's argument, comma\-separated: \f[C]\-\-width\ W,D\f[] . +Here's a diagram: +.IP +.nf +\f[C] +<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ width\ (W)\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-> +date\ (10)\ \ description\ (D)\ \ \ \ \ \ \ account\ (W\-41\-D)\ \ \ \ \ amount\ (12)\ \ \ balance\ (12) +DDDDDDDDDD\ dddddddddddddddddddd\ \ aaaaaaaaaaaaaaaaaaa\ \ AAAAAAAAAAAA\ \ AAAAAAAAAAAA +\f[] +.fi +.PP +and some examples: +.IP +.nf +\f[C] +$\ hledger\ reg\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ terminal\ width\ (or\ 80\ on\ windows) +$\ hledger\ reg\ \-w\ 100\ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ use\ width\ 100 +$\ COLUMNS=100\ hledger\ reg\ \ \ \ \ \ \ \ \ #\ set\ with\ one\-time\ environment\ variable +$\ export\ COLUMNS=100;\ hledger\ reg\ #\ set\ till\ session\ end\ (or\ window\ resize) +$\ hledger\ reg\ \-w\ 100,40\ \ \ \ \ \ \ \ \ \ \ #\ set\ overall\ width\ 100,\ description\ width\ 40 +$\ hledger\ reg\ \-w\ $COLUMNS,40\ \ \ \ \ \ #\ use\ terminal\ width,\ and\ set\ description\ width +\f[] +.fi +.PP +This command also supports output destination and output format +selection. +.SS register\-match +.PP +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. +Helps ledger\-autosync detect already\-seen transactions when importing. +.SS rewrite +.PP +Print all transactions, adding custom postings to the matched ones. +.SS stats +.PP +Show some journal statistics. +.TP +.B \f[C]\-o\ FILE\ \-\-output\-file=FILE\f[] +write output to FILE. +A file extension matching one of the above formats selects that format. +.RS +.RE +.IP +.nf +\f[C] +$\ hledger\ stats +Main\ journal\ file\ \ \ \ \ \ \ \ :\ /src/hledger/examples/sample.journal +Included\ journal\ files\ \ \ :\ +Transactions\ span\ \ \ \ \ \ \ \ :\ 2008\-01\-01\ to\ 2009\-01\-01\ (366\ days) +Last\ transaction\ \ \ \ \ \ \ \ \ :\ 2008\-12\-31\ (2333\ days\ ago) +Transactions\ \ \ \ \ \ \ \ \ \ \ \ \ :\ 5\ (0.0\ per\ day) +Transactions\ last\ 30\ days:\ 0\ (0.0\ per\ day) +Transactions\ last\ 7\ days\ :\ 0\ (0.0\ per\ day) +Payees/descriptions\ \ \ \ \ \ :\ 5 +Accounts\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 8\ (depth\ 3) +Commodities\ \ \ \ \ \ \ \ \ \ \ \ \ \ :\ 1\ ($) +\f[] +.fi +.PP +The stats command displays summary information for the whole journal, or +a matched part of it. +With a reporting interval, it shows a report for each report period. +.PP +This command also supports output destination and output format +selection. +.SS tags +.PP +List all the tag names used in the journal. +With a TAGREGEX argument, only tag names matching the regular expression +(case insensitive) are shown. +With additional QUERY arguments, only transactions matching the query +are considered. +.SS test +.PP +Run built\-in unit tests. +.IP +.nf +\f[C] +$\ hledger\ test +Cases:\ 74\ \ Tried:\ 74\ \ Errors:\ 0\ \ Failures:\ 0 +\f[] +.fi +.PP +This command runs hledger's built\-in unit tests and displays a quick +report. +With a regular expression argument, it selects only tests with matching +names. +It's mainly used in development, but it's also nice to be able to check +your hledger executable for smoke at any time. +.SH ADD\-ON COMMANDS +.PP +hledger also searches for external add\-on commands, and will include +these in the commands list. +These are programs or scripts in your PATH whose name starts with +\f[C]hledger\-\f[] and ends with a recognised file extension (currently: +no extension, \f[C]bat\f[],\f[C]com\f[],\f[C]exe\f[], +\f[C]hs\f[],\f[C]lhs\f[],\f[C]pl\f[],\f[C]py\f[],\f[C]rb\f[],\f[C]rkt\f[],\f[C]sh\f[]). +.PP +Add\-ons can be invoked like any hledger command, but there are a few +things to be aware of. +Eg if the \f[C]hledger\-web\f[] add\-on is installed, +.IP \[bu] 2 +\f[C]hledger\ \-h\ web\f[] shows hledger's help, while +\f[C]hledger\ web\ \-h\f[] shows hledger\-web's help. +.IP \[bu] 2 +Flags specific to the add\-on must have a preceding \f[C]\-\-\f[] to +hide them from hledger. +So \f[C]hledger\ web\ \-\-serve\ \-\-port\ 9000\f[] will be rejected; +you must use \f[C]hledger\ web\ \-\-\ \-\-serve\ \-\-port\ 9000\f[]. +.IP \[bu] 2 +You can always run add\-ons directly if preferred: +\f[C]hledger\-web\ \-\-serve\ \-\-port\ 9000\f[]. +.PP +Add\-ons are a relatively easy way to add local features or experiment +with new ideas. +They can be written in any language, but haskell scripts have a big +advantage: they can use the same hledger (and haskell) library functions +that built\-in commands do, for command\-line options, journal parsing, +reporting, etc. +.PP +Here are some hledger add\-ons available: +.SS Official add\-ons +.PP +These are maintained and released along with hledger. +.SS api +.PP +hledger\-api serves hledger data as a JSON web API. +.SS ui +.PP +hledger\-ui provides an efficient curses\-style interface. +.SS web +.PP +hledger\-web provides a simple web interface. +.SS Third party add\-ons +.PP +These are maintained separately, and usually updated shortly after a +hledger release. +.SS diff +.PP +hledger\-diff shows differences in an account's transactions between one +journal file and another. +.SS iadd +.PP +hledger\-iadd is a curses\-style, more interactive replacement for the +add command. +.SS interest +.PP +hledger\-interest generates interest transactions for an account +according to various schemes. +.SS irr +.PP +hledger\-irr calculates the internal rate of return of an investment +account. +.SS Experimental add\-ons +.PP +These are available in source form in the hledger repo's bin/ directory; +installing them is pretty easy. +They may be less mature and documented than built\-in commands. +Reading and tweaking these is a good way to start making your own! +.SS autosync +.PP +hledger\-autosync is a symbolic link for easily running +ledger\-autosync, if installed. +ledger\-autosync does deduplicating conversion of OFX data and some CSV +formats, and can also download the data if your bank offers OFX Direct +Connect. +.SS chart +.PP +hledger\-chart.hs is an old pie chart generator, in need of some love. +.SS check +.PP +hledger\-check.hs checks more powerful account balance assertions. +.SH ENVIRONMENT +.PP +\f[B]COLUMNS\f[] The screen width used by the register command. +Default: the full terminal width. +.PP +\f[B]LEDGER_FILE\f[] The journal file path when not specified with +\f[C]\-f\f[]. +Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps +\f[C]C:/Users/USER/.hledger.journal\f[]). +.SH FILES +.PP +Reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +.SH BUGS +.PP +The need to precede addon command options with \f[C]\-\-\f[] when +invoked from hledger is awkward. +.PP +When input data contains non\-ascii characters, a suitable system locale +must be configured (or there will be an unhelpful error). +Eg on POSIX, set LANG to something other than C. +.PP +In a Microsoft Windows CMD window, non\-ascii characters and colours are +not supported. +.PP +In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger +add. +.PP +Not all of Ledger's journal file syntax is supported. +See file format differences. +.PP +On large data files, hledger is slower and uses more memory than Ledger. +.SH TROUBLESHOOTING +.PP +Here are some issues you might encounter when you run hledger (and +remember you can also seek help from the IRC channel, mail list or bug +tracker): +.PP +\f[B]Successfully installed, but \[lq]No command `hledger' +found\[rq]\f[] +.PD 0 +.P +.PD +stack and cabal install binaries into a special directory, which should +be added to your PATH environment variable. +Eg on unix\-like systems, that is ~/.local/bin and ~/.cabal/bin +respectively. +.PP +\f[B]I set a custom LEDGER_FILE, but hledger is still using the default +file\f[] +.PD 0 +.P +.PD +\f[C]LEDGER_FILE\f[] should be a real environment variable, not just a +shell variable. +The command \f[C]env\ |\ grep\ LEDGER_FILE\f[] should show it. +You may need to use \f[C]export\f[]. +Here's an explanation. +.PP +\f[B]\[lq]Illegal byte sequence\[rq] or \[lq]Invalid or incomplete +multibyte or wide character\[rq] errors\f[] +.PD 0 +.P +.PD +In order to handle non\-ascii letters and symbols (like £), hledger +needs an appropriate locale. +This is usually configured system\-wide; you can also configure it +temporarily. +The locale may need to be one that supports UTF\-8, if you built hledger +with GHC < 7.2 (or possibly always, I'm not sure yet). +.PP +Here's an example of setting the locale temporarily, on ubuntu +gnu/linux: +.IP +.nf +\f[C] +$\ file\ my.journal +my.journal:\ UTF\-8\ Unicode\ text\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ the\ file\ is\ UTF8\-encoded +$\ locale\ \-a +C +en_US.utf8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ <\-\ a\ UTF8\-aware\ locale\ is\ available +POSIX +$\ LANG=en_US.utf8\ hledger\ \-f\ my.journal\ print\ \ \ #\ <\-\ use\ it\ for\ this\ command +\f[] +.fi +.PP +Here's one way to set it permanently, there are probably better ways: +.IP +.nf +\f[C] +$\ echo\ "export\ LANG=en_US.UTF\-8"\ >>~/.bash_profile +$\ bash\ \-\-login +\f[] +.fi +.PP +If we preferred to use eg \f[C]fr_FR.utf8\f[], we might have to install +that first: +.IP +.nf +\f[C] +$\ apt\-get\ install\ language\-pack\-fr +$\ locale\ \-a +C +en_US.utf8 +fr_BE.utf8 +fr_CA.utf8 +fr_CH.utf8 +fr_FR.utf8 +fr_LU.utf8 +POSIX +$\ LANG=fr_FR.utf8\ hledger\ \-f\ my.journal\ print +\f[] +.fi +.PP +Note some platforms allow variant locale spellings, but not all (ubuntu +accepts \f[C]fr_FR.UTF8\f[], mac osx requires exactly +\f[C]fr_FR.UTF\-8\f[]). + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger.info @@ -0,0 +1,2527 @@ +This is hledger.info, produced by makeinfo version 6.5 from stdin. + + +File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) + +hledger(1) hledger 1.9 +********************** + +This is hledger's command-line interface (there are also curses and web +interfaces). Its basic function is to read a plain text file describing +financial transactions (in accounting terms, a general journal) and +print useful reports on standard output, or export them as CSV. hledger +can also read some other file formats such as CSV files, translating +them to journal format. Additionally, hledger lists other hledger-* +executables found in the user's $PATH and can invoke them as +subcommands. + + hledger reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). If using '$LEDGER_FILE', note this +must be a real environment variable, not a shell variable. You can +specify standard input with '-f-'. + + Transactions are dated movements of money between two (or more) named +accounts, and are recorded with journal entries like this: + +2015/10/16 bought food + expenses:food $10 + assets:cash + + For more about this format, see hledger_journal(5). + + Most users use a text editor to edit the journal, usually with an +editor mode such as ledger-mode for added convenience. hledger's +interactive add command is another way to record new transactions. +hledger never changes existing transactions. + + To get started, you can either save some entries like the above in +'~/.hledger.journal', or run 'hledger add' and follow the prompts. Then +try some commands like 'hledger print' or 'hledger balance'. Run +'hledger' with no arguments for a list of commands. +* Menu: + +* EXAMPLES:: +* OPTIONS:: +* QUERIES:: +* COMMANDS:: +* ADD-ON COMMANDS:: + + +File: hledger.info, Node: EXAMPLES, Next: OPTIONS, Prev: Top, Up: Top + +1 EXAMPLES +********** + +Two simple transactions in hledger journal format: + +2015/9/30 gift received + assets:cash $20 + income:gifts + +2015/10/16 farmers market + expenses:food $10 + assets:cash + + Some basic reports: + +$ hledger print +2015/09/30 gift received + assets:cash $20 + income:gifts $-20 + +2015/10/16 farmers market + expenses:food $10 + assets:cash $-10 + +$ hledger accounts --tree +assets + cash +expenses + food +income + gifts + +$ hledger balance + $10 assets:cash + $10 expenses:food + $-20 income:gifts +-------------------- + 0 + +$ hledger register cash +2015/09/30 gift received assets:cash $20 $20 +2015/10/16 farmers market assets:cash $-10 $10 + + More commands: + +$ hledger # show available commands +$ hledger add # add more transactions to the journal file +$ hledger balance # all accounts with aggregated balances +$ hledger balance --help # show detailed help for balance command +$ hledger balance --depth 1 # only top-level accounts +$ hledger register # show account postings, with running total +$ hledger reg income # show postings to/from income accounts +$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account +$ hledger print desc:shop # show transactions with shop in the description +$ hledger activity -W # show transaction counts per week as a bar chart + + +File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top + +2 OPTIONS +********* + +* Menu: + +* General options:: +* Command options:: +* Command arguments:: +* Argument files:: +* Special characters:: +* Input files:: +* Smart dates:: +* Report start & end date:: +* Report intervals:: +* Period expressions:: +* Depth limiting:: +* Pivoting:: +* Cost:: +* Market value:: +* Combining -B and -V:: +* Output destination:: +* Output format:: +* Regular expressions:: + + +File: hledger.info, Node: General options, Next: Command options, Up: OPTIONS + +2.1 General options +=================== + +To see general usage help, including general options which are supported +by most hledger commands, run 'hledger -h'. + + General help options: + +'-h --help' + + show general usage (or after COMMAND, command usage) +'--version' + + show 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') +'--rules-file=RULESFILE' + + Conversion rules file to use when reading CSV (default: FILE.rules) +'--alias=OLD=NEW' + + rename accounts named OLD to NEW +'--anon' + + anonymize accounts and payees +'--pivot FIELDNAME' + + use some other field or tag for the account name +'-I --ignore-assertions' + + ignore any failing balance assertions + + General reporting options: + +'-b --begin=DATE' + + include postings/txns on or after this date +'-e --end=DATE' + + include postings/txns before this date +'-D --daily' + + multiperiod/multicolumn report by day +'-W --weekly' + + multiperiod/multicolumn report by week +'-M --monthly' + + multiperiod/multicolumn report by month +'-Q --quarterly' + + multiperiod/multicolumn report by quarter +'-Y --yearly' + + multiperiod/multicolumn report by year +'-p --period=PERIODEXP' + + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) +'--date2' + + match the secondary date instead (see command help for other + effects) +'-U --unmarked' + + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' + + include only pending postings/txns +'-C --cleared' + + include only cleared postings/txns +'-R --real' + + include only non-virtual postings +'-NUM --depth=NUM' + + hide/aggregate accounts or postings more than NUM levels deep +'-E --empty' + + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) +'-B --cost' + + convert amounts to their cost at transaction time (using the + transaction price, if any) +'-V --value' + + convert amounts to their market value on the report end date (using + the most recent applicable market price, if any) +'--auto' + + apply automated posting rules to modify transactions. +'--forecast' + + apply periodic transaction rules to generate future transactions, + to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, +the last one takes precedence. + + Some reporting options can also be written as query arguments. + + +File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: OPTIONS + +2.2 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 addon, you may need to put its +options after a double-hyphen, eg: 'hledger ui -- --watch'. Or, you can +run the addon executable directly: 'hledger-ui --watch'. + + +File: hledger.info, Node: Command arguments, Next: Argument files, Prev: Command options, Up: OPTIONS + +2.3 Command arguments +===================== + +Most hledger commands accept arguments after the command name, which are +often a query, filtering the data in some way. + + +File: hledger.info, Node: Argument files, Next: Special characters, Prev: Command arguments, Up: OPTIONS + +2.4 Argument files +================== + +You can save a set of command line options/arguments in a file, one per +line, and then reuse them by writing '@FILENAME' in a command line. To +prevent this expansion of '@'-arguments, precede them with a '--' +argument. For more, see Save frequently used options. + + +File: hledger.info, Node: Special characters, Next: Input files, Prev: Argument files, Up: OPTIONS + +2.5 Special characters +====================== + +Option and argument values which contain problematic characters should +be escaped with double quotes, backslashes, or (best) single quotes. +Problematic characters means spaces, and also characters which are +significant to your command shell, such as less-than/greater-than. Eg: +'hledger register -p 'last year' "accounts receivable +(receivable|payable)" amt:\>100'. + + Characters which are significant both to the shell and in regular +expressions sometimes need to be double-escaped. These include +parentheses, the pipe symbol and the dollar sign. Eg, to match the +dollar symbol, bash users should do: 'hledger balance cur:'\$'' or +'hledger balance cur:\\$'. + + When hledger is invoking an addon executable (like hledger-ui), +options and arguments get de-escaped once more, so you might need +_triple_-escaping. Eg: 'hledger ui cur:'\\$'' or 'hledger ui cur:\\\\$' +in bash. (The number of backslashes in fish shell is left as an +exercise for the reader.) + + Inside a file used for argument expansion, one less level of escaping +is enough. (And in this case, backslashes seem to work better than +quotes. Eg: 'cur:\$'). + + If in doubt, keep things simple: + + * run add-on executables directly + * write options after the command + * enclose problematic args in single quotes + * if needed, also add a backslash to escape regexp metacharacters + + If you're really stumped, add '--debug=2' to troubleshoot. + + +File: hledger.info, Node: Input files, Next: Smart dates, Prev: Special characters, Up: OPTIONS + +2.6 Input files +=============== + +hledger reads transactions from a data file (and the add command writes +to it). By default this file is '$HOME/.hledger.journal' (or on +Windows, something like 'C:/Users/USER/.hledger.journal'). You can +override this with the '$LEDGER_FILE' environment variable: + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with the '-f/--file' option: + +$ hledger -f /some/file stats + + The file name '-' (hyphen) means standard input: + +$ cat some.journal | hledger -f- + + Usually the data file is in hledger's journal format, but it can also +be one of several other formats, listed below. hledger detects the +format automatically based on the file extension, or if that is not +recognised, by trying each built-in "reader" in turn: + +Reader: Reads: Used for file extensions: +---------------------------------------------------------------------------- +'journal' hledger's journal format, also '.journal' '.j' + some Ledger journals '.hledger' '.ledger' +'timeclock' timeclock files (precise time '.timeclock' + logging) +'timedot' timedot files (approximate time '.timedot' + logging) +'csv' comma-separated values (data '.csv' + interchange) + + If needed (eg to ensure correct error messages when a file has the +"wrong" extension), you can force a specific reader/format by prepending +it to the file path with a colon. Examples: + +$ hledger -f csv:/some/csv-file.dat stats +$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- + + You can also specify multiple '-f' options, to read multiple files as +one big journal. There are some limitations with this: + + * directives in one file will not affect the other files + * balance assertions will not see any account balances from previous + files + + If you need those, either use the include directive, or concatenate +the files, eg: 'cat a.journal b.journal | hledger -f- CMD'. + + +File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS + +2.7 Smart dates +=============== + +hledger's user interfaces accept a flexible "smart date" syntax (unlike +dates in the journal file). Smart dates allow some english words, can +be relative to today's date, and can have less-significant date parts +omitted (defaulting to 1). + + Examples: + +'2009/1/1', '2009/01/01', '2009-1-1', '2009.1.1' simple dates, several separators allowed +'2009/1', '2009' same as above - a missing day or month defaults to 1 +'1/1', 'january', 'jan', 'this year' relative dates, meaning january 1 of the current year +'next year' january 1 of next year +'this month' the 1st of the current month +'this week' the most recent monday +'last week' the monday of the week before this one +'lastweek' spaces are optional +'today', 'yesterday', 'tomorrow' + + +File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS + +2.8 Report start & end date +=========================== + +Most hledger reports show the full span of time represented by the +journal data, by default. So, the effective report start and end dates +will be the earliest and latest transaction or posting dates found in +the journal. + + Often you will want to see a shorter time span, such as the current +month. You can specify a start and/or end date using '-b/--begin', +'-e/--end', '-p/--period' or a 'date:' query (described below). All of +these accept the smart date syntax. One important thing to be aware of +when specifying end dates: as in Ledger, end dates are exclusive, so you +need to write the date _after_ the last day you want to include. + + Examples: + +'-b 2016/3/17' begin on St. Patrick's day 2016 +'-e 12/1' end at the start of december 1st of the current year (11/30 will be the last date included) +'-b thismonth' all transactions on or after the 1st of the current month +'-p thismonth' all transactions in the current month +'date:2016/3/17-' the above written as queries instead +'date:-12/1' +'date:thismonth-' +'date:thismonth' + + +File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS + +2.9 Report intervals +==================== + +A report interval can be specified so that commands like register, +balance and activity will divide their reports into multiple subperiods. +The basic intervals can be selected with one of '-D/--daily', +'-W/--weekly', '-M/--monthly', '-Q/--quarterly', or '-Y/--yearly'. More +complex intervals may be specified with a period expression. Report +intervals can not be specified with a query, currently. + + +File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS + +2.10 Period expressions +======================= + +The '-p/--period' option accepts period expressions, a shorthand way of +expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of +2009. Note, hledger always treats start dates as inclusive and end +dates as exclusive: + + '-p "from 2009/1/1 to 2009/4/1"' + + Keywords like "from" and "to" are optional, and so are the spaces, as +long as you don't run two dates together. "to" can also be written as +"-". These are equivalent to the above: + +'-p "2009/1/1 2009/4/1"' +'-p2009/1/1to2009/4/1' +'-p2009/1/1-2009/4/1' + + Dates are smart dates, so if the current year is 2009, the above can +also be written as: + +'-p "1/1 4/1"' +'-p "january-apr"' +'-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction in your journal: + +'-p "from 2009/1/1"' everything after january 1, 2009 +'-p "from 2009/1"' the same +'-p "from 2009"' the same +'-p "to 2009"' everything before january 1, 2009 + + A single date with no "from" or "to" defines both the start and end +date like so: + +'-p "2009"' the year 2009; equivalent to "2009/1/1 to 2010/1/1" +'-p "2009/1"' the month of jan; equivalent to "2009/1/1 to 2009/2/1" +'-p "2009/1/1"' just that day; equivalent to "2009/1/1 to 2009/1/2" + + The argument of '-p' can also begin with, or be, a report interval +expression. The basic report intervals are 'daily', 'weekly', +'monthly', 'quarterly', or 'yearly', which have the same effect as the +'-D','-W','-M','-Q', or '-Y' flags. Between report interval and +start/end dates (if any), the word 'in' is optional. Examples: + +'-p "weekly from 2009/1/1 to 2009/4/1"' +'-p "monthly in 2008"' +'-p "quarterly"' + + Note that 'weekly', 'monthly', 'quarterly' and 'yearly' intervals +will always start on the first day on week, month, quarter or year +accordingly, and will end on the last day of same period, even if +associated period expression specifies different explicit start and end +date. + + For example: + +'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceeding Monday +'-p "monthly in 2008/11/25"' - starts on 2018/11/01 +'-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 +'-p "yearly from 2009-12-29"' - starts on 2009/01/01, first day of 2009 + + The following more complex report intervals are also supported: +'biweekly', 'bimonthly', 'every day|week|month|quarter|year', 'every N +days|weeks|months|quarters|years'. + + All of these will start on the first day of the requested period and +end on the last one, as described above. + + Examples: + +'-p "bimonthly from 2008"' - periods will have boundaries on 2008/01/01, 2008/03/01, ... +'-p "every 2 weeks"' - starts on closest preceeding Monday +'-p "every 5 month from 2009/03"' - periods will have boundaries on 2009/03/01, 2009/08/01, ... + + If you want intervals that start on arbitrary day of your choosing +and span a week, month or year, you need to use any of the following: + + 'every Nth day of week', 'every ', 'every Nth day [of +month]', 'every Nth weekday [of month]', 'every MM/DD [of year]', 'every +Nth MMM [of year]', 'every MMM Nth [of year]'. + + Examples: + +'-p "every 2nd day of week"' - periods will go from Tue to Tue +'-p "every Tue"' - same +'-p "every 15th day"' - period boundaries will be on 15th of each month +'-p "every 2nd Monday"' - period boundaries will be on second Monday of each month +'-p "every 11/05"' - yearly periods with boundaries on 5th of Nov +'-p "every 5th Nov"' - same +'-p "every Nov 5th"' - same + + Show historical balances at end of 15th each month (N is exclusive +end date): + + 'hledger balance -H -p "every 16th day"' + + Group postings from start of wednesday to end of next tuesday (N is +start date and exclusive end date): + + 'hledger register checking -p "every 3rd day of week"' + + +File: hledger.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS + +2.11 Depth limiting +=================== + +With the '--depth N' option (short form: '-N'), commands like account, +balance and register will show only the uppermost accounts in the +account tree, down to level N. Use this when you want a summary with +less detail. This flag has the same effect as a 'depth:' query argument +(so '-2', '--depth=2' or 'depth:2' are basically equivalent). + + +File: hledger.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS + +2.12 Pivoting +============= + +Normally hledger sums amounts, and organizes them in a hierarchy, based +on account name. The '--pivot FIELD' option causes it to sum and +organize hierarchy based on the value of some other field instead. +FIELD can be: 'code', 'description', 'payee', 'note', or the full name +(case insensitive) of any tag. As with account names, values containing +'colon:separated:parts' will be displayed hierarchically in reports. + + '--pivot' is a general option affecting all reports; you can think of +hledger transforming the journal before any other processing, replacing +every posting's account name with the value of the specified field on +that posting, inheriting it from the transaction or using a blank value +if it's not present. + + An example: + +2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query, +described below): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS + +2.13 Cost +========= + +The '-B/--cost' flag converts amounts to their cost at transaction time, +if they have a transaction price specified. + + +File: hledger.info, Node: Market value, Next: Combining -B and -V, Prev: Cost, Up: OPTIONS + +2.14 Market value +================= + +The '-V/--value' flag converts reported amounts to their current market +value. Specifically, when there is a market price (P directive) for the +amount's commodity, dated on or before today's date (or the report end +date if specified), the amount will be converted to the price's +commodity. + + When there are multiple applicable P directives, -V chooses the most +recent one, or in case of equal dates, the last-parsed one. + + For example: + +# one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +# purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +# the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 + + How many euros do I have ? + +$ hledger -f t.j bal euros + €100 assets:euros + + What are they worth on nov 3 ? (no report end date specified, +defaults to the last date in the journal) + +$ hledger -f t.j bal euros -V + $110.00 assets:euros + + What are they worth on dec 21 ? + +$ hledger -f t.j bal euros -V -e 2016/12/21 + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P +directives, not transaction prices (unlike Ledger). + + +File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS + +2.15 Combining -B and -V +======================== + +Using -B/-cost and -V/-value together is currently allowed, but the +results are probably not meaningful. Let us know if you find a use for +this. + + +File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS + +2.16 Output destination +======================= + +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. This is +controlled by the '-o/--output-file' option. + +$ hledger balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE + + +File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS + +2.17 Output format +================== + +Some commands can write their output in other formats. Eg print and +register can output CSV, and the balance commands can output CSV or +HTML. This is controlled by the '-O/--output-format' option, or by +specifying a '.csv' or '.html' file extension with '-o/--output-file'. + +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv + + +File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS + +2.18 Regular expressions +======================== + +hledger uses regular expressions in a number of places: + + * query terms, on the command line and in the hledger-web search + form: 'REGEX', 'desc:REGEX', 'cur:REGEX', 'tag:...=REGEX' + * CSV rules conditional blocks: 'if REGEX ...' + * account alias directives and options: 'alias /REGEX/ = + REPLACEMENT', '--alias /REGEX/=REPLACEMENT' + + hledger's regular expressions come from the regex-tdfa library. In +general they: + + * are case insensitive + * are infix matching (do not need to match the entire thing being + matched) + * are POSIX extended regular expressions + * also support GNU word boundaries (\<, \>, \b, \B) + * and parenthesised capturing groups and numeric backreferences in + replacement strings + * do not support mode modifiers like (?s) + + Some things to note: + + * In the 'alias' directive and '--alias' option, regular expressions + must be enclosed in forward slashes ('/REGEX/'). Elsewhere in + hledger, these are not required. + + * 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:\$'. + + * On the command line, some metacharacters like '$' have a special + meaning to the shell and so must be escaped at least once more. + See Special characters. + + +File: hledger.info, Node: QUERIES, Next: COMMANDS, Prev: OPTIONS, Up: Top + +3 QUERIES +********* + +One of hledger's strengths is being able to quickly report on precise +subsets of your data. Most commands accept an optional query +expression, written as arguments after the command name, to filter the +data by date, account name or other criteria. The syntax is similar to +a web search: one or more space-separated search terms, quotes to +enclose whitespace, prefixes to match specific fields, a not: prefix to +negate the match. + + We do not yet support arbitrary boolean combinations of search terms; +instead most commands show transactions/postings/accounts which match +(or negatively match): + + * any of the description terms AND + * any of the account terms AND + * any of the status terms AND + * all the other terms. + + The print command instead shows transactions which: + + * match any of the description terms AND + * have any postings matching any of the positive account terms AND + * have no postings matching any of the negative account terms AND + * match all the other terms. + + The following kinds of search terms can be used. Remember these can +also be prefixed with *'not:'*, eg to exclude a particular subaccount. + +*'REGEX'* + + match account names by this regular expression. (No prefix is + equivalent to 'acct:'). +*'acct:REGEX'* + + same as above +*'amt:N, amt:N, amt:>=N'* + + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not + tested, and will always match.) The comparison has two modes: if N + is preceded by a + or - sign (or is 0), the two signed numbers are + compared. Otherwise, the absolute magnitudes are compared, + ignoring sign. +*'code:REGEX'* + + match by transaction code (eg check number) +*'cur:REGEX'* + + match postings or transactions including any amounts whose + currency/commodity symbol is fully matched by REGEX. (For a partial + match, use '.*REGEX.*'). Note, to match characters which are + regex-significant, like the dollar sign ('$'), you need to prepend + '\'. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: 'hledger + print cur:'\$'' or 'hledger print cur:\\$'. +*'desc:REGEX'* + + match transaction descriptions. +*'date:PERIODEXPR'* + + match dates within the specified period. PERIODEXPR is a period + expression (with no report interval). Examples: 'date:2016', + 'date:thismonth', 'date:2000/2/1-2/15', 'date:lastweek-'. If the + '--date2' command line flag is present, this matches secondary + dates instead. +*'date2:PERIODEXPR'* + + match secondary dates within the specified period. +*'depth:N'* + + match (or display, depending on command) accounts at or above this + depth +*'note:REGEX'* + + match transaction notes (part of description right of '|', or whole + description when there's no '|') +*'payee:REGEX'* + + match transaction payee/payer names (part of description left of + '|', or whole description when there's no '|') +*'real:, real:0'* + + match real or virtual postings respectively +*'status:, status:!, status:*'* + + match unmarked, pending, or cleared transactions respectively +*'tag:REGEX[=REGEX]'* + + match by tag name, and optionally also by tag value. Note a tag: + query is considered to match a transaction if it matches any of the + postings. Also remember that postings inherit the tags of their + parent transaction. + + The following special search term is used automatically in +hledger-web, only: + +*'inacct:ACCTNAME'* + + tells hledger-web to show the transaction register for this + account. Can be filtered further with 'acct' etc. + + Some of these can also be expressed as command-line options (eg +'depth:2' is equivalent to '--depth 2'). Generally you can mix options +and query arguments, and the resulting query will be their intersection +(perhaps excluding the '-p/--period' option). + + +File: hledger.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top + +4 COMMANDS +********** + +hledger provides a number of subcommands; 'hledger' with no arguments +shows a list. + + If you install additional 'hledger-*' packages, or if you put +programs or scripts named 'hledger-NAME' in your PATH, these will also +be listed as subcommands. + + Run a subcommand by writing its name as first argument (eg 'hledger +incomestatement'). You can also write one of the standard short aliases +displayed in parentheses in the command list ('hledger b'), or any any +unambiguous prefix of a command name ('hledger inc'). + + Here are all the builtin commands in alphabetical order. See also +'hledger' for a more organised command list, and 'hledger CMD -h' for +detailed command help. +* Menu: + +* accounts:: +* activity:: +* add:: +* balance:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* check-dates:: +* check-dupes:: +* close:: +* help:: +* import:: +* incomestatement:: +* prices:: +* print:: +* print-unique:: +* register:: +* register-match:: +* rewrite:: +* stats:: +* tags:: +* test:: + + +File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS + +4.1 accounts +============ + +Show account names. Alias: a. + +'--declared' + + show account names declared with account directives +'--used' + + show account names posted to by transactions +'--tree' + + show short account names and their parents, as a tree +'--flat' + + show full account names, as a list (default) +'--drop=N' + + in flat mode: omit N leading account name parts + + This command lists account names, either declared with account +directives (-declared), posted to (-used), or both (default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +'--tree', it uses indentation to show the account hierarchy. In flat +mode you can add '--drop N' to omit the first few account name +components. Account names can be depth-clipped with '--depth N' or +depth:N. + + Examples: + +$ hledger accounts --tree +assets + bank + checking + saving + cash +expenses + food + supplies +income + gifts + salary +liabilities + debts + +$ hledger accounts --drop 1 +bank:checking +bank:saving +cash +food +supplies +gifts +salary +debts + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + + +File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS + +4.2 activity +============ + +Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). With query arguments, it counts only matched transactions. + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** + + +File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS + +4.3 add +======= + +Prompt for transactions and add them to the journal. + +'--no-new-accounts' + + don't allow creating new accounts; helps prevent typos when + entering account names + + Many hledger users edit their journals directly with a text editor, +or generate them from CSV. For more interactive data entry, there is the +'add' command, which prompts interactively on the console for new +transactions, and appends them to the journal file (if there are +multiple '-f FILE' options, the first file is used.) Existing +transactions are not changed. This is the only hledger command that +writes to the journal file. + + To use it, just run 'hledger add' and follow the prompts. You can +add as many transactions as you like; when you are finished, enter '.' +or press control-d or control-c to exit. + + Features: + + * add tries to provide useful defaults, using the most similar recent + transaction (by description) as a template. + * You can also set the initial defaults with command line arguments. + * Readline-style edit keys can be used during data entry. + * The tab key will auto-complete whenever possible - accounts, + descriptions, dates ('yesterday', 'today', 'tomorrow'). If the + input area is empty, it will insert the default value. + * If the journal defines a default commodity, it will be added to any + bare numbers entered. + * A parenthesised transaction code may be entered following a date. + * Comments and tags may be entered following a description or amount. + * If you make a mistake, enter '<' at any prompt to restart the + transaction. + * Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see the tutorial for a detailed explanation): + +$ hledger add +Adding transactions to journal file /src/hledger/examples/sample.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. +An optional ; COMMENT may follow descriptions or amounts. +If you make a mistake, enter < at any prompt to restart the transaction. +To end a transaction, enter . when prompted. +To quit, enter . at a date prompt or press control-d or control-c. +Date [2015/05/22]: +Description: supermarket +Account 1: expenses:food +Amount 1: $10 +Account 2: assets:checking +Amount 2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): . +2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + +Save this transaction to the journal ? [y]: +Saved. +Starting the next transaction (. or ctrl-D/ctrl-C to quit) +Date [2015/05/22]: $ + + +File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS + +4.4 balance +=========== + +Show accounts and their balances. Aliases: b, bal. + +'--change' + + show balance change in each period (default) +'--cumulative' + + show balance change accumulated across periods (in multicolumn + reports) +'-H --historical' + + show historical ending balance in each period (includes postings + before report start date) +'--tree' + + show accounts as a tree; amounts include subaccounts (default in + simple reports) +'--flat' + + show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) +'-A --average' + + show a row average column (in multicolumn mode) +'-T --row-total' + + show a row total column (in multicolumn mode) +'-N --no-total' + + don't show the final total row +'--drop=N' + + omit N leading account name parts (in flat mode) +'--no-elide' + + don't squash boring parent accounts (in tree mode) +'--format=LINEFORMAT' + + in single-column balance reports: use this custom line format +'-O FMT --output-format=FMT' + + select the output format. Supported formats: txt, csv, html. +'-o FILE --output-file=FILE' + + write output to FILE. A file extension matching one of the above + formats selects that format. +'--pretty-tables' + + use unicode to display prettier tables. +'--sort-amount' + + sort by amount instead of account code/name (in flat mode). With + multiple columns, sorts by the row total, or by row average if that + is displayed. +'--invert' + + display all amounts with reversed sign +'--budget' + + show performance compared to budget goals defined by periodic + transactions +'--show-unbudgeted' + + with -budget, show unbudgeted accounts also + + The balance command displays accounts and balances. It is hledger's +most featureful and versatile command. + +$ hledger balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts +-------------------- + 0 + + More precisely, the balance command shows the _change_ to each +account's balance caused by all (matched) postings. In the common case +where you do not filter by date and your journal sets the correct +opening balances, this is the same as the account's ending balance. + + By default, accounts are displayed hierarchically, with subaccounts +indented below their parent. At each level of the tree, accounts are +sorted by account code if any, then by account name. Or with +'-S/--sort-amount', by their balance amount. + + "Boring" accounts, which contain a single interesting subaccount and +no balance of their own, are elided into the following line for more +compact output. (Not yet supported in tabular reports.) Use +'--no-elide' to prevent this. + + Account balances are "inclusive" - they include the balances of any +subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are +omitted. Use '-E/--empty' to show them. + + A final total is displayed by default; use '-N/--no-total' to +suppress it: + +$ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + +* Menu: + +* Flat mode:: +* Depth limited balance reports:: +* Multicolumn balance reports:: +* Budgets:: +* Custom balance output:: +* Colour support:: + + +File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance + +4.4.1 Flat mode +--------------- + +To see a flat list of full account names instead of the default +hierarchical display, use '--flat'. In this mode, accounts (unless +depth-clipped) show their "exclusive" balance, excluding any subaccount +balances. In this mode, you can also use '--drop N' to omit the first +few account name components. + +$ hledger balance -p 2008/6 expenses -N --flat --drop 1 + $1 food + $1 supplies + + +File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance + +4.4.2 Depth limited balance reports +----------------------------------- + +With '--depth N', balance shows accounts only to the specified depth. +This is very useful to show a complex charts of accounts in less detail. +In flat mode, balances from accounts below the depth limit will be shown +as part of a parent account at the depth limit. + +$ hledger balance -N --depth 1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + +File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance + +4.4.3 Multicolumn balance reports +--------------------------------- + +With a reporting interval, multiple balance columns will be shown, one +for each report period. There are three types of multi-column balance +report, showing different information: + + 1. By default: each column shows the sum of postings in that period, + ie the account's change of balance in that period. This is useful + eg for a monthly income statement: + + $ hledger balance --quarterly income expenses -E + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 + ===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 + -------------------++--------------------------------- + || $-1 $1 0 0 + + 2. With '--cumulative': each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at + the report start date: + + $ hledger balance --quarterly income expenses -E --cumulative + Ending balances (cumulative) in 2008: + + || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 + ===================++================================================= + expenses:food || 0 $1 $1 $1 + expenses:supplies || 0 $1 $1 $1 + income:gifts || 0 $-1 $-1 $-1 + income:salary || $-1 $-1 $-1 $-1 + -------------------++------------------------------------------------- + || $-1 0 0 0 + + 3. With '--historical/-H': each column shows the actual historical + ending balance for that period, accumulating the changes across + periods, starting from the actual balance at the report start date. + This is useful eg for a multi-period balance sheet, and when you + are showing only the data after a certain start date: + + $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 + Ending balances (historical) in 2008/04/01-2008/12/31: + + || 2008/06/30 2008/09/30 2008/12/31 + ======================++===================================== + assets:bank:checking || $1 $1 0 + assets:bank:saving || $1 $1 $1 + assets:cash || $-2 $-2 $-2 + liabilities:debts || 0 0 $1 + ----------------------++------------------------------------- + || 0 0 0 + + Multi-column balance reports display accounts in flat mode by +default; to see the hierarchy, use '--tree'. + + With a reporting interval (like '--quarterly' above), the report +start/end dates will be adjusted if necessary so that they encompass the +displayed report periods. This is so that the first and last periods +will be "full" and comparable to the others. + + The '-E/--empty' flag does two things in multicolumn balance reports: +first, the report will show all columns within the specified report +period (without -E, leading and trailing columns with all zeroes are not +shown). Second, all accounts which existed at the report start date +will be considered, not just the ones with activity during the report +period (use -E to include low-activity accounts which would otherwise +would be omitted). + + The '-T/--row-total' flag adds an additional column showing the total +for each row. + + The '-A/--average' flag adds a column showing the average value in +each row. + + Here's an example of all three: + +$ hledger balance -Q income expenses --tree -ETA +Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 Total Average +============++=================================================== + expenses || 0 $2 0 0 $2 $1 + food || 0 $1 0 0 $1 0 + supplies || 0 $1 0 0 $1 0 + income || $-1 $-1 0 0 $-2 $-1 + gifts || 0 $-1 0 0 $-1 0 + salary || $-1 0 0 0 $-1 0 +------------++--------------------------------------------------- + || $-1 $1 0 0 0 0 + +# Average is rounded to the dollar here since all journal amounts are + + +File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance + +4.4.4 Budgets +------------- + +With '--budget' and a report interval, all periodic transactions in your +journal with that interval, active during the requested report period, +are interpreted as recurring budget goals for the specified accounts +(and subaccounts), and the report will show the difference between +actual and budgeted balances. + + For example, you can take average monthly expenses in the common +expense categories to construct a minimal monthly budget: + +;; Budget +~ monthly + income $2000 + expenses:food $400 + expenses:bus $50 + expenses:movies $30 + assets:bank:checking + +;; Two months worth of expenses +2017-11-01 + income $1950 + expenses:food $396 + expenses:bus $49 + expenses:movies $30 + expenses:supplies $20 + assets:bank:checking + +2017-12-01 + income $2100 + expenses:food $412 + expenses:bus $53 + expenses:gifts $100 + assets:bank:checking + + You can now see a monthly budget performance report: + +$ hledger balance -M --budget +Balance changes in 2017/11/01-2017/12/31: + + || 2017/11 2017/12 +=======================++================================================= + :expenses || $20 $100 + assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] + expenses:bus || $49 [98% of $50] $53 [106% of $50] + expenses:food || $396 [99% of $400] $412 [103% of $400] + expenses:movies || $30 [100% of $30] 0 [0% of $30] + income || $1950 [98% of $2000] $2100 [105% of $2000] +-----------------------++------------------------------------------------- + || 0 0 + + You can roll over unspent budgets to next period with '--cumulative': + +$ hledger balance -M --budget --cumulative +Ending balances (cumulative) in 2017/11/01-2017/12/31: + + || 2017/11/30 2017/12/31 +=======================++================================================= + :expenses || $20 $120 + assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] + expenses:bus || $49 [98% of $50] $102 [102% of $100] + expenses:food || $396 [99% of $400] $808 [101% of $800] + expenses:movies || $30 [100% of $30] $30 [50% of $60] + income || $1950 [98% of $2000] $4050 [101% of $4000] +-----------------------++------------------------------------------------- + || 0 0 + + Accounts with no budget goals (not mentioned in the periodic +transactions) will be aggregated under '', unless you add +the '--show-unbudgeted' flag to display them normally: + +$ hledger balance --budget --show-unbudgeted +Balance changes in 2017/11/01-2017/12/31: + + || 2017/11 2017/12 +======================++================================================= + assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] + expenses:bus || $49 [98% of $50] $53 [106% of $50] + expenses:food || $396 [99% of $400] $412 [103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [100% of $30] 0 [0% of $30] + expenses:supplies || $20 0 + income || $1950 [98% of $2000] $2100 [105% of $2000] +----------------------++------------------------------------------------- + || 0 0 + + Note -budget first arrived in hledger in 1.5 and is still pretty +young; join the discussions on mail list and issue tracker to help us +refine it. + + For more examples, see Budgeting and Forecasting. + + +File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance + +4.4.5 Custom balance output +--------------------------- + +You can customise the layout of simple (non-tabular) balance reports +with '--format FMT': + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + * MAX truncates at this width (optional) + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance + +4.4.6 Colour support +-------------------- + +The balance command shows negative amounts in red, if: + + * the 'TERM' environment variable is not set to 'dumb' + * the output is not being redirected or piped anywhere + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS + +4.5 balancesheet +================ + +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). It assumes that these accounts are under a top-level 'asset' or +'liability' account (case insensitive, plural forms also allowed). Note +this report shows all account balances with normal positive sign (like +conventional financial statements, unlike balance/print/register) +(experimental). (bs) + +'--change' + + show balance change in each period, instead of historical ending + balances +'--cumulative' + + show balance change accumulated across periods (in multicolumn + reports), instead of historical ending balances +'-H --historical' + + show historical ending balance in each period (includes postings + before report start date) (default) +'--tree' + + show accounts as a tree; amounts include subaccounts (default in + simple reports) +'--flat' + + show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) +'-A --average' + + show a row average column (in multicolumn mode) +'-T --row-total' + + show a row total column (in multicolumn mode) +'-N --no-total' + + don't show the final total row +'--drop=N' + + omit N leading account name parts (in flat mode) +'--no-elide' + + don't squash boring parent accounts (in tree mode) +'--format=LINEFORMAT' + + in single-column balance reports: use this custom line format +'--sort-amount' + + sort by amount instead of account code/name + + Example: + +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for +each report period. As with multicolumn balance reports, you can alter +the report mode with '--change'/'--cumulative'/'--historical'. Normally +balancesheet shows historical ending balances, which is what you need +for a balance sheet; note this means it ignores report begin dates. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS + +4.6 balancesheetequity +====================== + +Just like balancesheet, but also reports Equity (which it assumes is +under a top-level 'equity' account). + + Example: + +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 + + +File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS + +4.7 cashflow +============ + +This command displays a simple cashflow statement, showing changes in +"cash" accounts. It assumes that these accounts are under a top-level +'asset' account (case insensitive, plural forms also allowed) and do not +contain 'receivable' or 'A/R' in their name. Note this report shows all +account balances with normal positive sign (like conventional financial +statements, unlike balance/print/register) (experimental). (cf) + +'--change' + + show balance change in each period (default) +'--cumulative' + + show balance change accumulated across periods (in multicolumn + reports), instead of changes during periods +'-H --historical' + + show historical ending balance in each period (includes postings + before report start date), instead of changes during each period +'--tree' + + show accounts as a tree; amounts include subaccounts (default in + simple reports) +'--flat' + + show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) +'-A --average' + + show a row average column (in multicolumn mode) +'-T --row-total' + + show a row total column (in multicolumn mode) +'-N --no-total' + + don't show the final total row (in simple reports) +'--drop=N' + + omit N leading account name parts (in flat mode) +'--no-elide' + + don't squash boring parent accounts (in tree mode) +'--format=LINEFORMAT' + + in single-column balance reports: use this custom line format +'--sort-amount' + + sort by amount instead of account code/name + + Example: + +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 + + With a reporting interval, multiple columns will be shown, one for +each report period. Normally cashflow shows changes in assets per +period, though as with multicolumn balance reports you can alter the +report mode with '--change'/'--cumulative'/'--historical'. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS + +4.8 check-dates +=============== + +Check that transactions are sorted by increasing date. With a query, +only matched transactions' dates are checked. + + +File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS + +4.9 check-dupes +=============== + +Report account names having the same leaf but different prefixes. An +example: http://stefanorodighiero.net/software/hledger-dupes.html + + +File: hledger.info, Node: close, Next: help, Prev: check-dupes, Up: COMMANDS + +4.10 close +========== + +Print closing/opening transactions that bring some or all account +balances to zero and back. Can be useful for bringing asset/liability +balances across file boundaries, or for closing out income/expenses for +a period. This was formerly called "equity", as in Ledger, and that +alias is also accepted. See close -help for more. + + +File: hledger.info, Node: help, Next: import, Prev: close, Up: COMMANDS + +4.11 help +========= + +Show any of the hledger manuals. + + The 'help' command displays any of the main hledger manuals, in one +of several ways. Run it with no argument to list the manuals, or +provide a full or partial manual name to select one. + + hledger manuals are available in several formats. hledger help will +use the first of these display methods that it finds: info, man, $PAGER, +less, stdout (or when non-interactive, just stdout). You can force a +particular viewer with the '--info', '--man', '--pager', '--cat' flags. + +$ hledger help +Please choose a manual by typing "hledger help MANUAL" (a substring is ok). +Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot + +$ hledger help h --man + +hledger(1) hledger User Manuals hledger(1) + +NAME + hledger - a command-line accounting tool + +SYNOPSIS + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + hledger + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any +... + + +File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS + +4.12 import +=========== + +Read new transactions added to each FILE since last run, and add them to +the main journal file. + +'--dry-run' + + just show the transactions to be imported + + The input files are specified as arguments - no need to write -f +before each one. So eg to add new transactions from all CSV files to +the main journal, it's just: 'hledger import *.csv' + + New transactions are detected in the same way as print -new: by +assuming transactions are always added to the input files in increasing +date order, and by saving '.latest.FILE' state files. + + The -dry-run output is in journal format, so you can filter it, eg to +see only uncategorised transactions: + +$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions + + +File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS + +4.13 incomestatement +==================== + +This command displays a simple income statement, showing revenues and +expenses during a period. It assumes that these accounts are under a +top-level 'revenue' or 'income' or 'expense' account (case insensitive, +plural forms also allowed). Note this report shows all account balances +with normal positive sign (like conventional financial statements, +unlike balance/print/register) (experimental). (is) + +'--change' + + show balance change in each period (default) +'--cumulative' + + show balance change accumulated across periods (in multicolumn + reports), instead of changes during periods +'-H --historical' + + show historical ending balance in each period (includes postings + before report start date), instead of changes during each period +'--tree' + + show accounts as a tree; amounts include subaccounts (default in + simple reports) +'--flat' + + show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) +'-A --average' + + show a row average column (in multicolumn mode) +'-T --row-total' + + show a row total column (in multicolumn mode) +'-N --no-total' + + don't show the final total row +'--drop=N' + + omit N leading account name parts (in flat mode) +'--no-elide' + + don't squash boring parent accounts (in tree mode) +'--format=LINEFORMAT' + + in single-column balance reports: use this custom line format +'--sort-amount' + + sort by amount instead of account code/name + + This command displays a simple income statement. It currently +assumes that you have top-level accounts named 'income' (or 'revenue') +and 'expense' (plural forms also allowed.) + +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for +each report period. Normally incomestatement shows revenues/expenses +per period, though as with multicolumn balance reports you can alter the +report mode with '--change'/'--cumulative'/'--historical'. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS + +4.14 prices +=========== + +Print all market prices from the journal. + + +File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS + +4.15 print +========== + +Show transactions from the journal. Aliases: p, txns. + +'-m STR --match=STR' + + show the transaction whose description is most similar to STR, and + is most recent +'--new' + + show only newer-dated transactions added in each file since last + run +'-x --explicit' + + show all amounts explicitly +'-O FMT --output-format=FMT' + + select the output format. Supported formats: txt, csv. +'-o FILE --output-file=FILE' + + write output to FILE. A file extension matching one of the above + formats selects that format. + +$ hledger print +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + +2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + +2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + +2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + +2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 + + The print command displays full journal entries (transactions) from +the journal file in date order, tidily formatted. print's output is +always a valid hledger journal. It preserves all transaction +information, but it does not preserve directives or inter-transaction +comments + + Normally, the journal entry's explicit or implicit amount style is +preserved. Ie when an amount is omitted in the journal, it will be +omitted in the output. You can use the '-x'/'--explicit' flag to make +all amounts explicit, which can be useful for troubleshooting or for +making your journal more readable and robust against data entry errors. +Note, '-x' will cause postings with a multi-commodity amount (these can +arise when a multi-commodity transaction has an implicit amount) will be +split into multiple single-commodity postings, for valid journal output. + + With '-B'/'--cost', amounts with transaction prices are converted to +cost using that price. This can be used for troubleshooting. + + With '-m'/'--match' and a STR argument, print will show at most one +transaction: the one one whose description is most similar to STR, and +is most recent. STR should contain at least two characters. If there +is no similar-enough match, no transaction will be shown. + + With '--new', for each FILE being read, hledger reads (and writes) a +special state file ('.latest.FILE' in the same directory), containing +the latest transaction date(s) that were seen last time FILE was read. +When this file is found, only transactions with newer dates (and new +transactions on the latest date) are printed. This is useful for +ignoring already-seen entries in import data, such as downloaded CSV +files. Eg: + +$ hledger -f bank1.csv print --new +# shows transactions added since last print --new on this file + + This assumes that transactions added to FILE always have same or +increasing dates, and that transactions on the same day do not get +reordered. See also the import command. + + This command also supports output destination and output format +selection. Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS + +4.16 print-unique +================= + +Print transactions which do not reuse an already-seen description. + + +File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS + +4.17 register +============= + +Show postings and their running total. Aliases: r, reg. + +'--cumulative' + + show running total from report start date (default) +'-H --historical' + + show historical running total/balance (includes postings before + report start date) +'-A --average' + + show running average of posting amounts instead of total (implies + -empty) +'-r --related' + + show postings' siblings instead +'-w N --width=N' + + set output width (default: terminal width or COLUMNS. -wN,M sets + description width as well) +'-O FMT --output-format=FMT' + + select the output format. Supported formats: txt, csv. +'-o FILE --output-file=FILE' + + write output to FILE. A file extension matching one of the above + formats selects that format. + + The register command displays postings, one per line, and their +running total. This is typically used with a query selecting a +particular account, to see that account's activity: + +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + The '--historical'/'-H' flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + The '--depth' option limits the amount of sub-account detail +displayed. + + The '--average'/'-A' flag shows the running average posting amount +instead of the running total (so, the final number displayed is the +average for the whole report period). This flag implies '--empty' (see +below). It is affected by '--historical'. It works best when showing +just one account and one commodity. + + The '--related'/'-r' flag shows the _other_ postings in the +transactions of the postings which would normally be shown. + + With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: + +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, +are not shown by default; use the '--empty'/'-E' flag to see them: + +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The '--depth' +option helps with this, causing subaccounts to be aggregated: + +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates +these will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +4.17.1 Custom register output +----------------------------- + +register uses the full terminal width by default, except on windows. +You can override this by setting the 'COLUMNS' environment variable (not +a bash shell variable) or by using the '--width'/'-w' option. + + The description and account columns normally share the space equally +(about half of (width - 40) each). You can adjust this by adding a +description width as part of -width's argument, comma-separated: +'--width W,D' . Here's a diagram: + +<--------------------------------- width (W) ----------------------------------> +date (10) description (D) account (W-41-D) amount (12) balance (12) +DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + +$ hledger reg # use terminal width (or 80 on windows) +$ hledger reg -w 100 # use width 100 +$ COLUMNS=100 hledger reg # set with one-time environment variable +$ export COLUMNS=100; hledger reg # set till session end (or window resize) +$ hledger reg -w 100,40 # set overall width 100, description width 40 +$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS + +4.18 register-match +=================== + +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. Helps ledger-autosync detect +already-seen transactions when importing. + + +File: hledger.info, Node: rewrite, Next: stats, Prev: register-match, Up: COMMANDS + +4.19 rewrite +============ + +Print all transactions, adding custom postings to the matched ones. + + +File: hledger.info, Node: stats, Next: tags, Prev: rewrite, Up: COMMANDS + +4.20 stats +========== + +Show some journal statistics. + +'-o FILE --output-file=FILE' + + write output to FILE. A file extension matching one of the above + formats selects that format. + +$ hledger stats +Main journal file : /src/hledger/examples/sample.journal +Included journal files : +Transactions span : 2008-01-01 to 2009-01-01 (366 days) +Last transaction : 2008-12-31 (2333 days ago) +Transactions : 5 (0.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 5 +Accounts : 8 (depth 3) +Commodities : 1 ($) + + The stats command displays summary information for the whole journal, +or a matched part of it. With a reporting interval, it shows a report +for each report period. + + This command also supports output destination and output format +selection. + + +File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS + +4.21 tags +========= + +List all the tag names used in the journal. With a TAGREGEX argument, +only tag names matching the regular expression (case insensitive) are +shown. With additional QUERY arguments, only transactions matching the +query are considered. + + +File: hledger.info, Node: test, Prev: tags, Up: COMMANDS + +4.22 test +========= + +Run built-in unit tests. + +$ hledger test +Cases: 74 Tried: 74 Errors: 0 Failures: 0 + + This command runs hledger's built-in unit tests and displays a quick +report. With a regular expression argument, it selects only tests with +matching names. It's mainly used in development, but it's also nice to +be able to check your hledger executable for smoke at any time. + + +File: hledger.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top + +5 ADD-ON COMMANDS +***************** + +hledger also searches for external add-on commands, and will include +these in the commands list. These are programs or scripts in your PATH +whose name starts with 'hledger-' and ends with a recognised file +extension (currently: no extension, 'bat','com','exe', +'hs','lhs','pl','py','rb','rkt','sh'). + + Add-ons can be invoked like any hledger command, but there are a few +things to be aware of. Eg if the 'hledger-web' add-on is installed, + + * 'hledger -h web' shows hledger's help, while 'hledger web -h' shows + hledger-web's help. + + * Flags specific to the add-on must have a preceding '--' to hide + them from hledger. So 'hledger web --serve --port 9000' will be + rejected; you must use 'hledger web -- --serve --port 9000'. + + * You can always run add-ons directly if preferred: 'hledger-web + --serve --port 9000'. + + Add-ons are a relatively easy way to add local features or experiment +with new ideas. They can be written in any language, but haskell +scripts have a big advantage: they can use the same hledger (and +haskell) library functions that built-in commands do, for command-line +options, journal parsing, reporting, etc. + + Here are some hledger add-ons available: +* Menu: + +* Official add-ons:: +* Third party add-ons:: +* Experimental add-ons:: + + +File: hledger.info, Node: Official add-ons, Next: Third party add-ons, Up: ADD-ON COMMANDS + +5.1 Official add-ons +==================== + +These are maintained and released along with hledger. +* Menu: + +* api:: +* ui:: +* web:: + + +File: hledger.info, Node: api, Next: ui, Up: Official add-ons + +5.1.1 api +--------- + +hledger-api serves hledger data as a JSON web API. + + +File: hledger.info, Node: ui, Next: web, Prev: api, Up: Official add-ons + +5.1.2 ui +-------- + +hledger-ui provides an efficient curses-style interface. + + +File: hledger.info, Node: web, Prev: ui, Up: Official add-ons + +5.1.3 web +--------- + +hledger-web provides a simple web interface. + + +File: hledger.info, Node: Third party add-ons, Next: Experimental add-ons, Prev: Official add-ons, Up: ADD-ON COMMANDS + +5.2 Third party add-ons +======================= + +These are maintained separately, and usually updated shortly after a +hledger release. +* Menu: + +* diff:: +* iadd:: +* interest:: +* irr:: + + +File: hledger.info, Node: diff, Next: iadd, Up: Third party add-ons + +5.2.1 diff +---------- + +hledger-diff shows differences in an account's transactions between one +journal file and another. + + +File: hledger.info, Node: iadd, Next: interest, Prev: diff, Up: Third party add-ons + +5.2.2 iadd +---------- + +hledger-iadd is a curses-style, more interactive replacement for the add +command. + + +File: hledger.info, Node: interest, Next: irr, Prev: iadd, Up: Third party add-ons + +5.2.3 interest +-------------- + +hledger-interest generates interest transactions for an account +according to various schemes. + + +File: hledger.info, Node: irr, Prev: interest, Up: Third party add-ons + +5.2.4 irr +--------- + +hledger-irr calculates the internal rate of return of an investment +account. + + +File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS + +5.3 Experimental add-ons +======================== + +These are available in source form in the hledger repo's bin/ directory; +installing them is pretty easy. They may be less mature and documented +than built-in commands. Reading and tweaking these is a good way to +start making your own! +* Menu: + +* autosync:: +* chart:: +* check:: + + +File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons + +5.3.1 autosync +-------------- + +hledger-autosync is a symbolic link for easily running ledger-autosync, +if installed. ledger-autosync does deduplicating conversion of OFX data +and some CSV formats, and can also download the data if your bank offers +OFX Direct Connect. + + +File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons + +5.3.2 chart +----------- + +hledger-chart.hs is an old pie chart generator, in need of some love. + + +File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons + +5.3.3 check +----------- + +hledger-check.hs checks more powerful account balance assertions. + + +Tag Table: +Node: Top68 +Node: EXAMPLES1882 +Ref: #examples1982 +Node: OPTIONS3628 +Ref: #options3730 +Node: General options4095 +Ref: #general-options4220 +Node: Command options6819 +Ref: #command-options6970 +Node: Command arguments7368 +Ref: #command-arguments7522 +Node: Argument files7643 +Ref: #argument-files7794 +Node: Special characters8060 +Ref: #special-characters8213 +Node: Input files9632 +Ref: #input-files9768 +Node: Smart dates11738 +Ref: #smart-dates11879 +Node: Report start & end date12858 +Ref: #report-start-end-date13028 +Node: Report intervals14093 +Ref: #report-intervals14256 +Node: Period expressions14657 +Ref: #period-expressions14817 +Node: Depth limiting18774 +Ref: #depth-limiting18918 +Node: Pivoting19260 +Ref: #pivoting19378 +Node: Cost21054 +Ref: #cost21162 +Node: Market value21280 +Ref: #market-value21415 +Node: Combining -B and -V22598 +Ref: #combining--b-and--v22761 +Node: Output destination22908 +Ref: #output-destination23070 +Node: Output format23353 +Ref: #output-format23505 +Node: Regular expressions23890 +Ref: #regular-expressions24027 +Node: QUERIES25388 +Ref: #queries25490 +Node: COMMANDS29457 +Ref: #commands29569 +Node: accounts30551 +Ref: #accounts30649 +Node: activity31895 +Ref: #activity32005 +Node: add32365 +Ref: #add32464 +Node: balance35125 +Ref: #balance35236 +Node: Flat mode38740 +Ref: #flat-mode38865 +Node: Depth limited balance reports39285 +Ref: #depth-limited-balance-reports39486 +Node: Multicolumn balance reports39906 +Ref: #multicolumn-balance-reports40101 +Node: Budgets44790 +Ref: #budgets44937 +Node: Custom balance output48906 +Ref: #custom-balance-output49068 +Node: Colour support51234 +Ref: #colour-support51366 +Node: balancesheet51539 +Ref: #balancesheet51675 +Node: balancesheetequity53986 +Ref: #balancesheetequity54135 +Node: cashflow54672 +Ref: #cashflow54800 +Node: check-dates56923 +Ref: #check-dates57050 +Node: check-dupes57167 +Ref: #check-dupes57291 +Node: close57428 +Ref: #close57535 +Node: help57865 +Ref: #help57965 +Node: import59039 +Ref: #import59153 +Node: incomestatement59883 +Ref: #incomestatement60017 +Node: prices62421 +Ref: #prices62536 +Node: print62579 +Ref: #print62689 +Node: print-unique67583 +Ref: #print-unique67709 +Node: register67777 +Ref: #register67904 +Node: Custom register output72405 +Ref: #custom-register-output72534 +Node: register-match73764 +Ref: #register-match73898 +Node: rewrite74081 +Ref: #rewrite74198 +Node: stats74267 +Ref: #stats74370 +Node: tags75240 +Ref: #tags75338 +Node: test75574 +Ref: #test75658 +Node: ADD-ON COMMANDS76026 +Ref: #add-on-commands76136 +Node: Official add-ons77423 +Ref: #official-add-ons77563 +Node: api77650 +Ref: #api77739 +Node: ui77791 +Ref: #ui77890 +Node: web77948 +Ref: #web78037 +Node: Third party add-ons78083 +Ref: #third-party-add-ons78258 +Node: diff78393 +Ref: #diff78490 +Node: iadd78589 +Ref: #iadd78703 +Node: interest78786 +Ref: #interest78907 +Node: irr79002 +Ref: #irr79100 +Node: Experimental add-ons79178 +Ref: #experimental-add-ons79330 +Node: autosync79610 +Ref: #autosync79721 +Node: chart79960 +Ref: #chart80079 +Node: check80150 +Ref: #check80252 + +End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger.txt @@ -0,0 +1,2168 @@ + +hledger(1) hledger User Manuals hledger(1) + + + +NAME + hledger - a command-line accounting tool + +SYNOPSIS + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + hledger + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any + other commodity, using double-entry accounting and a simple, editable + file format. hledger is inspired by and largely compatible with + ledger(1). + Tested on unix, mac, windows, hledger aims to be a reliable, practical + tool for daily use. + + This is hledger's command-line interface (there are also curses and web + interfaces). Its basic function is to read a plain text file describ- + ing financial transactions (in accounting terms, a general journal) and + print useful reports on standard output, or export them as CSV. + hledger can also read some other file formats such as CSV files, trans- + lating them to journal format. Additionally, hledger lists other + hledger-* executables found in the user's $PATH and can invoke them as + subcommands. + + hledger reads data from one or more files in hledger journal, time- + clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must + be a real environment variable, not a shell variable. You can specify + standard input with -f-. + + Transactions are dated movements of money between two (or more) named + accounts, and are recorded with journal entries like this: + + 2015/10/16 bought food + expenses:food $10 + assets:cash + + For more about this format, see hledger_journal(5). + + Most users use a text editor to edit the journal, usually with an edi- + tor mode such as ledger-mode for added convenience. hledger's interac- + tive add command is another way to record new transactions. hledger + never changes existing transactions. + + To get started, you can either save some entries like the above in + ~/.hledger.journal, or run hledger add and follow the prompts. Then + try some commands like hledger print or hledger balance. Run hledger + with no arguments for a list of commands. + +EXAMPLES + Two simple transactions in hledger journal format: + + 2015/9/30 gift received + assets:cash $20 + income:gifts + + 2015/10/16 farmers market + expenses:food $10 + assets:cash + + Some basic reports: + + $ hledger print + 2015/09/30 gift received + assets:cash $20 + income:gifts $-20 + + 2015/10/16 farmers market + expenses:food $10 + assets:cash $-10 + + $ hledger accounts --tree + assets + cash + expenses + food + income + gifts + + $ hledger balance + $10 assets:cash + $10 expenses:food + $-20 income:gifts + -------------------- + 0 + + $ hledger register cash + 2015/09/30 gift received assets:cash $20 $20 + 2015/10/16 farmers market assets:cash $-10 $10 + + More commands: + + $ hledger # show available commands + $ hledger add # add more transactions to the journal file + $ hledger balance # all accounts with aggregated balances + $ hledger balance --help # show detailed help for balance command + $ hledger balance --depth 1 # only top-level accounts + $ hledger register # show account postings, with running total + $ hledger reg income # show postings to/from income accounts + $ hledger reg 'assets:some bank:checking' # show postings to/from this checking account + $ hledger print desc:shop # show transactions with shop in the description + $ hledger activity -W # show transaction counts per week as a bar chart + +OPTIONS + General options + To see general usage help, including general options which are sup- + ported by most hledger commands, run hledger -h. + + General help options: + + -h --help + show general usage (or after COMMAND, command usage) + + --version + show 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) + + --rules-file=RULESFILE + Conversion rules file to use when reading CSV (default: + FILE.rules) + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot FIELDNAME + use some other field or tag for the account name + + -I --ignore-assertions + ignore any failing balance assertions + + General reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) + + --date2 + match the secondary date instead (see command help for other + effects) + + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) + + -P --pending + include only pending postings/txns + + -C --cleared + include only cleared postings/txns + + -R --real + include only non-virtual postings + + -NUM --depth=NUM + hide/aggregate accounts or postings more than NUM levels deep + + -E --empty + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + --auto apply automated posting rules to modify transactions. + + --forecast + apply periodic transaction rules to generate future transac- + tions, to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, the + last one takes precedence. + + Some reporting options can also be written as query arguments. + + 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 addon, you may need to put its + options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + run the addon 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. + + Argument files + You can save a set of command line options/arguments in a file, one per + line, and then reuse them by writing @FILENAME in a command line. To + prevent this expansion of @-arguments, precede them with a -- argument. + For more, see Save frequently used options. + + Special characters + Option and argument values which contain problematic characters should + be escaped with double quotes, backslashes, or (best) single quotes. + Problematic characters means spaces, and also characters which are sig- + nificant to your command shell, such as less-than/greater-than. Eg: + hledger register -p 'last year' "accounts receivable (receiv- + able|payable)" amt:\>100. + + Characters which are significant both to the shell and in regular + expressions sometimes need to be double-escaped. These include paren- + theses, the pipe symbol and the dollar sign. Eg, to match the dollar + symbol, bash users should do: hledger balance cur:'\$' or hledger bal- + ance cur:\\$. + + When hledger is invoking an addon executable (like hledger-ui), options + and arguments get de-escaped once more, so you might need triple-escap- + ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The + number of backslashes in fish shell is left as an exercise for the + reader.) + + Inside a file used for argument expansion, one less level of escaping + is enough. (And in this case, backslashes seem to work better than + quotes. Eg: cur:\$). + + If in doubt, keep things simple: + + o run add-on executables directly + + o write options after the command + + o enclose problematic args in single quotes + + o if needed, also add a backslash to escape regexp metacharacters + + If you're really stumped, add --debug=2 to troubleshoot. + + Input files + hledger reads transactions from a data file (and the add command writes + to it). By default this file is $HOME/.hledger.journal (or on Windows, + something like C:/Users/USER/.hledger.journal). You can override this + with the $LEDGER_FILE environment variable: + + $ setenv LEDGER_FILE ~/finance/2016.journal + $ hledger stats + + or with the -f/--file option: + + $ hledger -f /some/file stats + + The file name - (hyphen) means standard input: + + $ cat some.journal | hledger -f- + + Usually the data file is in hledger's journal format, but it can also + be one of several other formats, listed below. hledger detects the + format automatically based on the file extension, or if that is not + recognised, by trying each built-in "reader" in turn: + + + Reader: Reads: Used for file extensions: + ----------------------------------------------------------------------------- + journal hledger's journal format, also .journal .j .hledger + some Ledger journals .ledger + timeclock timeclock files (precise time .timeclock + logging) + timedot timedot files (approximate time .timedot + logging) + csv comma-separated values (data .csv + interchange) + + If needed (eg to ensure correct error messages when a file has the + "wrong" extension), you can force a specific reader/format by prepend- + ing it to the file path with a colon. Examples: + + $ hledger -f csv:/some/csv-file.dat stats + $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:- + + You can also specify multiple -f options, to read multiple files as one + big journal. There are some limitations with this: + + o directives in one file will not affect the other files + + o balance assertions will not see any account balances from previous + files + + If you need those, either use the include directive, or concatenate the + files, eg: cat a.journal b.journal | hledger -f- CMD. + + Smart dates + hledger's user interfaces accept a flexible "smart date" syntax (unlike + dates in the journal file). Smart dates allow some english words, can + be relative to today's date, and can have less-significant date parts + omitted (defaulting to 1). + + Examples: + + + 2009/1/1, 2009/01/01, simple dates, several sep- + 2009-1-1, 2009.1.1 arators allowed + + + 2009/1, 2009 same as above - a missing + day or month defaults to 1 + 1/1, january, jan, relative dates, meaning + this year january 1 of the current + year + next year january 1 of next year + this month the 1st of the current + month + this week the most recent monday + last week the monday of the week + before this one + lastweek spaces are optional + today, yesterday, tomorrow + + Report start & end date + Most hledger reports show the full span of time represented by the + journal data, by default. So, the effective report start and end dates + will be the earliest and latest transaction or posting dates found in + the journal. + + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, + -e/--end, -p/--period or a date: query (described below). All of these + accept the smart date syntax. One important thing to be aware of when + specifying end dates: as in Ledger, end dates are exclusive, so you + need to write the date after the last day you want to include. + + Examples: + + + -b 2016/3/17 begin on St. Patrick's day + 2016 + -e 12/1 end at the start of decem- + ber 1st of the current + year (11/30 will be the + last date included) + -b thismonth all transactions on or + after the 1st of the cur- + rent month + -p thismonth all transactions in the + current month + date:2016/3/17- the above written as + queries instead + date:-12/1 + date:thismonth- + date:thismonth + + Report intervals + A report interval can be specified so that commands like register, bal- + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report + intervals can not be specified with a query, currently. + + Period expressions + The -p/--period option accepts period expressions, a shorthand way of + expressing a start date, end date, and/or report interval all at once. + + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as + exclusive: + + -p "from 2009/1/1 to 2009/4/1" + + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as + "-". These are equivalent to the above: + + + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1-2009/4/1 + + Dates are smart dates, so if the current year is 2009, the above can + also be written as: + + + -p "1/1 4/1" + -p "january-apr" + -p "this year to 4/1" + + If you specify only one date, the missing start or end date will be the + earliest or latest transaction in your journal: + + + -p "from 2009/1/1" everything after january + 1, 2009 + -p "from 2009/1" the same + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 + + A single date with no "from" or "to" defines both the start and end + date like so: + + + -p "2009" the year 2009; equivalent + to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of jan; equiva- + lent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" just that day; equivalent + to "2009/1/1 to 2009/1/2" + + The argument of -p can also begin with, or be, a report interval + expression. The basic report intervals are daily, weekly, monthly, + quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or + -Y flags. Between report interval and start/end dates (if any), the + word in is optional. Examples: + + + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "quarterly" + + Note that weekly, monthly, quarterly and yearly intervals will always + start on the first day on week, month, quarter or year accordingly, and + will end on the last day of same period, even if associated period + expression specifies different explicit start and end date. + + For example: + + + -p "weekly from 2009/1/1 to 2009/4/1" - + starts on 2008/12/29, closest preceed- + ing Monday + -p "monthly in 2008/11/25" - starts on + 2018/11/01 + -p "quar- + terly from 2009-05-05 to 2009-06-01" - + starts on 2009/04/01, ends on + 2009/06/30, which are first and last + days of Q2 2009 + -p "yearly from 2009-12-29" - starts on + 2009/01/01, first day of 2009 + + The following more complex report intervals are also supported: + biweekly, bimonthly, every day|week|month|quarter|year, + every N days|weeks|months|quarters|years. + + All of these will start on the first day of the requested period and + end on the last one, as described above. + + Examples: + + + -p "bimonthly from 2008" - periods will + have boundaries on 2008/01/01, + 2008/03/01, ... + -p "every 2 weeks" - starts on closest + preceeding Monday + -p "every 5 month from 2009/03" - peri- + ods will have boundaries on 2009/03/01, + 2009/08/01, ... + + If you want intervals that start on arbitrary day of your choosing and + span a week, month or year, you need to use any of the following: + + every Nth day of week, every , every Nth day [of month], + every Nth weekday [of month], every MM/DD [of year], + every Nth MMM [of year], every MMM Nth [of year]. + + Examples: + + + -p "every 2nd day of week" - periods + will go from Tue to Tue + -p "every Tue" - same + -p "every 15th day" - period boundaries + will be on 15th of each month + -p "every 2nd Monday" - period bound- + aries will be on second Monday of each + month + -p "every 11/05" - yearly periods with + boundaries on 5th of Nov + -p "every 5th Nov" - same + -p "every Nov 5th" - same + + Show historical balances at end of 15th each month (N is exclusive end + date): + + hledger balance -H -p "every 16th day" + + Group postings from start of wednesday to end of next tuesday (N is + start date and exclusive end date): + + hledger register checking -p "every 3rd day of week" + + Depth limiting + With the --depth N option (short form: -N), commands like account, bal- + ance and register will show only the uppermost accounts in the account + tree, down to level N. Use this when you want a summary with less + detail. This flag has the same effect as a depth: query argument (so + -2, --depth=2 or depth:2 are basically equivalent). + + Pivoting + Normally hledger sums amounts, and organizes them in a hierarchy, based + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD + can be: code, description, payee, note, or the full name (case insensi- + tive) of any tag. As with account names, values containing colon:sepa- + rated:parts will be displayed hierarchically in reports. + + --pivot is a general option affecting all reports; you can think of + hledger transforming the journal before any other processing, replacing + every posting's account name with the value of the specified field on + that posting, inheriting it from the transaction or using a blank value + if it's not present. + + An example: + + 2016/02/16 Member Fee Payment + assets:bank account 2 EUR + income:member fees -2 EUR ; member: John Doe + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:member fees + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query, + described below): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + + Cost + The -B/--cost flag converts amounts to their cost at transaction time, + if they have a transaction price specified. + + Market value + The -V/--value flag converts reported amounts to their current market + value. Specifically, when there is a market price (P directive) for + the amount's commodity, dated on or before today's date (or the report + end date if specified), the amount will be converted to the price's + commodity. + + When there are multiple applicable P directives, -V chooses the most + recent one, or in case of equal dates, the last-parsed one. + + For example: + + # one euro is worth this many dollars from nov 1 + P 2016/11/01 $1.10 + + # purchase some euros on nov 3 + 2016/11/3 + assets:euros 100 + assets:checking + + # the euro is worth fewer dollars by dec 21 + P 2016/12/21 $1.03 + + How many euros do I have ? + + $ hledger -f t.j bal euros + 100 assets:euros + + What are they worth on nov 3 ? (no report end date specified, defaults + to the last date in the journal) + + $ hledger -f t.j bal euros -V + $110.00 assets:euros + + What are they worth on dec 21 ? + + $ hledger -f t.j bal euros -V -e 2016/12/21 + $103.00 assets:euros + + Currently, hledger's -V only uses market prices recorded with P direc- + tives, not transaction prices (unlike Ledger). + + Combining -B and -V + Using -B/-cost and -V/-value together is currently allowed, but the + results are probably not meaningful. Let us know if you find a use for + this. + + Output destination + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- + trolled by the -o/--output-file option. + + $ hledger balance -o - # write to stdout (the default) + $ hledger balance -o FILE # write to FILE + + Output format + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or + HTML. This is controlled by the -O/--output-format option, or by spec- + ifying a .csv or .html file extension with -o/--output-file. + + $ hledger balance -O csv # write CSV to stdout + $ hledger balance -o FILE.csv # write CSV to FILE.csv + + 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: + REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX + + o CSV rules conditional blocks: if REGEX ... + + o account alias directives and options: alias /REGEX/ = REPLACEMENT, + --alias /REGEX/=REPLACEMENT + + hledger's regular expressions come from the regex-tdfa library. In + general they: + + o are case insensitive + + o are infix matching (do not need to match the entire thing being + matched) + + o are POSIX extended regular expressions + + o also support GNU word boundaries (\<, \>, \b, \B) + + o and parenthesised capturing groups and numeric backreferences in + replacement strings + + o do not support mode modifiers like (?s) + + Some things to note: + + 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 + with the dollar sign in hledger-web, write cur:\$. + + 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. + +QUERIES + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a + web search: one or more space-separated search terms, quotes to enclose + whitespace, prefixes to match specific fields, a not: prefix to negate + the match. + + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match + (or negatively match): + + o any of the description terms AND + + o any of the account terms AND + + o any of the status terms AND + + o all the other terms. + + The print command instead shows transactions which: + + o match any of the description terms AND + + o have any postings matching any of the positive account terms AND + + o have no postings matching any of the negative account terms AND + + o match all the other terms. + + The following kinds of search terms can be used. Remember these can + also be prefixed with not:, eg to exclude a particular subaccount. + + REGEX match account names by this regular expression. (No prefix is + equivalent to acct:). + + acct:REGEX + same as above + + amt:N, amt:N, amt:>=N + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not + tested, and will always match.) The comparison has two modes: if + N is preceded by a + or - sign (or is 0), the two signed numbers + are compared. Otherwise, the absolute magnitudes are compared, + ignoring sign. + + code:REGEX + match by transaction code (eg check number) + + cur:REGEX + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- + tial match, use .*REGEX.*). Note, to match characters which are + regex-significant, like the dollar sign ($), you need to prepend + \. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: + hledger print cur:'\$' or hledger print cur:\\$. + + desc:REGEX + match transaction descriptions. + + date:PERIODEXPR + match dates within the specified period. PERIODEXPR is a period + expression (with no report interval). Examples: date:2016, + date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the + --date2 command line flag is present, this matches secondary + dates instead. + + date2:PERIODEXPR + match secondary dates within the specified period. + + depth:N + match (or display, depending on command) accounts at or above + this depth + + note:REGEX + match transaction notes (part of description right of |, or + whole description when there's no |) + + payee:REGEX + match transaction payee/payer names (part of description left of + |, or whole description when there's no |) + + real:, real:0 + match real or virtual postings respectively + + status:, status:!, status:* + match unmarked, pending, or cleared transactions respectively + + tag:REGEX[=REGEX] + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the + tags of their parent transaction. + + The following special search term is used automatically in hledger-web, + only: + + inacct:ACCTNAME + tells hledger-web to show the transaction register for this + account. Can be filtered further with acct etc. + + Some of these can also be expressed as command-line options (eg depth:2 + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps + excluding the -p/--period option). + +COMMANDS + hledger provides a number of subcommands; hledger with no arguments + shows a list. + + If you install additional hledger-* packages, or if you put programs or + scripts named hledger-NAME in your PATH, these will also be listed as + subcommands. + + Run a subcommand by writing its name as first argument (eg + hledger incomestatement). You can also write one of the standard short + aliases displayed in parentheses in the command list (hledger b), or + any any unambiguous prefix of a command name (hledger inc). + + Here are all the builtin commands in alphabetical order. See also + hledger for a more organised command list, and hledger CMD -h for + detailed command help. + + accounts + Show account names. Alias: a. + + --declared + show account names declared with account directives + + --used show account names posted to by transactions + + --tree show short account names and their parents, as a tree + + --flat show full account names, as a list (default) + + --drop=N + in flat mode: omit N leading account name parts + + This command lists account names, either declared with account direc- + tives (-declared), posted to (-used), or both (default). With query + arguments, only matched account names and account names referenced by + matched postings are shown. It shows a flat list by default. With + --tree, it uses indentation to show the account hierarchy. In flat + mode you can add --drop N to omit the first few account name compo- + nents. Account names can be depth-clipped with --depth N or depth:N. + + Examples: + + $ hledger accounts --tree + assets + bank + checking + saving + cash + expenses + food + supplies + income + gifts + salary + liabilities + debts + + $ hledger accounts --drop 1 + bank:checking + bank:saving + cash + food + supplies + gifts + salary + debts + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + activity + Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the + default). With query arguments, it counts only matched transactions. + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + + add + Prompt for transactions and add them to the journal. + + --no-new-accounts + don't allow creating new accounts; helps prevent typos when + entering account names + + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the journal file (if there are multiple + -f FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal + file. + + To use it, just run hledger add and follow the prompts. You can add as + many transactions as you like; when you are finished, enter . or press + control-d or control-c to exit. + + Features: + + o add tries to provide useful defaults, using the most similar recent + transaction (by description) as a template. + + o You can also set the initial defaults with command line arguments. + + o Readline-style edit keys can be used during data entry. + + o The tab key will auto-complete whenever possible - accounts, descrip- + tions, dates (yesterday, today, tomorrow). If the input area is + empty, it will insert the default value. + + o If the journal defines a default commodity, it will be added to any + bare numbers entered. + + o A parenthesised transaction code may be entered following a date. + + o Comments and tags may be entered following a description or amount. + + o If you make a mistake, enter < at any prompt to restart the transac- + tion. + + o Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see the tutorial for a detailed explanation): + + $ hledger add + Adding transactions to journal file /src/hledger/examples/sample.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. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to restart the transaction. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2015/05/22]: + Description: supermarket + Account 1: expenses:food + Amount 1: $10 + Account 2: assets:checking + Amount 2 [$-10.0]: + Account 3 (or . or enter to finish this transaction): . + 2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2015/05/22]: $ + + balance + Show accounts and their balances. Aliases: b, bal. + + --change + show balance change in each period (default) + + --cumulative + show balance change accumulated across periods (in multicolumn + reports) + + -H --historical + show historical ending balance in each period (includes postings + before report start date) + + --tree show accounts as a tree; amounts include subaccounts (default in + simple reports) + + --flat show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) + + -A --average + show a row average column (in multicolumn mode) + + -T --row-total + show a row total column (in multicolumn mode) + + -N --no-total + don't show the final total row + + --drop=N + omit N leading account name parts (in flat mode) + + --no-elide + don't squash boring parent accounts (in tree mode) + + --format=LINEFORMAT + in single-column balance reports: use this custom line format + + -O FMT --output-format=FMT + select the output format. Supported formats: txt, csv, html. + + -o FILE --output-file=FILE + write output to FILE. A file extension matching one of the + above formats selects that format. + + --pretty-tables + use unicode to display prettier tables. + + --sort-amount + sort by amount instead of account code/name (in flat mode). + With multiple columns, sorts by the row total, or by row average + if that is displayed. + + --invert + display all amounts with reversed sign + + --budget + show performance compared to budget goals defined by periodic + transactions + + --show-unbudgeted + with -budget, show unbudgeted accounts also + + The balance command displays accounts and balances. It is hledger's + most featureful and versatile command. + + $ hledger balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts + -------------------- + 0 + + More precisely, the balance command shows the change to each account's + balance caused by all (matched) postings. In the common case where you + do not filter by date and your journal sets the correct opening bal- + ances, this is the same as the account's ending balance. + + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with + -S/--sort-amount, by their balance amount. + + "Boring" accounts, which contain a single interesting subaccount and no + balance of their own, are elided into the following line for more com- + pact output. (Not yet supported in tabular reports.) Use --no-elide to + prevent this. + + Account balances are "inclusive" - they include the balances of any + subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are + omitted. Use -E/--empty to show them. + + A final total is displayed by default; use -N/--no-total to suppress + it: + + $ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + + Flat mode + To see a flat list of full account names instead of the default hierar- + chical display, use --flat. In this mode, accounts (unless + depth-clipped) show their "exclusive" balance, excluding any subaccount + balances. In this mode, you can also use --drop N to omit the first + few account name components. + + $ hledger balance -p 2008/6 expenses -N --flat --drop 1 + $1 food + $1 supplies + + Depth limited balance reports + With --depth N, balance shows accounts only to the specified depth. + This is very useful to show a complex charts of accounts in less + detail. In flat mode, balances from accounts below the depth limit + will be shown as part of a parent account at the depth limit. + + $ hledger balance -N --depth 1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + Multicolumn balance reports + With a reporting interval, multiple balance columns will be shown, one + for each report period. There are three types of multi-column balance + report, showing different information: + + 1. By default: each column shows the sum of postings in that period, ie + the account's change of balance in that period. This is useful eg + for a monthly income statement: + + $ hledger balance --quarterly income expenses -E + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 + ===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 + -------------------++--------------------------------- + || $-1 $1 0 0 + + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at + the report start date: + + $ hledger balance --quarterly income expenses -E --cumulative + Ending balances (cumulative) in 2008: + + || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 + ===================++================================================= + expenses:food || 0 $1 $1 $1 + expenses:supplies || 0 $1 $1 $1 + income:gifts || 0 $-1 $-1 $-1 + income:salary || $-1 $-1 $-1 $-1 + -------------------++------------------------------------------------- + || $-1 0 0 0 + + 3. With --historical/-H: each column shows the actual historical ending + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is + useful eg for a multi-period balance sheet, and when you are showing + only the data after a certain start date: + + $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 + Ending balances (historical) in 2008/04/01-2008/12/31: + + || 2008/06/30 2008/09/30 2008/12/31 + ======================++===================================== + assets:bank:checking || $1 $1 0 + assets:bank:saving || $1 $1 $1 + assets:cash || $-2 $-2 $-2 + liabilities:debts || 0 0 $1 + ----------------------++------------------------------------- + || 0 0 0 + + Multi-column balance reports display accounts in flat mode by default; + to see the hierarchy, use --tree. + + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass + the displayed report periods. This is so that the first and last peri- + ods will be "full" and comparable to the others. + + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report + period (without -E, leading and trailing columns with all zeroes are + not shown). Second, all accounts which existed at the report start + date will be considered, not just the ones with activity during the + report period (use -E to include low-activity accounts which would oth- + erwise would be omitted). + + The -T/--row-total flag adds an additional column showing the total for + each row. + + The -A/--average flag adds a column showing the average value in each + row. + + Here's an example of all three: + + $ hledger balance -Q income expenses --tree -ETA + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 Total Average + ============++=================================================== + expenses || 0 $2 0 0 $2 $1 + food || 0 $1 0 0 $1 0 + supplies || 0 $1 0 0 $1 0 + income || $-1 $-1 0 0 $-2 $-1 + gifts || 0 $-1 0 0 $-1 0 + salary || $-1 0 0 0 $-1 0 + ------------++--------------------------------------------------- + || $-1 $1 0 0 0 0 + + # Average is rounded to the dollar here since all journal amounts are + + Budgets + With --budget and a report interval, all periodic transactions in your + journal with that interval, active during the requested report period, + are interpreted as recurring budget goals for the specified accounts + (and subaccounts), and the report will show the difference between + actual and budgeted balances. + + For example, you can take average monthly expenses in the common + expense categories to construct a minimal monthly budget: + + ;; Budget + ~ monthly + income $2000 + expenses:food $400 + expenses:bus $50 + expenses:movies $30 + assets:bank:checking + + ;; Two months worth of expenses + 2017-11-01 + income $1950 + expenses:food $396 + expenses:bus $49 + expenses:movies $30 + expenses:supplies $20 + assets:bank:checking + + 2017-12-01 + income $2100 + expenses:food $412 + expenses:bus $53 + expenses:gifts $100 + assets:bank:checking + + You can now see a monthly budget performance report: + + $ hledger balance -M --budget + Balance changes in 2017/11/01-2017/12/31: + + || 2017/11 2017/12 + =======================++================================================= + :expenses || $20 $100 + assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] + expenses:bus || $49 [98% of $50] $53 [106% of $50] + expenses:food || $396 [99% of $400] $412 [103% of $400] + expenses:movies || $30 [100% of $30] 0 [0% of $30] + income || $1950 [98% of $2000] $2100 [105% of $2000] + -----------------------++------------------------------------------------- + || 0 0 + + You can roll over unspent budgets to next period with --cumulative: + + $ hledger balance -M --budget --cumulative + Ending balances (cumulative) in 2017/11/01-2017/12/31: + + || 2017/11/30 2017/12/31 + =======================++================================================= + :expenses || $20 $120 + assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960] + expenses:bus || $49 [98% of $50] $102 [102% of $100] + expenses:food || $396 [99% of $400] $808 [101% of $800] + expenses:movies || $30 [100% of $30] $30 [50% of $60] + income || $1950 [98% of $2000] $4050 [101% of $4000] + -----------------------++------------------------------------------------- + || 0 0 + + Accounts with no budget goals (not mentioned in the periodic transac- + tions) will be aggregated under , unless you add the + --show-unbudgeted flag to display them normally: + + $ hledger balance --budget --show-unbudgeted + Balance changes in 2017/11/01-2017/12/31: + + || 2017/11 2017/12 + ======================++================================================= + assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480] + expenses:bus || $49 [98% of $50] $53 [106% of $50] + expenses:food || $396 [99% of $400] $412 [103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [100% of $30] 0 [0% of $30] + expenses:supplies || $20 0 + income || $1950 [98% of $2000] $2100 [105% of $2000] + ----------------------++------------------------------------------------- + || 0 0 + + Note -budget first arrived in hledger in 1.5 and is still pretty young; + join the discussions on mail list and issue tracker to help us refine + it. + + For more examples, see Budgeting and Forecasting. + + Custom balance output + You can customise the layout of simple (non-tabular) balance reports + with --format FMT: + + $ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 + --------------------------------- + 0 + + The FMT format string (plus a newline) specifies the formatting applied + to each account/balance pair. It may contain any suitable text, with + data fields interpolated like so: + + %[MIN][.MAX](FIELDNAME) + + o MIN pads with spaces to at least this width (optional) + + o MAX truncates at this width (optional) + + o FIELDNAME must be enclosed in parentheses, and can be one of: + + o depth_spacer - a number of spaces equal to the account's depth, or + if MIN is specified, MIN * depth spaces. + + o account - the account's name + + o total - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how multi-com- + modity amounts are rendered: + + o %_ - render on multiple lines, bottom-aligned (the default) + + o %^ - render on multiple lines, top-aligned + + o %, - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, %(depth_spacer) has no + effect, instead %(account) has indentation built in. + Experimentation may be needed to get pleasing results. + + Some example formats: + + o %(total) - the account's total + + o %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters + + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line + + o %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + + This command also supports output destination and output format selec- + tion. + + Colour support + The balance command shows negative amounts in red, if: + + o the TERM environment variable is not set to dumb + + o the output is not being redirected or piped anywhere + + balancesheet + This command displays a simple balance sheet, showing historical ending + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). Note + this report shows all account balances with normal positive sign (like + conventional financial statements, unlike balance/print/register) + (experimental). (bs) + + --change + show balance change in each period, instead of historical ending + balances + + --cumulative + show balance change accumulated across periods (in multicolumn + reports), instead of historical ending balances + + -H --historical + show historical ending balance in each period (includes postings + before report start date) (default) + + --tree show accounts as a tree; amounts include subaccounts (default in + simple reports) + + --flat show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) + + -A --average + show a row average column (in multicolumn mode) + + -T --row-total + show a row total column (in multicolumn mode) + + -N --no-total + don't show the final total row + + --drop=N + omit N leading account name parts (in flat mode) + + --no-elide + don't squash boring parent accounts (in tree mode) + + --format=LINEFORMAT + in single-column balance reports: use this custom line format + + --sort-amount + sort by amount instead of account code/name + + Example: + + $ hledger balancesheet + Balance Sheet + + Assets: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Total: + -------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for each + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for + a balance sheet; note this means it ignores report begin dates. + + This command also supports output destination and output format selec- + tion. + + balancesheetequity + Just like balancesheet, but also reports Equity (which it assumes is + under a top-level equity account). + + Example: + + $ hledger balancesheetequity + Balance Sheet With Equity + + Assets: + $-2 assets + $1 bank:saving + $-3 cash + -------------------- + $-2 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Equity: + $1 equity:owner + -------------------- + $1 + + Total: + -------------------- + 0 + + cashflow + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all + account balances with normal positive sign (like conventional financial + statements, unlike balance/print/register) (experimental). (cf) + + --change + show balance change in each period (default) + + --cumulative + show balance change accumulated across periods (in multicolumn + reports), instead of changes during periods + + -H --historical + show historical ending balance in each period (includes postings + before report start date), instead of changes during each period + + --tree show accounts as a tree; amounts include subaccounts (default in + simple reports) + + --flat show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) + + -A --average + show a row average column (in multicolumn mode) + + -T --row-total + show a row total column (in multicolumn mode) + + -N --no-total + don't show the final total row (in simple reports) + + --drop=N + omit N leading account name parts (in flat mode) + + --no-elide + don't squash boring parent accounts (in tree mode) + + --format=LINEFORMAT + in single-column balance reports: use this custom line format + + --sort-amount + sort by amount instead of account code/name + + Example: + + $ hledger cashflow + Cashflow Statement + + Cash flows: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Total: + -------------------- + $-1 + + With a reporting interval, multiple columns will be shown, one for each + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report + mode with --change/--cumulative/--historical. + + This command also supports output destination and output format selec- + tion. + + check-dates + Check that transactions are sorted by increasing date. With a query, + only matched transactions' dates are checked. + + check-dupes + Report account names having the same leaf but different prefixes. An + example: http://stefanorodighiero.net/software/hledger-dupes.html + + close + Print closing/opening transactions that bring some or all account bal- + ances to zero and back. Can be useful for bringing asset/liability + balances across file boundaries, or for closing out income/expenses for + a period. This was formerly called "equity", as in Ledger, and that + alias is also accepted. See close -help for more. + + help + Show any of the hledger manuals. + + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide + a full or partial manual name to select one. + + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can + force a particular viewer with the --info, --man, --pager, --cat flags. + + $ hledger help + Please choose a manual by typing "hledger help MANUAL" (a substring is ok). + Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot + + $ hledger help h --man + + hledger(1) hledger User Manuals hledger(1) + + NAME + hledger - a command-line accounting tool + + SYNOPSIS + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + hledger + + DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any + ... + + import + Read new transactions added to each FILE since last run, and add them + to the main journal file. + + --dry-run + just show the transactions to be imported + + The input files are specified as arguments - no need to write -f before + each one. So eg to add new transactions from all CSV files to the main + journal, it's just: hledger import *.csv + + New transactions are detected in the same way as print -new: by assum- + ing transactions are always added to the input files in increasing date + order, and by saving .latest.FILE state files. + + The -dry-run output is in journal format, so you can filter it, eg to + see only uncategorised transactions: + + $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions + + incomestatement + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, + unlike balance/print/register) (experimental). (is) + + --change + show balance change in each period (default) + + --cumulative + show balance change accumulated across periods (in multicolumn + reports), instead of changes during periods + + -H --historical + show historical ending balance in each period (includes postings + before report start date), instead of changes during each period + + --tree show accounts as a tree; amounts include subaccounts (default in + simple reports) + + --flat show accounts as a list; amounts exclude subaccounts except when + account is depth-clipped (default in multicolumn reports) + + -A --average + show a row average column (in multicolumn mode) + + -T --row-total + show a row total column (in multicolumn mode) + + -N --no-total + don't show the final total row + + --drop=N + omit N leading account name parts (in flat mode) + + --no-elide + don't squash boring parent accounts (in tree mode) + + --format=LINEFORMAT + in single-column balance reports: use this custom line format + + --sort-amount + sort by amount instead of account code/name + + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense + (plural forms also allowed.) + + $ hledger incomestatement + Income Statement + + Revenues: + $-2 income + $-1 gifts + $-1 salary + -------------------- + $-2 + + Expenses: + $2 expenses + $1 food + $1 supplies + -------------------- + $2 + + Total: + -------------------- + 0 + + With a reporting interval, multiple columns will be shown, one for each + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. + + This command also supports output destination and output format selec- + tion. + + prices + Print all market prices from the journal. + + print + Show transactions from the journal. Aliases: p, txns. + + -m STR --match=STR + show the transaction whose description is most similar to STR, + and is most recent + + --new show only newer-dated transactions added in each file since last + run + + -x --explicit + show all amounts explicitly + + -O FMT --output-format=FMT + select the output format. Supported formats: txt, csv. + + -o FILE --output-file=FILE + write output to FILE. A file extension matching one of the + above formats selects that format. + + $ hledger print + 2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + 2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + + 2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + + 2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + + 2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 + + The print command displays full journal entries (transactions) from the + journal file in date order, tidily formatted. print's output is always + a valid hledger journal. It preserves all transaction information, but + it does not preserve directives or inter-transaction comments + + Normally, the journal entry's explicit or implicit amount style is pre- + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all + amounts explicit, which can be useful for troubleshooting or for making + your journal more readable and robust against data entry errors. Note, + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- + put. + + With -B/--cost, amounts with transaction prices are converted to cost + using that price. This can be used for troubleshooting. + + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is + no similar-enough match, no transaction will be shown. + + With --new, for each FILE being read, hledger reads (and writes) a spe- + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for + ignoring already-seen entries in import data, such as downloaded CSV + files. Eg: + + $ hledger -f bank1.csv print --new + # shows transactions added since last print --new on this file + + This assumes that transactions added to FILE always have same or + increasing dates, and that transactions on the same day do not get + reordered. See also the import command. + + This command also supports output destination and output format selec- + tion. Here's an example of print's CSV output: + + $ hledger print -Ocsv + "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" + "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" + "1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" + "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" + "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" + "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" + "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" + "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" + "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" + "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" + "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o The "txnidx" (transaction index) field shows which postings belong to + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different + order, etc.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + print-unique + Print transactions which do not reuse an already-seen description. + + register + Show postings and their running total. Aliases: r, reg. + + --cumulative + show running total from report start date (default) + + -H --historical + show historical running total/balance (includes postings before + report start date) + + -A --average + show running average of posting amounts instead of total + (implies -empty) + + -r --related + show postings' siblings instead + + -w N --width=N + set output width (default: terminal width or COLUMNS. -wN,M + sets description width as well) + + -O FMT --output-format=FMT + select the output format. Supported formats: txt, csv. + + -o FILE --output-file=FILE + write output to FILE. A file extension matching one of the + above formats selects that format. + + The register command displays postings, one per line, and their running + total. This is typically used with a query selecting a particular + account, to see that account's activity: + + $ hledger register checking + 2008/01/01 income assets:bank:checking $1 $1 + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see + only recent activity, with a historically accurate running balance: + + $ hledger register checking -b 2008/6 --historical + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + The --depth option limits the amount of sub-account detail displayed. + + The --average/-A flag shows the running average posting amount instead + of the running total (so, the final number displayed is the average for + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one + account and one commodity. + + The --related/-r flag shows the other postings in the transactions of + the postings which would normally be shown. + + With a reporting interval, register shows summary postings, one per + interval, aggregating the postings to each account: + + $ hledger register --monthly income + 2008/01 income:salary $-1 $-1 + 2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, are + not shown by default; use the --empty/-E flag to see them: + + $ hledger register --monthly income -E + 2008/01 income:salary $-1 $-1 + 2008/02 0 $-1 + 2008/03 0 $-1 + 2008/04 0 $-1 + 2008/05 0 $-1 + 2008/06 income:gifts $-1 $-2 + 2008/07 0 $-2 + 2008/08 0 $-2 + 2008/09 0 $-2 + 2008/10 0 $-2 + 2008/11 0 $-2 + 2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The --depth + option helps with this, causing subaccounts to be aggregated: + + $ hledger register --monthly assets --depth 1h + 2008/01 assets $1 $1 + 2008/06 assets $-1 0 + 2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full + length and comparable to the others in the report. + + Custom register output + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not + a bash shell variable) or by using the --width/-w option. + + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a + description width as part of -width's argument, comma-separated: + --width W,D . Here's a diagram: + + <--------------------------------- width (W) ----------------------------------> + date (10) description (D) account (W-41-D) amount (12) balance (12) + DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + + $ hledger reg # use terminal width (or 80 on windows) + $ hledger reg -w 100 # use width 100 + $ COLUMNS=100 hledger reg # set with one-time environment variable + $ export COLUMNS=100; hledger reg # set till session end (or window resize) + $ hledger reg -w 100,40 # set overall width 100, description width 40 + $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width + + This command also supports output destination and output format selec- + tion. + + register-match + Print the one posting whose transaction description is closest to DESC, + in the style of the register command. Helps ledger-autosync detect + already-seen transactions when importing. + + rewrite + Print all transactions, adding custom postings to the matched ones. + + stats + Show some journal statistics. + + -o FILE --output-file=FILE + write output to FILE. A file extension matching one of the + above formats selects that format. + + $ hledger stats + Main journal file : /src/hledger/examples/sample.journal + Included journal files : + Transactions span : 2008-01-01 to 2009-01-01 (366 days) + Last transaction : 2008-12-31 (2333 days ago) + Transactions : 5 (0.0 per day) + Transactions last 30 days: 0 (0.0 per day) + Transactions last 7 days : 0 (0.0 per day) + Payees/descriptions : 5 + Accounts : 8 (depth 3) + Commodities : 1 ($) + + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report + for each report period. + + This command also supports output destination and output format selec- + tion. + + tags + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are + shown. With additional QUERY arguments, only transactions matching the + query are considered. + + test + Run built-in unit tests. + + $ hledger test + Cases: 74 Tried: 74 Errors: 0 Failures: 0 + + This command runs hledger's built-in unit tests and displays a quick + report. With a regular expression argument, it selects only tests with + matching names. It's mainly used in development, but it's also nice to + be able to check your hledger executable for smoke at any time. + +ADD-ON COMMANDS + hledger also searches for external add-on commands, and will include + these in the commands list. These are programs or scripts in your PATH + whose name starts with hledger- and ends with a recognised file exten- + sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). + + Add-ons can be invoked like any hledger command, but there are a few + things to be aware of. Eg if the hledger-web add-on is installed, + + o hledger -h web shows hledger's help, while hledger web -h shows + hledger-web's help. + + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; + you must use hledger web -- --serve --port 9000. + + o You can always run add-ons directly if preferred: + hledger-web --serve --port 9000. + + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line + options, journal parsing, reporting, etc. + + Here are some hledger add-ons available: + + Official add-ons + These are maintained and released along with hledger. + + api + hledger-api serves hledger data as a JSON web API. + + ui + hledger-ui provides an efficient curses-style interface. + + web + hledger-web provides a simple web interface. + + Third party add-ons + These are maintained separately, and usually updated shortly after a + hledger release. + + diff + hledger-diff shows differences in an account's transactions between one + journal file and another. + + iadd + hledger-iadd is a curses-style, more interactive replacement for the + add command. + + interest + hledger-interest generates interest transactions for an account accord- + ing to various schemes. + + irr + hledger-irr calculates the internal rate of return of an investment + account. + + Experimental add-ons + These are available in source form in the hledger repo's bin/ direc- + tory; installing them is pretty easy. They may be less mature and doc- + umented than built-in commands. Reading and tweaking these is a good + way to start making your own! + + autosync + hledger-autosync is a symbolic link for easily running ledger-autosync, + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank + offers OFX Direct Connect. + + chart + hledger-chart.hs is an old pie chart generator, in need of some love. + + check + hledger-check.hs checks more powerful account balance assertions. + +ENVIRONMENT + COLUMNS The screen width used by the register command. Default: the + full terminal width. + + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede addon command options with -- when invoked from + hledger is awkward. + + When input data contains non-ascii characters, a suitable system locale + must be configured (or there will be an unhelpful error). Eg on POSIX, + set LANG to something other than C. + + In a Microsoft Windows CMD window, non-ascii characters and colours are + not supported. + + In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger + add. + + Not all of Ledger's journal file syntax is supported. See file format + differences. + + On large data files, hledger is slower and uses more memory than + Ledger. + +TROUBLESHOOTING + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug + tracker): + + Successfully installed, but "No command `hledger' found" + stack and cabal install binaries into a special directory, which should + be added to your PATH environment variable. Eg on unix-like systems, + that is ~/.local/bin and ~/.cabal/bin respectively. + + I set a custom LEDGER_FILE, but hledger is still using the default file + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may + need to use export. Here's an explanation. + + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + character" errors + In order to handle non-ascii letters and symbols (like ), hledger needs + an appropriate locale. This is usually configured system-wide; you can + also configure it temporarily. The locale may need to be one that sup- + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + I'm not sure yet). + + Here's an example of setting the locale temporarily, on ubuntu + gnu/linux: + + $ file my.journal + my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded + $ locale -a + C + en_US.utf8 # <- a UTF8-aware locale is available + POSIX + $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command + + Here's one way to set it permanently, there are probably better ways: + + $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile + $ bash --login + + If we preferred to use eg fr_FR.utf8, we might have to install that + first: + + $ apt-get install language-pack-fr + $ locale -a + C + en_US.utf8 + fr_BE.utf8 + fr_CA.utf8 + fr_CH.utf8 + fr_FR.utf8 + fr_LU.utf8 + POSIX + $ LANG=fr_FR.utf8 hledger -f my.journal print + + Note some platforms allow variant locale spellings, but not all (ubuntu + accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.9 March 2018 hledger(1) diff --git a/embeddedfiles/hledger_csv.5 b/embeddedfiles/hledger_csv.5 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_csv.5 @@ -0,0 +1,334 @@ + +.TH "hledger_csv" "5" "March 2018" "hledger 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +CSV \- how hledger reads CSV data, and the CSV rules file format +.SH DESCRIPTION +.PP +hledger can read CSV (comma\-separated value) files as if they were +journal files, automatically converting each CSV record into a +transaction. +(To learn about \f[I]writing\f[] CSV, see CSV output.) +.PP +Converting CSV to transactions requires some special conversion rules. +These do several things: +.IP \[bu] 2 +they describe the layout and format of the CSV data +.IP \[bu] 2 +they can customize the generated journal entries using a simple +templating language +.IP \[bu] 2 +they can add refinements based on patterns in the CSV data, eg +categorizing transactions with more detailed account names. +.PP +When reading a CSV file named \f[C]FILE.csv\f[], hledger looks for a +conversion rules file named \f[C]FILE.csv.rules\f[] in the same +directory. +You can override this with the \f[C]\-\-rules\-file\f[] option. +If the rules file does not exist, hledger will auto\-create one with +some example rules, which you'll need to adjust. +.PP +At minimum, the rules file must identify the \f[C]date\f[] and +\f[C]amount\f[] fields. +It may also be necessary to specify the date format, and the number of +header lines to skip. +Eg: +.IP +.nf +\f[C] +fields\ date,\ _,\ _,\ amount +date\-format\ \ %d/%m/%Y +skip\ 1 +\f[] +.fi +.PP +A more complete example: +.IP +.nf +\f[C] +#\ hledger\ CSV\ rules\ for\ amazon.com\ order\ history + +#\ sample: +#\ "Date","Type","To/From","Name","Status","Amount","Fees","Transaction\ ID" +#\ "Jul\ 29,\ 2012","Payment","To","Adapteva,\ Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" + +#\ skip\ one\ header\ line +skip\ 1 + +#\ name\ the\ csv\ fields\ (and\ assign\ the\ transaction\[aq]s\ date,\ amount\ and\ code) +fields\ date,\ _,\ toorfrom,\ name,\ amzstatus,\ amount,\ fees,\ code + +#\ how\ to\ parse\ the\ date +date\-format\ %b\ %\-d,\ %Y + +#\ combine\ two\ fields\ to\ make\ the\ description +description\ %toorfrom\ %name + +#\ save\ these\ fields\ as\ tags +comment\ \ \ \ \ status:%amzstatus,\ fees:%fees + +#\ set\ the\ base\ account\ for\ all\ transactions +account1\ \ \ \ assets:amazon + +#\ flip\ the\ sign\ on\ the\ amount +amount\ \ \ \ \ \ \-%amount +\f[] +.fi +.PP +For more examples, see Convert CSV files. +.SH CSV RULES +.PP +The following seven kinds of rule can appear in the rules file, in any +order. +Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are +ignored. +.SS skip +.PP +\f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[] +.PP +Skip this number of CSV records at the beginning. +You'll need this whenever your CSV data contains header lines. +Eg: +.IP +.nf +\f[C] +#\ ignore\ the\ first\ CSV\ line +skip\ 1 +\f[] +.fi +.SS date\-format +.PP +\f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[] +.PP +When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or +\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you'll need to specify +the format. +DATEFMT is a strptime\-like date parsing pattern, which must parse the +date field values completely. +Examples: +.IP +.nf +\f[C] +#\ for\ dates\ like\ "6/11/2013": +date\-format\ %\-d/%\-m/%Y +\f[] +.fi +.IP +.nf +\f[C] +#\ for\ dates\ like\ "11/06/2013": +date\-format\ %m/%d/%Y +\f[] +.fi +.IP +.nf +\f[C] +#\ for\ dates\ like\ "2013\-Nov\-06": +date\-format\ %Y\-%h\-%d +\f[] +.fi +.IP +.nf +\f[C] +#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM": +date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p +\f[] +.fi +.SS field list +.PP +\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[], +\f[I]\f[CI]FIELDNAME2\f[I]\f[]\&... +.PP +This (a) names the CSV fields, in order (names may not contain +whitespace; uninteresting names may be left blank), and (b) assigns them +to journal entry fields if you use any of these standard field names: +\f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], +\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[], +\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[], +\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[]. +Eg: +.IP +.nf +\f[C] +#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]s\ date,\ description\ and\ amount, +#\ and\ give\ the\ 7th\ and\ 8th\ fields\ meaningful\ names\ for\ later\ reference: +# +#\ CSV\ field: +#\ \ \ \ \ \ 1\ \ \ \ \ 2\ \ \ \ \ \ \ \ \ \ \ \ 3\ 4\ \ \ \ \ \ \ 5\ 6\ 7\ \ \ \ \ \ \ \ \ \ 8 +#\ entry\ field: +fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield +\f[] +.fi +.SS field assignment +.PP +\f[I]\f[CI]ENTRYFIELDNAME\f[I]\f[] \f[I]\f[CI]FIELDVALUE\f[I]\f[] +.PP +This sets a journal entry field (one of the standard names above) to the +given text value, which can include CSV field values interpolated by +name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]). + Eg: +.IP +.nf +\f[C] +#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended +amount\ USD\ %4 +\f[] +.fi +.IP +.nf +\f[C] +#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags) +comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1 +\f[] +.fi +.PP +Field assignments can be used instead of or in addition to a field list. +.SS conditional block +.PP +\f[C]if\f[] \f[I]\f[CI]PATTERN\f[I]\f[] +.PD 0 +.P +.PD +\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... +.PP +\f[C]if\f[] +.PD 0 +.P +.PD +\f[I]\f[CI]PATTERN\f[I]\f[] +.PD 0 +.P +.PD +\f[I]\f[CI]PATTERN\f[I]\f[]\&... +.PD 0 +.P +.PD +\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]\&... +.PP +This applies one or more field assignments, only to those CSV records +matched by one of the PATTERNs. +The patterns are case\-insensitive regular expressions which match +anywhere within the whole CSV record (it's not yet possible to match +within a specific field). +When there are multiple patterns they can be written on separate lines, +unindented. +The field assignments are on separate lines indented by at least one +space. +Examples: +.IP +.nf +\f[C] +#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries" +if\ groceries +\ account2\ expenses:groceries +\f[] +.fi +.IP +.nf +\f[C] +#\ if\ the\ CSV\ record\ contains\ any\ of\ these\ patterns,\ set\ account2\ and\ comment\ as\ shown +if +monthly\ service\ fee +atm\ transaction\ fee +banking\ thru\ software +\ account2\ expenses:business:banking +\ comment\ \ XXX\ deductible\ ?\ check\ it +\f[] +.fi +.SS include +.PP +\f[C]include\f[]\f[I]\f[CI]RULESFILE\f[I]\f[] +.PP +Include another rules file at this point. +\f[C]RULESFILE\f[] is either an absolute file path or a path relative to +the current file's directory. +Eg: +.IP +.nf +\f[C] +#\ rules\ reused\ with\ several\ CSV\ files +include\ common.rules +\f[] +.fi +.SS newest\-first +.PP +\f[C]newest\-first\f[] +.PP +Consider adding this rule if all of the following are true: you might be +processing just one day of data, your CSV records are in reverse +chronological order (newest first), and you care about preserving the +order of same\-day transactions. +It usually isn't needed, because hledger autodetects the CSV order, but +when all CSV records have the same date it will assume they are oldest +first. +.SH CSV TIPS +.SS CSV ordering +.PP +The generated journal entries will be sorted by date. +The order of same\-day entries will be preserved (except in the special +case where you might need \f[C]newest\-first\f[], see above). +.SS CSV accounts +.PP +Each journal entry will have two postings, to \f[C]account1\f[] and +\f[C]account2\f[] respectively. +It's not yet possible to generate entries with more than two postings. +It's conventional and recommended to use \f[C]account1\f[] for the +account whose CSV we are reading. +.SS CSV amounts +.PP +The \f[C]amount\f[] field sets the amount of the \f[C]account1\f[] +posting. +.PP +If the CSV has debit/credit amounts in separate fields, assign to the +\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead. +(Whichever one has a value will be used, with appropriate sign. +If both contain a value, it may not work so well.) +.PP +If an amount value is parenthesised, it will be de\-parenthesised and +sign\-flipped. +.PP +If an amount value begins with a double minus sign, those will cancel +out and be removed. +.PP +If the CSV has the currency symbol in a separate field, assign that to +the \f[C]currency\f[] pseudo field to have it prepended to the amount. +Or, you can use a field assignment to \f[C]amount\f[] that interpolates +both CSV fields (giving more control, eg to put the currency symbol on +the right). +.SS CSV balance assertions +.PP +If the CSV includes a running balance, you can assign that to the +\f[C]balance\f[] pseudo field; whenever the running balance value is +non\-empty, it will be asserted as the balance after the +\f[C]account1\f[] posting. +.SS Reading multiple CSV files +.PP +You can read multiple CSV files at once using multiple \f[C]\-f\f[] +arguments on the command line, and hledger will look for a +correspondingly\-named rules file for each. +Note if you use the \f[C]\-\-rules\-file\f[] option, this one rules file +will be used for all the CSV files being read. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger_csv.info b/embeddedfiles/hledger_csv.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_csv.info @@ -0,0 +1,349 @@ +This is hledger_csv.info, produced by makeinfo version 6.5 from stdin. + + +File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir) + +hledger_csv(5) hledger 1.9 +************************** + +hledger can read CSV (comma-separated value) files as if they were +journal files, automatically converting each CSV record into a +transaction. (To learn about _writing_ CSV, see CSV output.) + + Converting CSV to transactions requires some special conversion +rules. These do several things: + + * they describe the layout and format of the CSV data + * they can customize the generated journal entries using a simple + templating language + * they can add refinements based on patterns in the CSV data, eg + categorizing transactions with more detailed account names. + + When reading a CSV file named 'FILE.csv', hledger looks for a +conversion rules file named 'FILE.csv.rules' in the same directory. You +can override this with the '--rules-file' option. If the rules file +does not exist, hledger will auto-create one with some example rules, +which you'll need to adjust. + + At minimum, the rules file must identify the 'date' and 'amount' +fields. It may also be necessary to specify the date format, and the +number of header lines to skip. Eg: + +fields date, _, _, amount +date-format %d/%m/%Y +skip 1 + + A more complete example: + +# hledger CSV rules for amazon.com order history + +# sample: +# "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" +# "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" + +# skip one header line +skip 1 + +# name the csv fields (and assign the transaction's date, amount and code) +fields date, _, toorfrom, name, amzstatus, amount, fees, code + +# how to parse the date +date-format %b %-d, %Y + +# combine two fields to make the description +description %toorfrom %name + +# save these fields as tags +comment status:%amzstatus, fees:%fees + +# set the base account for all transactions +account1 assets:amazon + +# flip the sign on the amount +amount -%amount + + For more examples, see Convert CSV files. +* Menu: + +* CSV RULES:: +* CSV TIPS:: + + +File: hledger_csv.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top + +1 CSV RULES +*********** + +The following seven kinds of rule can appear in the rules file, in any +order. Blank lines and lines beginning with '#' or ';' are ignored. +* Menu: + +* skip:: +* date-format:: +* field list:: +* field assignment:: +* conditional block:: +* include:: +* newest-first:: + + +File: hledger_csv.info, Node: skip, Next: date-format, Up: CSV RULES + +1.1 skip +======== + +'skip'_'N'_ + + Skip this number of CSV records at the beginning. You'll need this +whenever your CSV data contains header lines. Eg: + +# ignore the first CSV line +skip 1 + + +File: hledger_csv.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES + +1.2 date-format +=============== + +'date-format'_'DATEFMT'_ + + When your CSV date fields are not formatted like 'YYYY/MM/DD' (or +'YYYY-MM-DD' or 'YYYY.MM.DD'), you'll need to specify the format. +DATEFMT is a strptime-like date parsing pattern, which must parse the +date field values completely. Examples: + +# for dates like "6/11/2013": +date-format %-d/%-m/%Y + +# for dates like "11/06/2013": +date-format %m/%d/%Y + +# for dates like "2013-Nov-06": +date-format %Y-%h-%d + +# for dates like "11/6/2013 11:32 PM": +date-format %-m/%-d/%Y %l:%M %p + + +File: hledger_csv.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES + +1.3 field list +============== + +'fields'_'FIELDNAME1'_, _'FIELDNAME2'_... + + This (a) names the CSV fields, in order (names may not contain +whitespace; uninteresting names may be left blank), and (b) assigns them +to journal entry fields if you use any of these standard field names: +'date', 'date2', 'status', 'code', 'description', 'comment', 'account1', +'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'. +Eg: + +# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, +# and give the 7th and 8th fields meaningful names for later reference: +# +# CSV field: +# 1 2 3 4 5 6 7 8 +# entry field: +fields date, description, , amount, , , somefield, anotherfield + + +File: hledger_csv.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES + +1.4 field assignment +==================== + +_'ENTRYFIELDNAME'_ _'FIELDVALUE'_ + + This sets a journal entry field (one of the standard names above) to +the given text value, which can include CSV field values interpolated by +name ('%CSVFIELDNAME') or 1-based position ('%N'). Eg: + +# set the amount to the 4th CSV field with "USD " prepended +amount USD %4 + +# combine three fields to make a comment (containing two tags) +comment note: %somefield - %anotherfield, date: %1 + + Field assignments can be used instead of or in addition to a field +list. + + +File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES + +1.5 conditional block +===================== + +'if' _'PATTERN'_ + _'FIELDASSIGNMENTS'_... + + 'if' +_'PATTERN'_ +_'PATTERN'_... + _'FIELDASSIGNMENTS'_... + + This applies one or more field assignments, only to those CSV records +matched by one of the PATTERNs. The patterns are case-insensitive +regular expressions which match anywhere within the whole CSV record +(it's not yet possible to match within a specific field). When there +are multiple patterns they can be written on separate lines, unindented. +The field assignments are on separate lines indented by at least one +space. Examples: + +# if the CSV record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the CSV record contains any of these patterns, set account2 and comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + +File: hledger_csv.info, Node: include, Next: newest-first, Prev: conditional block, Up: CSV RULES + +1.6 include +=========== + +'include'_'RULESFILE'_ + + Include another rules file at this point. 'RULESFILE' is either an +absolute file path or a path relative to the current file's directory. +Eg: + +# rules reused with several CSV files +include common.rules + + +File: hledger_csv.info, Node: newest-first, Prev: include, Up: CSV RULES + +1.7 newest-first +================ + +'newest-first' + + Consider adding this rule if all of the following are true: you might +be processing just one day of data, your CSV records are in reverse +chronological order (newest first), and you care about preserving the +order of same-day transactions. It usually isn't needed, because +hledger autodetects the CSV order, but when all CSV records have the +same date it will assume they are oldest first. + + +File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top + +2 CSV TIPS +********** + +* Menu: + +* CSV ordering:: +* CSV accounts:: +* CSV amounts:: +* CSV balance assertions:: +* Reading multiple CSV files:: + + +File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS + +2.1 CSV ordering +================ + +The generated journal entries will be sorted by date. The order of +same-day entries will be preserved (except in the special case where you +might need 'newest-first', see above). + + +File: hledger_csv.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS + +2.2 CSV accounts +================ + +Each journal entry will have two postings, to 'account1' and 'account2' +respectively. It's not yet possible to generate entries with more than +two postings. It's conventional and recommended to use 'account1' for +the account whose CSV we are reading. + + +File: hledger_csv.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS + +2.3 CSV amounts +=============== + +The 'amount' field sets the amount of the 'account1' posting. + + If the CSV has debit/credit amounts in separate fields, assign to the +'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has +a value will be used, with appropriate sign. If both contain a value, +it may not work so well.) + + If an amount value is parenthesised, it will be de-parenthesised and +sign-flipped. + + If an amount value begins with a double minus sign, those will cancel +out and be removed. + + If the CSV has the currency symbol in a separate field, assign that +to the 'currency' pseudo field to have it prepended to the amount. Or, +you can use a field assignment to 'amount' that interpolates both CSV +fields (giving more control, eg to put the currency symbol on the +right). + + +File: hledger_csv.info, Node: CSV balance assertions, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS + +2.4 CSV balance assertions +========================== + +If the CSV includes a running balance, you can assign that to the +'balance' pseudo field; whenever the running balance value is non-empty, +it will be asserted as the balance after the 'account1' posting. + + +File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions, Up: CSV TIPS + +2.5 Reading multiple CSV files +============================== + +You can read multiple CSV files at once using multiple '-f' arguments on +the command line, and hledger will look for a correspondingly-named +rules file for each. Note if you use the '--rules-file' option, this +one rules file will be used for all the CSV files being read. + + +Tag Table: +Node: Top72 +Node: CSV RULES2161 +Ref: #csv-rules2269 +Node: skip2531 +Ref: #skip2625 +Node: date-format2797 +Ref: #date-format2924 +Node: field list3430 +Ref: #field-list3567 +Node: field assignment4272 +Ref: #field-assignment4427 +Node: conditional block4931 +Ref: #conditional-block5085 +Node: include5981 +Ref: #include6111 +Node: newest-first6342 +Ref: #newest-first6456 +Node: CSV TIPS6867 +Ref: #csv-tips6961 +Node: CSV ordering7079 +Ref: #csv-ordering7197 +Node: CSV accounts7378 +Ref: #csv-accounts7516 +Node: CSV amounts7770 +Ref: #csv-amounts7916 +Node: CSV balance assertions8691 +Ref: #csv-balance-assertions8873 +Node: Reading multiple CSV files9078 +Ref: #reading-multiple-csv-files9248 + +End Tag Table diff --git a/embeddedfiles/hledger_csv.txt b/embeddedfiles/hledger_csv.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_csv.txt @@ -0,0 +1,252 @@ + +hledger_csv(5) hledger User Manuals hledger_csv(5) + + + +NAME + CSV - how hledger reads CSV data, and the CSV rules file format + +DESCRIPTION + hledger can read CSV (comma-separated value) files as if they were + journal files, automatically converting each CSV record into a transac- + tion. (To learn about writing CSV, see CSV output.) + + Converting CSV to transactions requires some special conversion rules. + These do several things: + + o they describe the layout and format of the CSV data + + o they can customize the generated journal entries using a simple tem- + plating language + + o they can add refinements based on patterns in the CSV data, eg cate- + gorizing transactions with more detailed account names. + + When reading a CSV file named FILE.csv, hledger looks for a conversion + rules file named FILE.csv.rules in the same directory. You can over- + ride this with the --rules-file option. If the rules file does not + exist, hledger will auto-create one with some example rules, which + you'll need to adjust. + + At minimum, the rules file must identify the date and amount fields. + It may also be necessary to specify the date format, and the number of + header lines to skip. Eg: + + fields date, _, _, amount + date-format %d/%m/%Y + skip 1 + + A more complete example: + + # hledger CSV rules for amazon.com order history + + # sample: + # "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" + # "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" + + # skip one header line + skip 1 + + # name the csv fields (and assign the transaction's date, amount and code) + fields date, _, toorfrom, name, amzstatus, amount, fees, code + + # how to parse the date + date-format %b %-d, %Y + + # combine two fields to make the description + description %toorfrom %name + + # save these fields as tags + comment status:%amzstatus, fees:%fees + + # set the base account for all transactions + account1 assets:amazon + + # flip the sign on the amount + amount -%amount + + For more examples, see Convert CSV files. + +CSV RULES + The following seven kinds of rule can appear in the rules file, in any + order. Blank lines and lines beginning with # or ; are ignored. + + skip + skipN + + Skip this number of CSV records at the beginning. You'll need this + whenever your CSV data contains header lines. Eg: + + # ignore the first CSV line + skip 1 + + date-format + date-formatDATEFMT + + When your CSV date fields are not formatted like YYYY/MM/DD (or + YYYY-MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT + is a strptime-like date parsing pattern, which must parse the date + field values completely. Examples: + + # for dates like "6/11/2013": + date-format %-d/%-m/%Y + + # for dates like "11/06/2013": + date-format %m/%d/%Y + + # for dates like "2013-Nov-06": + date-format %Y-%h-%d + + # for dates like "11/6/2013 11:32 PM": + date-format %-m/%-d/%Y %l:%M %p + + field list + fieldsFIELDNAME1, FIELDNAME2... + + This (a) names the CSV fields, in order (names may not contain white- + space; uninteresting names may be left blank), and (b) assigns them to + journal entry fields if you use any of these standard field names: + date, date2, status, code, description, comment, account1, account2, + amount, amount-in, amount-out, currency, balance. Eg: + + # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, + # and give the 7th and 8th fields meaningful names for later reference: + # + # CSV field: + # 1 2 3 4 5 6 7 8 + # entry field: + fields date, description, , amount, , , somefield, anotherfield + + field assignment + ENTRYFIELDNAME FIELDVALUE + + This sets a journal entry field (one of the standard names above) to + the given text value, which can include CSV field values interpolated + by name (%CSVFIELDNAME) or 1-based position (%N). + Eg: + + # set the amount to the 4th CSV field with "USD " prepended + amount USD %4 + + # combine three fields to make a comment (containing two tags) + comment note: %somefield - %anotherfield, date: %1 + + Field assignments can be used instead of or in addition to a field + list. + + conditional block + if PATTERN + FIELDASSIGNMENTS... + + if + PATTERN + PATTERN... + FIELDASSIGNMENTS... + + This applies one or more field assignments, only to those CSV records + matched by one of the PATTERNs. The patterns are case-insensitive reg- + ular expressions which match anywhere within the whole CSV record (it's + not yet possible to match within a specific field). When there are + multiple patterns they can be written on separate lines, unindented. + The field assignments are on separate lines indented by at least one + space. Examples: + + # if the CSV record contains "groceries", set account2 to "expenses:groceries" + if groceries + account2 expenses:groceries + + # if the CSV record contains any of these patterns, set account2 and comment as shown + if + monthly service fee + atm transaction fee + banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + include + includeRULESFILE + + Include another rules file at this point. RULESFILE is either an abso- + lute file path or a path relative to the current file's directory. Eg: + + # rules reused with several CSV files + include common.rules + + newest-first + newest-first + + Consider adding this rule if all of the following are true: you might + be processing just one day of data, your CSV records are in reverse + chronological order (newest first), and you care about preserving the + order of same-day transactions. It usually isn't needed, because + hledger autodetects the CSV order, but when all CSV records have the + same date it will assume they are oldest first. + +CSV TIPS + CSV ordering + The generated journal entries will be sorted by date. The order of + same-day entries will be preserved (except in the special case where + you might need newest-first, see above). + + CSV accounts + Each journal entry will have two postings, to account1 and account2 + respectively. It's not yet possible to generate entries with more than + two postings. It's conventional and recommended to use account1 for + the account whose CSV we are reading. + + CSV amounts + The amount field sets the amount of the account1 posting. + + If the CSV has debit/credit amounts in separate fields, assign to the + amount-in and amount-out pseudo fields instead. (Whichever one has a + value will be used, with appropriate sign. If both contain a value, it + may not work so well.) + + If an amount value is parenthesised, it will be de-parenthesised and + sign-flipped. + + If an amount value begins with a double minus sign, those will cancel + out and be removed. + + If the CSV has the currency symbol in a separate field, assign that to + the currency pseudo field to have it prepended to the amount. Or, you + can use a field assignment to amount that interpolates both CSV fields + (giving more control, eg to put the currency symbol on the right). + + CSV balance assertions + If the CSV includes a running balance, you can assign that to the bal- + ance pseudo field; whenever the running balance value is non-empty, it + will be asserted as the balance after the account1 posting. + + Reading multiple CSV files + You can read multiple CSV files at once using multiple -f arguments on + the command line, and hledger will look for a correspondingly-named + rules file for each. Note if you use the --rules-file option, this one + rules file will be used for all the CSV files being read. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.9 March 2018 hledger_csv(5) diff --git a/embeddedfiles/hledger_journal.5 b/embeddedfiles/hledger_journal.5 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_journal.5 @@ -0,0 +1,1303 @@ +.\"t + +.TH "hledger_journal" "5" "March 2018" "hledger 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +Journal \- hledger's default file format, representing a General Journal +.SH DESCRIPTION +.PP +hledger's usual data source is a plain text file containing journal +entries in hledger journal format. +This file represents a standard accounting general journal. +I use file names ending in \f[C]\&.journal\f[], but that's not required. +The journal file contains a number of transaction entries, each +describing a transfer of money (or any commodity) between two or more +named accounts, in a simple format readable by both hledger and humans. +.PP +hledger's journal format is a compatible subset, mostly, of ledger's +journal format, so hledger can work with compatible ledger journal files +as well. +It's safe, and encouraged, to run both hledger and ledger on the same +journal file, eg to validate the results you're getting. +.PP +You can use hledger without learning any more about this file; just use +the add or web commands to create and update it. +Many users, though, also edit the journal file directly with a text +editor, perhaps assisted by the helper modes for emacs or vim. +.PP +Here's an example: +.IP +.nf +\f[C] +;\ A\ sample\ journal\ file.\ This\ is\ a\ comment. + +2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ transaction\[aq]s\ first\ line\ starts\ in\ column\ 0,\ contains\ date\ and\ description +\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ posting\ lines\ start\ with\ whitespace,\ each\ contains\ an\ account\ name +\ \ \ \ income:salary\ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ \ \ \ followed\ by\ at\ least\ two\ spaces\ and\ an\ amount + +2008/06/01\ gift +\ \ \ \ assets:bank:checking\ \ $1\ \ \ \ ;\ <\-\ at\ least\ two\ postings\ in\ a\ transaction +\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ $\-1\ \ \ \ ;\ <\-\ their\ amounts\ must\ balance\ to\ 0 + +2008/06/02\ save +\ \ \ \ assets:bank:saving\ \ \ \ $1 +\ \ \ \ assets:bank:checking\ \ \ \ \ \ \ \ ;\ <\-\ one\ amount\ may\ be\ omitted;\ here\ $\-1\ is\ inferred + +2008/06/03\ eat\ &\ shop\ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ description\ can\ be\ anything +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ $1 +\ \ \ \ expenses:supplies\ \ \ \ \ $1\ \ \ \ ;\ <\-\ this\ transaction\ debits\ two\ expense\ accounts +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ $\-2\ inferred + +2008/10/01\ take\ a\ loan +\ \ \ \ assets:bank:checking\ \ $1 +\ \ \ \ liabilities:debts\ \ \ \ $\-1 + +2008/12/31\ *\ pay\ off\ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ an\ optional\ *\ or\ !\ after\ the\ date\ means\ "cleared"\ (or\ anything\ you\ want) +\ \ \ \ liabilities:debts\ \ \ \ \ $1 +\ \ \ \ assets:bank:checking +\f[] +.fi +.SH FILE FORMAT +.SS Transactions +.PP +Transactions are movements of some quantity of commodities between named +accounts. +Each transaction is represented by a journal entry beginning with a +simple date in column 0. +This can be followed by any of the following, separated by spaces: +.IP \[bu] 2 +(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]) +.IP \[bu] 2 +(optional) a transaction code (any short number or text, enclosed in +parentheses) +.IP \[bu] 2 +(optional) a transaction description (any remaining text until end of +line or a semicolon) +.IP \[bu] 2 +(optional) a transaction comment (any remaining text following a +semicolon until end of line) +.PP +Then comes zero or more (but usually at least 2) indented lines +representing\&... +.SS Postings +.PP +A posting is an addition of some amount to, or removal of some amount +from, an account. +Each posting line begins with at least one space or tab (2 or 4 spaces +is common), followed by: +.IP \[bu] 2 +(optional) a status character (empty, \f[C]!\f[], or \f[C]*\f[]), +followed by a space +.IP \[bu] 2 +(required) an account name (any text, optionally containing \f[B]single +spaces\f[], until end of line or a double space) +.IP \[bu] 2 +(optional) \f[B]two or more spaces\f[] or tabs followed by an amount. +.PP +Positive amounts are being added to the account, negative amounts are +being removed. +.PP +The amounts within a transaction must always sum up to zero. +As a convenience, one amount may be left blank; it will be inferred so +as to balance the transaction. +.PP +Be sure to note the unusual two\-space delimiter between account name +and amount. +This makes it easy to write account names containing spaces. +But if you accidentally leave only one space (or tab) before the amount, +the amount will be considered part of the account name. +.SS Dates +.SS Simple dates +.PP +Within a journal file, transaction dates use Y/M/D (or Y\-M\-D or Y.M.D) +Leading zeros are optional. +The year may be omitted, in which case it will be inferred from the +context \- the current transaction, the default year set with a default +year directive, or the current date when the command is run. +Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[], +\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[]. +.SS Secondary dates +.PP +Real\-life transactions sometimes involve more than one date \- eg the +date you write a cheque, and the date it clears in your bank. +When you want to model this, eg for more accurate balances, you can +specify individual posting dates, which I recommend. +Or, you can use the secondary dates (aka auxiliary/effective dates) +feature, supported for compatibility with Ledger. +.PP +A secondary date can be written after the primary date, separated by an +equals sign. +The primary date, on the left, is used by default; the secondary date, +on the right, is used when the \f[C]\-\-date2\f[] flag is specified +(\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work). +.PP +The meaning of secondary dates is up to you, but it's best to follow a +consistent rule. +Eg write the bank's clearing date as primary, and when needed, the date +the transaction was initiated as secondary. +.PP +Here's an example. +Note that a secondary date will use the year of the primary date if +unspecified. +.IP +.nf +\f[C] +2010/2/23=2/19\ movie\ ticket +\ \ expenses:cinema\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10 +\ \ assets:checking +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ register\ checking +2010/02/23\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ register\ checking\ \-\-date2 +2010/02/19\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.PP +Secondary dates require some effort; you must use them consistently in +your journal entries and remember whether to use or not use the +\f[C]\-\-date2\f[] flag for your reports. +They are included in hledger for Ledger compatibility, but posting dates +are a more powerful and less confusing alternative. +.SS Posting dates +.PP +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like \f[C]date:DATE\f[]. +This is probably the best way to control posting dates precisely. +Eg in this example the expense should appear in May reports, and the +deduction from checking should be reported on 6/1 for easy bank +reconciliation: +.IP +.nf +\f[C] +2015/5/30 +\ \ \ \ expenses:food\ \ \ \ \ $10\ \ \ ;\ food\ purchased\ on\ saturday\ 5/30 +\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ ;\ bank\ cleared\ it\ on\ monday,\ date:6/1 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ register\ food +2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.j\ register\ checking +2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.PP +DATE should be a simple date; if the year is not specified it will use +the year of the transaction's date. +You can set the secondary date similarly, with \f[C]date2:DATE2\f[]. +The \f[C]date:\f[] or \f[C]date2:\f[] tags must have a valid simple date +value if they are present, eg a \f[C]date:\f[] tag with no value is not +allowed. +.PP +Ledger's earlier, more compact bracketed date syntax is also supported: +\f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[]. +hledger will attempt to parse any square\-bracketed sequence of the +\f[C]0123456789/\-.=\f[] characters in this way. +With this syntax, DATE infers its year from the transaction and DATE2 +infers its year from DATE. +.SS Status +.PP +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: +.PP +.TS +tab(@); +l l. +T{ +mark \ +T}@T{ +status +T} +_ +T{ +\ +T}@T{ +unmarked +T} +T{ +\f[C]!\f[] +T}@T{ +pending +T} +T{ +\f[C]*\f[] +T}@T{ +cleared +T} +.TE +.PP +When reporting, you can filter by status with the +\f[C]\-U/\-\-unmarked\f[], \f[C]\-P/\-\-pending\f[], and +\f[C]\-C/\-\-cleared\f[] flags; or the \f[C]status:\f[], +\f[C]status:!\f[], and \f[C]status:*\f[] queries; or the U, P, C keys in +hledger\-ui. +.PP +Note, in Ledger and in older versions of hledger, the \[lq]unmarked\[rq] +state is called \[lq]uncleared\[rq]. +As of hledger 1.3 we have renamed it to unmarked for clarity. +.PP +To replicate Ledger and old hledger's behaviour of also matching +pending, combine \-U and \-P. +.PP +Status marks are optional, but can be helpful eg for reconciling with +real\-world accounts. +Some editor modes provide highlighting and shortcuts for working with +status. +Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c +C\-e, or posting status with C\-c C\-c. +.PP +What \[lq]uncleared\[rq], \[lq]pending\[rq], and \[lq]cleared\[rq] +actually mean is up to you. +Here's one suggestion: +.PP +.TS +tab(@); +lw(9.9n) lw(60.1n). +T{ +status +T}@T{ +meaning +T} +_ +T{ +uncleared +T}@T{ +recorded but not yet reconciled; needs review +T} +T{ +pending +T}@T{ +tentatively reconciled (if needed, eg during a big reconciliation) +T} +T{ +cleared +T}@T{ +complete, reconciled as far as possible, and considered correct +T} +.TE +.PP +With this scheme, you would use \f[C]\-PC\f[] to see the current balance +at your bank, \f[C]\-U\f[] to see things which will probably hit your +bank soon (like uncashed checks), and no flags to see the most +up\-to\-date state of your finances. +.SS Description +.PP +A transaction's description is the rest of the line following the date +and status mark (or until a comment begins). +Sometimes called the \[lq]narration\[rq] in traditional bookkeeping, it +can be used for whatever you wish, or left blank. +Transaction descriptions can be queried, unlike comments. +.SS Payee and note +.PP +You can optionally include a \f[C]|\f[] (pipe) character in a +description to subdivide it into a payee/payer name on the left and +additional notes on the right. +This may be worthwhile if you need to do more precise querying and +pivoting by payee. +.SS Account names +.PP +Account names typically have several parts separated by a full colon, +from which hledger derives a hierarchical chart of accounts. +They can be anything you like, but in finance there are traditionally +five top\-level accounts: \f[C]assets\f[], \f[C]liabilities\f[], +\f[C]income\f[], \f[C]expenses\f[], and \f[C]equity\f[]. +.PP +Account names may contain single spaces, eg: +\f[C]assets:accounts\ receivable\f[]. +Because of this, they must always be followed by \f[B]two or more +spaces\f[] (or newline). +.PP +Account names can be aliased. +.SS Amounts +.PP +After the account name, there is usually an amount. +Important: between account name and amount, there must be \f[B]two or +more spaces\f[]. +.PP +Amounts consist of a number and (usually) a currency symbol or commodity +name. +Some examples: +.PP +\f[C]2.00001\f[] +.PD 0 +.P +.PD +\f[C]$1\f[] +.PD 0 +.P +.PD +\f[C]4000\ AAPL\f[] +.PD 0 +.P +.PD +\f[C]3\ "green\ apples"\f[] +.PD 0 +.P +.PD +\f[C]\-$1,000,000.00\f[] +.PD 0 +.P +.PD +\f[C]INR\ 9,99,99,999.00\f[] +.PD 0 +.P +.PD +\f[C]EUR\ \-2.000.000,00\f[] +.PD 0 +.P +.PD +\f[C]1\ 999\ 999.9455\f[] +.PD 0 +.P +.PD +\f[C]EUR\ 1E3\f[] +.PD 0 +.P +.PD +\f[C]1000E\-6s\f[] +.PP +As you can see, the amount format is somewhat flexible: +.IP \[bu] 2 +amounts are a number (the \[lq]quantity\[rq]) and optionally a currency +symbol/commodity name (the \[lq]commodity\[rq]). +.IP \[bu] 2 +the commodity is a symbol, word, or phrase, on the left or right, with +or without a separating space. +If the commodity contains numbers, spaces or non\-word punctuation it +must be enclosed in double quotes. +.IP \[bu] 2 +negative amounts with a commodity on the left can have the minus sign +before or after it +.IP \[bu] 2 +digit groups (thousands, or any other grouping) can be separated by +space or comma or period and should be used as separator between all +groups +.IP \[bu] 2 +decimal part can be separated by comma or period and should be different +from digit groups separator +.IP \[bu] 2 +scientific E\-notation is allowed. +Be careful not to use a digit group separator character in scientific +notation, as it's not supported and it might get mistaken for a decimal +point. +(Declaring the digit group separator character explicitly with a +commodity directive will prevent this.) +.PP +You can use any of these variations when recording data. +However, there is some ambiguous way of representing numbers like +\f[C]$1.000\f[] and \f[C]$1,000\f[] both may mean either one thousand or +one dollar. +By default hledger will assume that this is sole delimiter is used only +for decimals. +On the other hand commodity format declared prior to that line will help +to resolve that ambiguity differently: +.IP +.nf +\f[C] +commodity\ $1,000.00 + +2017/12/25\ New\ life\ of\ Scrooge +\ \ \ \ expenses:gifts\ \ $1,000 +\ \ \ \ assets +\f[] +.fi +.PP +Though journal may contain mixed styles to represent amount, when +hledger displays amounts, it will choose a consistent format for each +commodity. +(Except for price amounts, which are always formatted as written). +The display format is chosen as follows: +.IP \[bu] 2 +if there is a commodity directive specifying the format, that is used +.IP \[bu] 2 +otherwise the format is inferred from the first posting amount in that +commodity in the journal, and the precision (number of decimal places) +will be the maximum from all posting amounts in that commmodity +.IP \[bu] 2 +or if there are no such amounts in the journal, a default format is used +(like \f[C]$1000.00\f[]). +.PP +Price amounts and amounts in D directives usually don't affect amount +format inference, but in some situations they can do so indirectly. +(Eg when D's default commodity is applied to a commodity\-less amount, +or when an amountless posting is balanced using a price's commodity, or +when \-V is used.) If you find this causing problems, set the desired +format with a commodity directive. +.SS Virtual Postings +.PP +When you parenthesise the account name in a posting, we call that a +\f[I]virtual posting\f[], which means: +.IP \[bu] 2 +it is ignored when checking that the transaction is balanced +.IP \[bu] 2 +it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used, +or the \f[C]real:1\f[] query. +.PP +You could use this, eg, to set an account's opening balance without +needing to use the \f[C]equity:opening\ balances\f[] account: +.IP +.nf +\f[C] +1/1\ special\ unbalanced\ posting\ to\ set\ initial\ balance +\ \ (assets:checking)\ \ \ $1000 +\f[] +.fi +.PP +When the account name is bracketed, we call it a \f[I]balanced virtual +posting\f[]. +This is like an ordinary virtual posting except the balanced virtual +postings in a transaction must balance to 0, like the real postings (but +separately from them). +Balanced virtual postings are also excluded by \f[C]\-\-real/\-R\f[] or +\f[C]real:1\f[]. +.IP +.nf +\f[C] +1/1\ buy\ food\ with\ cash,\ and\ update\ some\ budget\-tracking\ subaccounts\ elsewhere +\ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10 +\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10 +\ \ [assets:checking:available]\ \ \ \ \ $10 +\ \ [assets:checking:budget:food]\ \ $\-10 +\f[] +.fi +.PP +Virtual postings have some legitimate uses, but those are few. +You can usually find an equivalent journal entry using real postings, +which is more correct and provides better error checking. +.SS Balance Assertions +.PP +hledger supports Ledger\-style balance assertions in journal files. +These look like \f[C]=EXPECTEDBALANCE\f[] following a posting's amount. +Eg in this example we assert the expected dollar balance in accounts a +and b after each posting: +.IP +.nf +\f[C] +2013/1/1 +\ \ a\ \ \ $1\ \ =$1 +\ \ b\ \ \ \ \ \ \ =$\-1 + +2013/1/2 +\ \ a\ \ \ $1\ \ =$2 +\ \ b\ \ $\-1\ \ =$\-2 +\f[] +.fi +.PP +After reading a journal file, hledger will check all balance assertions +and report an error if any of them fail. +Balance assertions can protect you from, eg, inadvertently disrupting +reconciled balances while cleaning up old entries. +You can disable them temporarily with the +\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for +troubleshooting or for reading Ledger files. +.SS Assertions and ordering +.PP +hledger sorts an account's postings and assertions first by date and +then (for postings on the same day) by parse order. +Note this is different from Ledger, which sorts assertions only by parse +order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) +.PP +So, hledger balance assertions keep working if you reorder +differently\-dated transactions within the journal. +But if you reorder same\-dated transactions or postings, assertions +might break and require updating. +This order dependence does bring an advantage: precise control over the +order of postings and assertions within a day, so you can assert +intra\-day balances. +.SS Assertions and included files +.PP +With included files, things are a little more complicated. +Including preserves the ordering of postings and assertions. +If you have multiple postings to an account on the same day, split +across different files, and you also want to assert the account's +balance on the same day, you'll have to put the assertion in the right +file. +.SS Assertions and multiple \-f options +.PP +Balance assertions don't work well across files specified with multiple +\-f options. +Use include or concatenate the files instead. +.SS Assertions and commodities +.PP +The asserted balance must be a simple single\-commodity amount, and in +fact the assertion checks only this commodity's balance within the +(possibly multi\-commodity) account balance. +We could call this a partial balance assertion. +This is compatible with Ledger, and makes it possible to make assertions +about accounts containing multiple commodities. +.PP +To assert each commodity's balance in such a multi\-commodity account, +you can add multiple postings (with amount 0 if necessary). +But note that no matter how many assertions you add, you can't be sure +the account does not contain some unexpected commodity. +(We'll add support for this kind of total balance assertion if there's +demand.) +.SS Assertions and subaccounts +.PP +Balance assertions do not count the balance from subaccounts; they check +the posted account's exclusive balance. +For example: +.IP +.nf +\f[C] +1/1 +\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1 +\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1 +\ \ equity +\f[] +.fi +.PP +The balance report's flat mode shows these exclusive balances more +clearly: +.IP +.nf +\f[C] +$\ hledger\ bal\ checking\ \-\-flat +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2 +\f[] +.fi +.SS Assertions and virtual postings +.PP +Balance assertions are checked against all postings, both real and +virtual. +They are not affected by the \f[C]\-\-real/\-R\f[] flag or +\f[C]real:\f[] query. +.SS Balance Assignments +.PP +Ledger\-style balance assignments are also supported. +These are like balance assertions, but with no posting amount on the +left side of the equals sign; instead it is calculated automatically so +as to satisfy the assertion. +This can be a convenience during data entry, eg when setting opening +balances: +.IP +.nf +\f[C] +;\ starting\ a\ new\ journal,\ set\ asset\ account\ balances\ +2016/1/1\ opening\ balances +\ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ =\ $409.32 +\ \ assets:savings\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $735.24 +\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ =\ $42 +\ \ equity:opening\ balances +\f[] +.fi +.PP +or when adjusting a balance to reality: +.IP +.nf +\f[C] +;\ no\ cash\ left;\ update\ balance,\ record\ any\ untracked\ spending\ as\ a\ generic\ expense +2016/1/15 +\ \ assets:cash\ \ \ \ =\ $0 +\ \ expenses:misc +\f[] +.fi +.PP +The calculated amount depends on the account's balance in the commodity +at that point (which depends on the previously\-dated postings of the +commodity to that account since the last balance assertion or +assignment). +Note that using balance assignments makes your journal a little less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. +.SS Prices +.SS Transaction prices +.PP +Within a transaction, you can note an amount's price in another +commodity. +This can be used to document the cost (in a purchase) or selling price +(in a sale). +For example, transaction prices are useful to record purchases of a +foreign currency. +.PP +Transaction prices are fixed, and do not change over time. +(Ledger users: Ledger uses a different syntax for fixed prices, +\f[C]{=UNITPRICE}\f[], which hledger currently ignores). +.PP +There are several ways to record a transaction price: +.IP "1." 3 +Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each +\ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00 +\f[] +.fi +.RE +.IP "2." 3 +Write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot +\ \ assets:dollars +\f[] +.fi +.RE +.IP "3." 3 +Specify amounts for all postings, using exactly two commodities, and let +hledger infer the price that balances the transaction: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased +\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135 +\f[] +.fi +.RE +.PP +Amounts with transaction prices can be displayed in the transaction +price's commodity by using the \f[C]\-B/\-\-cost\f[] flag (except for +#551) (\[lq]B\[rq] is from \[lq]cost Basis\[rq]). +Eg for the above, here is how \-B affects the balance report: +.IP +.nf +\f[C] +$\ hledger\ bal\ \-N\ \-\-flat +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +$\ hledger\ bal\ \-N\ \-\-flat\ \-B +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost +\f[] +.fi +.PP +Note \-B is sensitive to the order of postings when a transaction price +is inferred: the inferred price will be in the commodity of the last +amount. +So if example 3's postings are reversed, while the transaction is +equivalent, \-B shows something different: +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ 135\ dollars\ sold +\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ for\ 100\ euros +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ bal\ \-N\ \-\-flat\ \-B +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €\-100\ \ assets:dollars\ \ #\ <\-\ the\ dollars\[aq]\ selling\ price +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros +\f[] +.fi +.SS Market prices +.PP +Market prices are not tied to a particular transaction; they represent +historical exchange rates between two commodities. +(Ledger calls them historical prices.) For example, the prices published +by a stock exchange or the foreign exchange market. +hledger can use these prices to show the market value of things at a +given date, see market value. +.PP +To record market prices, use P directives in the main journal or in an +included file. +Their format is: +.IP +.nf +\f[C] +P\ DATE\ COMMODITYBEINGPRICED\ UNITPRICE +\f[] +.fi +.PP +DATE is a simple date as usual. +COMMODITYBEINGPRICED is the symbol of the commodity being priced. +UNITPRICE is an ordinary amount (symbol and quantity) in a second +commodity, specifying the unit price or conversion rate for the first +commodity in terms of the second, on the given date. +.PP +For example, the following directives say that one euro was worth 1.35 +US dollars during 2009, and $1.40 from 2010 onward: +.IP +.nf +\f[C] +P\ 2009/1/1\ €\ $1.35 +P\ 2010/1/1\ €\ $1.40 +\f[] +.fi +.SS Comments +.PP +Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash +(\f[C]#\f[]) or star (\f[C]*\f[]) are comments, and will be ignored. +(Star comments cause org\-mode nodes to be ignored, allowing emacs users +to fold and navigate their journals with org\-mode or orgstruct\-mode.) +.PP +Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[] +directives is a (multi\-line) comment. +If there is no \f[C]end\ comment\f[], the comment extends to the end of +the file. +.PP +You can attach comments to a transaction by writing them after the +description and/or indented on the following lines (before the +postings). +Similarly, you can attach comments to an individual posting by writing +them after the amount and/or indented on the following lines. +Transaction and posting comments must begin with a semicolon +(\f[C];\f[]). +.PP +Some examples: +.IP +.nf +\f[C] +#\ a\ file\ comment + +;\ also\ a\ file\ comment + +comment +This\ is\ a\ multiline\ file\ comment, +which\ continues\ until\ a\ line +where\ the\ "end\ comment"\ string +appears\ on\ its\ own\ (or\ end\ of\ file). +end\ comment + +2012/5/14\ something\ \ ;\ a\ transaction\ comment +\ \ \ \ ;\ the\ transaction\ comment,\ continued +\ \ \ \ posting1\ \ 1\ \ ;\ a\ comment\ for\ posting\ 1 +\ \ \ \ posting2 +\ \ \ \ ;\ a\ comment\ for\ posting\ 2 +\ \ \ \ ;\ another\ comment\ line\ for\ posting\ 2 +;\ a\ file\ comment\ (because\ not\ indented) +\f[] +.fi +.SS Tags +.PP +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. +.PP +A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: +.IP +.nf +\f[C] +2017/1/16\ bought\ groceries\ \ \ \ ;\ sometag: +\f[] +.fi +.PP +Tags can have a value, which is the text after the colon, up to the next +comma or end of line, with leading/trailing whitespace removed: +.IP +.nf +\f[C] +\ \ \ \ expenses:food\ \ \ \ $10\ \ \ ;\ a\-posting\-tag:\ the\ tag\ value +\f[] +.fi +.PP +Note this means hledger's tag values can not contain commas or newlines. +Ending at commas means you can write multiple short tags on one line, +comma separated: +.IP +.nf +\f[C] +\ \ \ \ assets:checking\ \ \ \ \ \ \ ;\ a\ comment\ containing\ tag1:,\ tag2:\ some\ value\ ... +\f[] +.fi +.PP +Here, +.IP \[bu] 2 +\[lq]\f[C]a\ comment\ containing\f[]\[rq] is just comment text, not a +tag +.IP \[bu] 2 +\[lq]\f[C]tag1\f[]\[rq] is a tag with no value +.IP \[bu] 2 +\[lq]\f[C]tag2\f[]\[rq] is another tag, whose value is +\[lq]\f[C]some\ value\ ...\f[]\[rq] +.PP +Tags in a transaction comment affect the transaction and all of its +postings, while tags in a posting comment affect only that posting. +For example, the following transaction has three tags (\f[C]A\f[], +\f[C]TAG2\f[], \f[C]third\-tag\f[]) and the posting has four (those plus +\f[C]posting\-tag\f[]): +.IP +.nf +\f[C] +1/1\ a\ transaction\ \ ;\ A:,\ TAG2: +\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ <\-\ with\ a\ value +\ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag: +\f[] +.fi +.PP +Tags are like Ledger's metadata feature, except hledger's tag values are +simple strings. +.SS Directives +.SS Account aliases +.PP +You can define aliases which rewrite your account names (after reading +the journal, before generating reports). +hledger's account aliases can be useful for: +.IP \[bu] 2 +expanding shorthand account names to their full form, allowing easier +data entry and a less verbose journal +.IP \[bu] 2 +adapting old journals to your current chart of accounts +.IP \[bu] 2 +experimenting with new account organisations, like a new hierarchy or +combining two accounts into one +.IP \[bu] 2 +customising reports +.PP +See also Cookbook: rewrite account names. +.SS Basic aliases +.PP +To set an account alias, use the \f[C]alias\f[] directive in your +journal file. +This affects all subsequent journal entries in the current file or its +included files. +The spaces around the = are optional: +.IP +.nf +\f[C] +alias\ OLD\ =\ NEW +\f[] +.fi +.PP +Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the +command line. +This affects all entries. +It's useful for trying out aliases interactively. +.PP +OLD and NEW are full account names. +hledger will replace any occurrence of the old account name with the new +one. +Subaccounts are also affected. +Eg: +.IP +.nf +\f[C] +alias\ checking\ =\ assets:bank:wells\ fargo:checking +#\ rewrites\ "checking"\ to\ "assets:bank:wells\ fargo:checking",\ or\ "checking:a"\ to\ "assets:bank:wells\ fargo:checking:a" +\f[] +.fi +.SS Regex aliases +.PP +There is also a more powerful variant that uses a regular expression, +indicated by the forward slashes: +.IP +.nf +\f[C] +alias\ /REGEX/\ =\ REPLACEMENT +\f[] +.fi +.PP +or \f[C]\-\-alias\ \[aq]/REGEX/=REPLACEMENT\[aq]\f[]. +.PP +REGEX is a case\-insensitive regular expression. +Anywhere it matches inside an account name, the matched part will be +replaced by REPLACEMENT. +If REGEX contains parenthesised match groups, these can be referenced by +the usual numeric backreferences in REPLACEMENT. +Eg: +.IP +.nf +\f[C] +alias\ /^(.+):bank:([^:]+)(.*)/\ =\ \\1:\\2\ \\3 +#\ rewrites\ "assets:bank:wells\ fargo:checking"\ to\ \ "assets:wells\ fargo\ checking" +\f[] +.fi +.PP +Also note that REPLACEMENT continues to the end of line (or on command +line, to end of option argument), so it can contain trailing whitespace. +.SS Multiple aliases +.PP +You can define as many aliases as you like using directives or +command\-line options. +Aliases are recursive \- each alias sees the result of applying previous +ones. +(This is different from Ledger, where aliases are non\-recursive by +default). +Aliases are applied in the following order: +.IP "1." 3 +alias directives, most recently seen first (recent directives take +precedence over earlier ones; directives not yet seen are ignored) +.IP "2." 3 +alias options, in the order they appear on the command line +.SS end aliases +.PP +You can clear (forget) all currently defined aliases with the +\f[C]end\ aliases\f[] directive: +.IP +.nf +\f[C] +end\ aliases +\f[] +.fi +.SS account directive +.PP +The \f[C]account\f[] directive predeclares account names. +The simplest form is \f[C]account\ ACCTNAME\f[], eg: +.IP +.nf +\f[C] +account\ assets:bank:checking +\f[] +.fi +.PP +Currently this mainly helps with account name autocompletion in eg +hledger add, hledger\-iadd, hledger\-web, and ledger\-mode. +.PD 0 +.P +.PD +In future it will also help detect misspelled accounts. +.PP +Account names can be followed by a numeric account code: +.IP +.nf +\f[C] +account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000 +account\ assets:bank:checking\ \ \ \ 1110 +account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000 +account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000 +account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000 +\f[] +.fi +.PP +This affects account display order in reports: accounts with codes are +listed before accounts without codes, in increasing code order. +(Otherwise, accounts are listed alphabetically.) Account codes should be +all numeric digits, unique, and separated from the account name by at +least two spaces (since account names may contain single spaces). +By convention, often the first digit indicates the type of account, as +in this numbering scheme and the example above. +In future, we might use this to recognize account types. +.PP +An account directive can also have indented subdirectives following it, +which are currently ignored. +Here is the full syntax: +.IP +.nf +\f[C] +;\ account\ ACCTNAME\ \ [OPTIONALCODE] +;\ \ \ [OPTIONALSUBDIRECTIVES] + +account\ assets:bank:checking\ \ \ 1110 +\ \ a\ comment +\ \ some\-tag:12345 +\f[] +.fi +.SS apply account directive +.PP +You can specify a parent account which will be prepended to all accounts +within a section of the journal. +Use the \f[C]apply\ account\f[] and \f[C]end\ apply\ account\f[] +directives like so: +.IP +.nf +\f[C] +apply\ account\ home + +2010/1/1 +\ \ \ \ food\ \ \ \ $10 +\ \ \ \ cash + +end\ apply\ account +\f[] +.fi +.PP +which is equivalent to: +.IP +.nf +\f[C] +2010/01/01 +\ \ \ \ home:food\ \ \ \ \ \ \ \ \ \ \ $10 +\ \ \ \ home:cash\ \ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.PP +If \f[C]end\ apply\ account\f[] is omitted, the effect lasts to the end +of the file. +Included files are also affected, eg: +.IP +.nf +\f[C] +apply\ account\ business +include\ biz.journal +end\ apply\ account +apply\ account\ personal +include\ personal.journal +\f[] +.fi +.PP +Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings +were also supported. +.SS Multi\-line comments +.PP +A line containing just \f[C]comment\f[] starts a multi\-line comment, +and a line containing just \f[C]end\ comment\f[] ends it. +See comments. +.SS commodity directive +.PP +The \f[C]commodity\f[] directive predefines commodities (currently this +is just informational), and also it may define the display format for +amounts in this commodity (overriding the automatically inferred +format). +.PP +It may be written on a single line, like this: +.IP +.nf +\f[C] +;\ commodity\ EXAMPLEAMOUNT + +;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated, +;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and +;\ separating\ thousands\ with\ comma. +commodity\ 1,000.0000\ AAAA +\f[] +.fi +.PP +or on multiple lines, using the \[lq]format\[rq] subdirective. +In this case the commodity symbol appears twice and should be the same +in both places: +.IP +.nf +\f[C] +;\ commodity\ SYMBOL +;\ \ \ format\ EXAMPLEAMOUNT + +;\ display\ indian\ rupees\ with\ currency\ name\ on\ the\ left, +;\ thousands,\ lakhs\ and\ crores\ comma\-separated, +;\ period\ as\ decimal\ point,\ and\ two\ decimal\ places. +commodity\ INR +\ \ format\ INR\ 9,99,99,999.00 +\f[] +.fi +.SS Default commodity +.PP +The D directive sets a default commodity (and display format), to be +used for amounts without a commodity symbol (ie, plain numbers). +(Note this differs from Ledger's default commodity directive.) The +commodity and display format will be applied to all subsequent +commodity\-less amounts, or until the next D directive. +.IP +.nf +\f[C] +#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars +#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places) +D\ $1,000.00 + +1/1 +\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1 +\ \ b +\f[] +.fi +.SS Default year +.PP +You can set a default year to be used for subsequent dates which don't +specify a year. +This is a line beginning with \f[C]Y\f[] followed by the year. +Eg: +.IP +.nf +\f[C] +Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009 + +12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15 +\ \ expenses\ \ 1 +\ \ assets + +Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010 + +2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected +\ \ expenses\ \ 1 +\ \ assets + +1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31 +\ \ expenses\ \ 1 +\ \ assets +\f[] +.fi +.SS Including other files +.PP +You can pull in the content of additional journal files by writing an +include directive, like this: +.IP +.nf +\f[C] +include\ path/to/file.journal +\f[] +.fi +.PP +If the path does not begin with a slash, it is relative to the current +file. +Glob patterns (\f[C]*\f[]) are not currently supported. +.PP +The \f[C]include\f[] directive can only be used in journal files. +It can include journal, timeclock or timedot files, but not CSV files. +.SH Periodic transactions +.PP +Periodic transactions are a kind of rule with a dual purpose: they can +specify recurring future transactions (with \f[C]\-\-forecast\f[]), or +budget goals (with \f[C]\-\-budget\f[]). +They look a bit like a transaction, except the first line is a tilde +(\f[C]~\f[]) followed by a period expression: +.IP +.nf +\f[C] +~\ weekly +\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck +\ \ income:acme\ inc +\f[] +.fi +.PP +With \f[C]\-\-forecast\f[], each periodic transaction rule generates +recurring \[lq]forecast\[rq] transactions at the specified interval, +beginning the day after the latest recorded journal transaction (or +today, if there are no transactions) and ending 6 months from today (or +at the report end date, if specified). +.PP +With \f[C]balance\ \-\-budget\f[], each periodic transaction declares +recurring budget goals for the specified accounts. +Eg the example above declares the goal of receiving $400 from +\f[C]income:acme\ inc\f[] (and also, depositing $400 into +\f[C]assets:bank:checking\f[]) every week. +.PP +For more details, see: balance: Budgeting and Budgeting and Forecasting. +.SH Automated postings +.PP +Automated postings are postings added automatically by rule to certain +transactions (with \f[C]\-\-auto\f[]). +An automated posting rule looks like a transaction where the first line +is an equal sign (\f[C]=\f[]) followed by a query: +.IP +.nf +\f[C] +=\ expenses:gifts +\ \ \ \ budget:gifts\ \ *\-1 +\ \ \ \ assets:budget\ \ *1 +\f[] +.fi +.PP +The posting amounts can be of the form \f[C]*N\f[], which means \[lq]the +amount of the matched transaction's first posting, multiplied by N\[rq]. +They can also be ordinary fixed amounts. +Fixed amounts with no commodity symbol will be given the same commodity +as the matched transaction's first posting. +.PP +This example adds a corresponding (unbalanced) budget posting to every +transaction involving the \f[C]expenses:gifts\f[] account: +.IP +.nf +\f[C] +=\ expenses:gifts +\ \ \ \ (budget:gifts)\ \ *\-1 + +2017\-12\-14 +\ \ expenses:gifts\ \ $20 +\ \ assets +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ print\ \-\-auto +2017/12/14 +\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20 +\ \ \ \ assets +\ \ \ \ (budget:gifts)\ \ \ \ \ \ \ \ \ \ \ \ $\-20 +\f[] +.fi +.SH EDITOR SUPPORT +.PP +Add\-on modes exist for various text editors, to make working with +journal files easier. +They add colour, navigation aids and helpful commands. +For hledger users who edit the journal file directly (the majority), +using one of these modes is quite recommended. +.PP +These were written with Ledger in mind, but also work with hledger +files: +.PP +.TS +tab(@); +lw(12.2n) lw(57.8n). +T{ +Editor +T}@T{ +T} +_ +T{ +Emacs +T}@T{ +http://www.ledger\-cli.org/3.0/doc/ledger\-mode.html +T} +T{ +Vim +T}@T{ +https://github.com/ledger/ledger/wiki/Getting\-started +T} +T{ +Sublime Text +T}@T{ +https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-Sublime\-Text\-or\-RubyMine +T} +T{ +Textmate +T}@T{ +https://github.com/ledger/ledger/wiki/Using\-TextMate\-2 +T} +T{ +Text Wrangler \ +T}@T{ +https://github.com/ledger/ledger/wiki/Editing\-Ledger\-files\-with\-TextWrangler +T} +T{ +Visual Studio Code +T}@T{ +https://marketplace.visualstudio.com/items?itemName=mark\-hansen.hledger\-vscode +T} +.TE + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger_journal.info b/embeddedfiles/hledger_journal.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_journal.info @@ -0,0 +1,1270 @@ +This is hledger_journal.info, produced by makeinfo version 6.5 from +stdin. + + +File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) + +hledger_journal(5) hledger 1.9 +****************************** + +hledger's usual data source is a plain text file containing journal +entries in hledger journal format. This file represents a standard +accounting general journal. I use file names ending in '.journal', but +that's not required. The journal file contains a number of transaction +entries, each describing a transfer of money (or any commodity) between +two or more named accounts, in a simple format readable by both hledger +and humans. + + hledger's journal format is a compatible subset, mostly, of ledger's +journal format, so hledger can work with compatible ledger journal files +as well. It's safe, and encouraged, to run both hledger and ledger on +the same journal file, eg to validate the results you're getting. + + You can use hledger without learning any more about this file; just +use the add or web commands to create and update it. Many users, +though, also edit the journal file directly with a text editor, perhaps +assisted by the helper modes for emacs or vim. + + Here's an example: + +; A sample journal file. This is a comment. + +2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description + assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name + income:salary $-1 ; followed by at least two spaces and an amount + +2008/06/01 gift + assets:bank:checking $1 ; <- at least two postings in a transaction + income:gifts $-1 ; <- their amounts must balance to 0 + +2008/06/02 save + assets:bank:saving $1 + assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred + +2008/06/03 eat & shop ; <- description can be anything + expenses:food $1 + expenses:supplies $1 ; <- this transaction debits two expense accounts + assets:cash ; <- $-2 inferred + +2008/10/01 take a loan + assets:bank:checking $1 + liabilities:debts $-1 + +2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) + liabilities:debts $1 + assets:bank:checking + +* Menu: + +* FILE FORMAT:: +* Periodic transactions:: +* Automated postings:: +* EDITOR SUPPORT:: + + +File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top + +1 FILE FORMAT +************* + +* Menu: + +* Transactions:: +* Postings:: +* Dates:: +* Status:: +* Description:: +* Account names:: +* Amounts:: +* Virtual Postings:: +* Balance Assertions:: +* Balance Assignments:: +* Prices:: +* Comments:: +* Tags:: +* Directives:: + + +File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT + +1.1 Transactions +================ + +Transactions are movements of some quantity of commodities between named +accounts. Each transaction is represented by a journal entry beginning +with a simple date in column 0. This can be followed by any of the +following, separated by spaces: + + * (optional) a status character (empty, '!', or '*') + * (optional) a transaction code (any short number or text, enclosed + in parentheses) + * (optional) a transaction description (any remaining text until end + of line or a semicolon) + * (optional) a transaction comment (any remaining text following a + semicolon until end of line) + + Then comes zero or more (but usually at least 2) indented lines +representing... + + +File: hledger_journal.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT + +1.2 Postings +============ + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + * (optional) a status character (empty, '!', or '*'), followed by a + space + * (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + * (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, one amount may be left blank; it will be inferred so as to +balance the transaction. + + Be sure to note the unusual two-space delimiter between account name +and amount. This makes it easy to write account names containing +spaces. But if you accidentally leave only one space (or tab) before +the amount, the amount will be considered part of the account name. + + +File: hledger_journal.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT + +1.3 Dates +========= + +* Menu: + +* Simple dates:: +* Secondary dates:: +* Posting dates:: + + +File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: Dates + +1.3.1 Simple dates +------------------ + +Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) +Leading zeros are optional. The year may be omitted, in which case it +will be inferred from the context - the current transaction, the default +year set with a default year directive, or the current date when the +command is run. Some examples: '2010/01/31', '1/31', '2010-01-31', +'2010.1.31'. + + +File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates + +1.3.2 Secondary dates +--------------------- + +Real-life transactions sometimes involve more than one date - eg the +date you write a cheque, and the date it clears in your bank. When you +want to model this, eg for more accurate balances, you can specify +individual posting dates, which I recommend. Or, you can use the +secondary dates (aka auxiliary/effective dates) feature, supported for +compatibility with Ledger. + + A secondary date can be written after the primary date, separated by +an equals sign. The primary date, on the left, is used by default; the +secondary date, on the right, is used when the '--date2' flag is +specified ('--aux-date' or '--effective' also work). + + The meaning of secondary dates is up to you, but it's best to follow +a consistent rule. Eg write the bank's clearing date as primary, and +when needed, the date the transaction was initiated as secondary. + + Here's an example. Note that a secondary date will use the year of +the primary date if unspecified. + +2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + +$ hledger register checking +2010/02/23 movie ticket assets:checking $-10 $-10 + +$ hledger register checking --date2 +2010/02/19 movie ticket assets:checking $-10 $-10 + + Secondary dates require some effort; you must use them consistently +in your journal entries and remember whether to use or not use the +'--date2' flag for your reports. They are included in hledger for +Ledger compatibility, but posting dates are a more powerful and less +confusing alternative. + + +File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: Dates + +1.3.3 Posting dates +------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like 'date:DATE'. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015/05/30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015/06/01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction's date. You can set the secondary date +similarly, with 'date2:DATE2'. The 'date:' or 'date2:' tags must have a +valid simple date value if they are present, eg a 'date:' tag with no +value is not allowed. + + Ledger's earlier, more compact bracketed date syntax is also +supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'. hledger will attempt +to parse any square-bracketed sequence of the '0123456789/-.=' +characters in this way. With this syntax, DATE infers its year from the +transaction and DATE2 infers its year from DATE. + + +File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: FILE FORMAT + +1.4 Status +========== + +Transactions, or individual postings within a transaction, can have a +status mark, which is a single character before the transaction +description or posting account name, separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +'!' pending +'*' cleared + + When reporting, you can filter by status with the '-U/--unmarked', +'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!', +and 'status:*' queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" +state is called "uncleared". As of hledger 1.3 we have renamed it to +unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching +pending, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here's one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use '-PC' to see the current balance at +your bank, '-U' to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger_journal.info, Node: Description, Next: Account names, Prev: Status, Up: FILE FORMAT + +1.5 Description +=============== + +A transaction's description is the rest of the line following the date +and status mark (or until a comment begins). Sometimes called the +"narration" in traditional bookkeeping, it can be used for whatever you +wish, or left blank. Transaction descriptions can be queried, unlike +comments. +* Menu: + +* Payee and note:: + + +File: hledger_journal.info, Node: Payee and note, Up: Description + +1.5.1 Payee and note +-------------------- + +You can optionally include a '|' (pipe) character in a description to +subdivide it into a payee/payer name on the left and additional notes on +the right. This may be worthwhile if you need to do more precise +querying and pivoting by payee. + + +File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT + +1.6 Account names +================= + +Account names typically have several parts separated by a full colon, +from which hledger derives a hierarchical chart of accounts. They can +be anything you like, but in finance there are traditionally five +top-level accounts: 'assets', 'liabilities', 'income', 'expenses', and +'equity'. + + Account names may contain single spaces, eg: 'assets:accounts +receivable'. Because of this, they must always be followed by *two or +more spaces* (or newline). + + Account names can be aliased. + + +File: hledger_journal.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT + +1.7 Amounts +=========== + +After the account name, there is usually an amount. Important: between +account name and amount, there must be *two or more spaces*. + + Amounts consist of a number and (usually) a currency symbol or +commodity name. Some examples: + + '2.00001' +'$1' +'4000 AAPL' +'3 "green apples"' +'-$1,000,000.00' +'INR 9,99,99,999.00' +'EUR -2.000.000,00' +'1 999 999.9455' +'EUR 1E3' +'1000E-6s' + + As you can see, the amount format is somewhat flexible: + + * amounts are a number (the "quantity") and optionally a currency + symbol/commodity name (the "commodity"). + * the commodity is a symbol, word, or phrase, on the left or right, + with or without a separating space. If the commodity contains + numbers, spaces or non-word punctuation it must be enclosed in + double quotes. + * negative amounts with a commodity on the left can have the minus + sign before or after it + * digit groups (thousands, or any other grouping) can be separated by + space or comma or period and should be used as separator between + all groups + * decimal part can be separated by comma or period and should be + different from digit groups separator + * scientific E-notation is allowed. Be careful not to use a digit + group separator character in scientific notation, as it's not + supported and it might get mistaken for a decimal point. + (Declaring the digit group separator character explicitly with a + commodity directive will prevent this.) + + You can use any of these variations when recording data. However, +there is some ambiguous way of representing numbers like '$1.000' and +'$1,000' both may mean either one thousand or one dollar. By default +hledger will assume that this is sole delimiter is used only for +decimals. On the other hand commodity format declared prior to that +line will help to resolve that ambiguity differently: + +commodity $1,000.00 + +2017/12/25 New life of Scrooge + expenses:gifts $1,000 + assets + + Though journal may contain mixed styles to represent amount, when +hledger displays amounts, it will choose a consistent format for each +commodity. (Except for price amounts, which are always formatted as +written). The display format is chosen as follows: + + * if there is a commodity directive specifying the format, that is + used + * otherwise the format is inferred from the first posting amount in + that commodity in the journal, and the precision (number of decimal + places) will be the maximum from all posting amounts in that + commmodity + * or if there are no such amounts in the journal, a default format is + used (like '$1000.00'). + + Price amounts and amounts in D directives usually don't affect amount +format inference, but in some situations they can do so indirectly. (Eg +when D's default commodity is applied to a commodity-less amount, or +when an amountless posting is balanced using a price's commodity, or +when -V is used.) If you find this causing problems, set the desired +format with a commodity directive. + + +File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT + +1.8 Virtual Postings +==================== + +When you parenthesise the account name in a posting, we call that a +_virtual posting_, which means: + + * it is ignored when checking that the transaction is balanced + * it is excluded from reports when the '--real/-R' flag is used, or + the 'real:1' query. + + You could use this, eg, to set an account's opening balance without +needing to use the 'equity:opening balances' account: + +1/1 special unbalanced posting to set initial balance + (assets:checking) $1000 + + When the account name is bracketed, we call it a _balanced virtual +posting_. This is like an ordinary virtual posting except the balanced +virtual postings in a transaction must balance to 0, like the real +postings (but separately from them). Balanced virtual postings are also +excluded by '--real/-R' or 'real:1'. + +1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere + expenses:food $10 + assets:cash $-10 + [assets:checking:available] $10 + [assets:checking:budget:food] $-10 + + Virtual postings have some legitimate uses, but those are few. You +can usually find an equivalent journal entry using real postings, which +is more correct and provides better error checking. + + +File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT + +1.9 Balance Assertions +====================== + +hledger supports Ledger-style balance assertions in journal files. +These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in +this example we assert the expected dollar balance in accounts a and b +after each posting: + +2013/1/1 + a $1 =$1 + b =$-1 + +2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the '--ignore-assertions' flag, which can be useful for troubleshooting +or for reading Ledger files. +* Menu: + +* Assertions and ordering:: +* Assertions and included files:: +* Assertions and multiple -f options:: +* Assertions and commodities:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: + + +File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions + +1.9.1 Assertions and ordering +----------------------------- + +hledger sorts an account's postings and assertions first by date and +then (for postings on the same day) by parse order. Note this is +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder +differently-dated transactions within the journal. But if you reorder +same-dated transactions or postings, assertions might break and require +updating. This order dependence does bring an advantage: precise +control over the order of postings and assertions within a day, so you +can assert intra-day balances. + + +File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions + +1.9.2 Assertions and included files +----------------------------------- + +With included files, things are a little more complicated. Including +preserves the ordering of postings and assertions. If you have multiple +postings to an account on the same day, split across different files, +and you also want to assert the account's balance on the same day, +you'll have to put the assertion in the right file. + + +File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions + +1.9.3 Assertions and multiple -f options +---------------------------------------- + +Balance assertions don't work well across files specified with multiple +-f options. Use include or concatenate the files instead. + + +File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and multiple -f options, Up: Balance Assertions + +1.9.4 Assertions and commodities +-------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity's balance within the +(possibly multi-commodity) account balance. We could call this a +partial balance assertion. This is compatible with Ledger, and makes it +possible to make assertions about accounts containing multiple +commodities. + + To assert each commodity's balance in such a multi-commodity account, +you can add multiple postings (with amount 0 if necessary). But note +that no matter how many assertions you add, you can't be sure the +account does not contain some unexpected commodity. (We'll add support +for this kind of total balance assertion if there's demand.) + + +File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions + +1.9.5 Assertions and subaccounts +-------------------------------- + +Balance assertions do not count the balance from subaccounts; they check +the posted account's exclusive balance. For example: + +1/1 + checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 + checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 + equity + + The balance report's flat mode shows these exclusive balances more +clearly: + +$ hledger bal checking --flat + 1 checking + 1 checking:fund +-------------------- + 2 + + +File: hledger_journal.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions + +1.9.6 Assertions and virtual postings +------------------------------------- + +Balance assertions are checked against all postings, both real and +virtual. They are not affected by the '--real/-R' flag or 'real:' +query. + + +File: hledger_journal.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT + +1.10 Balance Assignments +======================== + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). Note that using balance assignments makes your journal a +little less explicit; to know the exact amount posted, you have to run +hledger or do the calculations yourself, instead of just reading it. + + +File: hledger_journal.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT + +1.11 Prices +=========== + +* Menu: + +* Transaction prices:: +* Market prices:: + + +File: hledger_journal.info, Node: Transaction prices, Next: Market prices, Up: Prices + +1.11.1 Transaction prices +------------------------- + +Within a transaction, you can note an amount's price in another +commodity. This can be used to document the cost (in a purchase) or +selling price (in a sale). For example, transaction prices are useful +to record purchases of a foreign currency. + + Transaction prices are fixed, and do not change over time. (Ledger +users: Ledger uses a different syntax for fixed prices, '{=UNITPRICE}', +which hledger currently ignores). + + There are several ways to record a transaction price: + + 1. Write the price per unit, as '@ UNITPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as '@@ TOTALPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts with transaction prices can be displayed in the transaction +price's commodity by using the '-B/--cost' flag (except for #551) ("B" +is from "cost Basis"). Eg for the above, here is how -B affects the +balance report: + +$ hledger bal -N --flat + $-135 assets:dollars + €100 assets:euros +$ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction +price is inferred: the inferred price will be in the commodity of the +last amount. So if example 3's postings are reversed, while the +transaction is equivalent, -B shows something different: + +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros €100 ; for 100 euros + +$ hledger bal -N --flat -B + €-100 assets:dollars # <- the dollars' selling price + €100 assets:euros + + +File: hledger_journal.info, Node: Market prices, Prev: Transaction prices, Up: Prices + +1.11.2 Market prices +-------------------- + +Market prices are not tied to a particular transaction; they represent +historical exchange rates between two commodities. (Ledger calls them +historical prices.) For example, the prices published by a stock +exchange or the foreign exchange market. hledger can use these prices +to show the market value of things at a given date, see market value. + + To record market prices, use P directives in the main journal or in +an included file. Their format is: + +P DATE COMMODITYBEINGPRICED UNITPRICE + + DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol +of the commodity being priced. UNITPRICE is an ordinary amount (symbol +and quantity) in a second commodity, specifying the unit price or +conversion rate for the first commodity in terms of the second, on the +given date. + + For example, the following directives say that one euro was worth +1.35 US dollars during 2009, and $1.40 from 2010 onward: + +P 2009/1/1 € $1.35 +P 2010/1/1 € $1.40 + + +File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT + +1.12 Comments +============= + +Lines in the journal beginning with a semicolon (';') or hash ('#') or +star ('*') are comments, and will be ignored. (Star comments cause +org-mode nodes to be ignored, allowing emacs users to fold and navigate +their journals with org-mode or orgstruct-mode.) + + Also, anything between 'comment' and 'end comment' directives is a +(multi-line) comment. If there is no 'end comment', the comment extends +to the end of the file. + + You can attach comments to a transaction by writing them after the +description and/or indented on the following lines (before the +postings). Similarly, you can attach comments to an individual posting +by writing them after the amount and/or indented on the following lines. +Transaction and posting comments must begin with a semicolon (';'). + + Some examples: + +# a file comment + +; also a file comment + +comment +This is a multiline file comment, +which continues until a line +where the "end comment" string +appears on its own (or end of file). +end comment + +2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 +; a file comment (because not indented) + + +File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT + +1.13 Tags +========= + +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: + +2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the +next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or +newlines. Ending at commas means you can write multiple short tags on +one line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + * "'a comment containing'" is just comment text, not a tag + * "'tag1'" is a tag with no value + * "'tag2'" is another tag, whose value is "'some value ...'" + + Tags in a transaction comment affect the transaction and all of its +postings, while tags in a posting comment affect only that posting. For +example, the following transaction has three tags ('A', 'TAG2', +'third-tag') and the posting has four (those plus 'posting-tag'): + +1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values +are simple strings. + + +File: hledger_journal.info, Node: Directives, Prev: Tags, Up: FILE FORMAT + +1.14 Directives +=============== + +* Menu: + +* Account aliases:: +* account directive:: +* apply account directive:: +* Multi-line comments:: +* commodity directive:: +* Default commodity:: +* Default year:: +* Including other files:: + + +File: hledger_journal.info, Node: Account aliases, Next: account directive, Up: Directives + +1.14.1 Account aliases +---------------------- + +You can define aliases which rewrite your account names (after reading +the journal, before generating reports). hledger's account aliases can +be useful for: + + * expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + * adapting old journals to your current chart of accounts + * experimenting with new account organisations, like a new hierarchy + or combining two accounts into one + * customising reports + + See also Cookbook: rewrite account names. +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Multiple aliases:: +* end aliases:: + + +File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases + +1.14.1.1 Basic aliases +...................... + +To set an account alias, use the 'alias' directive in your journal file. +This affects all subsequent journal entries in the current file or its +included files. The spaces around the = are optional: + +alias OLD = NEW + + Or, you can use the '--alias 'OLD=NEW'' option on the command line. +This affects all entries. It's useful for trying out aliases +interactively. + + OLD and NEW are full account names. hledger will replace any +occurrence of the old account name with the new one. Subaccounts are +also affected. Eg: + +alias checking = assets:bank:wells fargo:checking +# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + +File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases + +1.14.1.2 Regex aliases +...................... + +There is also a more powerful variant that uses a regular expression, +indicated by the forward slashes: + +alias /REGEX/ = REPLACEMENT + + or '--alias '/REGEX/=REPLACEMENT''. + + REGEX is a case-insensitive regular expression. Anywhere it matches +inside an account name, the matched part will be replaced by +REPLACEMENT. If REGEX contains parenthesised match groups, these can be +referenced by the usual numeric backreferences in REPLACEMENT. Eg: + +alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 +# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + Also note that REPLACEMENT continues to the end of line (or on +command line, to end of option argument), so it can contain trailing +whitespace. + + +File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases + +1.14.1.3 Multiple aliases +......................... + +You can define as many aliases as you like using directives or +command-line options. Aliases are recursive - each alias sees the +result of applying previous ones. (This is different from Ledger, where +aliases are non-recursive by default). Aliases are applied in the +following order: + + 1. alias directives, most recently seen first (recent directives take + precedence over earlier ones; directives not yet seen are ignored) + 2. alias options, in the order they appear on the command line + + +File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases + +1.14.1.4 end aliases +.................... + +You can clear (forget) all currently defined aliases with the 'end +aliases' directive: + +end aliases + + +File: hledger_journal.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives + +1.14.2 account directive +------------------------ + +The 'account' directive predeclares account names. The simplest form is +'account ACCTNAME', eg: + +account assets:bank:checking + + Currently this mainly helps with account name autocompletion in eg +hledger add, hledger-iadd, hledger-web, and ledger-mode. +In future it will also help detect misspelled accounts. + + Account names can be followed by a numeric account code: + +account assets 1000 +account assets:bank:checking 1110 +account liabilities 2000 +account revenues 4000 +account expenses 6000 + + This affects account display order in reports: accounts with codes +are listed before accounts without codes, in increasing code order. +(Otherwise, accounts are listed alphabetically.) Account codes should +be all numeric digits, unique, and separated from the account name by at +least two spaces (since account names may contain single spaces). By +convention, often the first digit indicates the type of account, as in +this numbering scheme and the example above. In future, we might use +this to recognize account types. + + An account directive can also have indented subdirectives following +it, which are currently ignored. Here is the full syntax: + +; account ACCTNAME [OPTIONALCODE] +; [OPTIONALSUBDIRECTIVES] + +account assets:bank:checking 1110 + a comment + some-tag:12345 + + +File: hledger_journal.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives + +1.14.3 apply account directive +------------------------------ + +You can specify a parent account which will be prepended to all accounts +within a section of the journal. Use the 'apply account' and 'end apply +account' directives like so: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + which is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + If 'end apply account' is omitted, the effect lasts to the end of the +file. Included files are also affected, eg: + +apply account business +include biz.journal +end apply account +apply account personal +include personal.journal + + Prior to hledger 1.0, legacy 'account' and 'end' spellings were also +supported. + + +File: hledger_journal.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives + +1.14.4 Multi-line comments +-------------------------- + +A line containing just 'comment' starts a multi-line comment, and a line +containing just 'end comment' ends it. See comments. + + +File: hledger_journal.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives + +1.14.5 commodity directive +-------------------------- + +The 'commodity' directive predefines commodities (currently this is just +informational), and also it may define the display format for amounts in +this commodity (overriding the automatically inferred format). + + It may be written on a single line, like this: + +; commodity EXAMPLEAMOUNT + +; display AAAA amounts with the symbol on the right, space-separated, +; using period as decimal point, with four decimal places, and +; separating thousands with comma. +commodity 1,000.0000 AAAA + + or on multiple lines, using the "format" subdirective. In this case +the commodity symbol appears twice and should be the same in both +places: + +; commodity SYMBOL +; format EXAMPLEAMOUNT + +; display indian rupees with currency name on the left, +; thousands, lakhs and crores comma-separated, +; period as decimal point, and two decimal places. +commodity INR + format INR 9,99,99,999.00 + + +File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives + +1.14.6 Default commodity +------------------------ + +The D directive sets a default commodity (and display format), to be +used for amounts without a commodity symbol (ie, plain numbers). (Note +this differs from Ledger's default commodity directive.) The commodity +and display format will be applied to all subsequent commodity-less +amounts, or until the next D directive. + +# commodity-less amounts should be treated as dollars +# (and displayed with symbol on the left, thousands separators and two decimal places) +D $1,000.00 + +1/1 + a 5 ; <- commodity-less amount, becomes $1 + b + + +File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives + +1.14.7 Default year +------------------- + +You can set a default year to be used for subsequent dates which don't +specify a year. This is a line beginning with 'Y' followed by the year. +Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +Y2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + +File: hledger_journal.info, Node: Including other files, Prev: Default year, Up: Directives + +1.14.8 Including other files +---------------------------- + +You can pull in the content of additional journal files by writing an +include directive, like this: + +include path/to/file.journal + + If the path does not begin with a slash, it is relative to the +current file. Glob patterns ('*') are not currently supported. + + The 'include' directive can only be used in journal files. It can +include journal, timeclock or timedot files, but not CSV files. + + +File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: FILE FORMAT, Up: Top + +2 Periodic transactions +*********************** + +Periodic transactions are a kind of rule with a dual purpose: they can +specify recurring future transactions (with '--forecast'), or budget +goals (with '--budget'). They look a bit like a transaction, except the +first line is a tilde ('~') followed by a period expression: + +~ weekly + assets:bank:checking $400 ; paycheck + income:acme inc + + With '--forecast', each periodic transaction rule generates recurring +"forecast" transactions at the specified interval, beginning the day +after the latest recorded journal transaction (or today, if there are no +transactions) and ending 6 months from today (or at the report end date, +if specified). + + With 'balance --budget', each periodic transaction declares recurring +budget goals for the specified accounts. Eg the example above declares +the goal of receiving $400 from 'income:acme inc' (and also, depositing +$400 into 'assets:bank:checking') every week. + + For more details, see: balance: Budgeting and Budgeting and +Forecasting. + + +File: hledger_journal.info, Node: Automated postings, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top + +3 Automated postings +******************** + +Automated postings are postings added automatically by rule to certain +transactions (with '--auto'). An automated posting rule looks like a +transaction where the first line is an equal sign ('=') followed by a +query: + += expenses:gifts + budget:gifts *-1 + assets:budget *1 + + The posting amounts can be of the form '*N', which means "the amount +of the matched transaction's first posting, multiplied by N". They can +also be ordinary fixed amounts. Fixed amounts with no commodity symbol +will be given the same commodity as the matched transaction's first +posting. + + This example adds a corresponding (unbalanced) budget posting to +every transaction involving the 'expenses:gifts' account: + += expenses:gifts + (budget:gifts) *-1 + +2017-12-14 + expenses:gifts $20 + assets + +$ hledger print --auto +2017/12/14 + expenses:gifts $20 + assets + (budget:gifts) $-20 + + +File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated postings, Up: Top + +4 EDITOR SUPPORT +**************** + +Add-on modes exist for various text editors, to make working with +journal files easier. They add colour, navigation aids and helpful +commands. For hledger users who edit the journal file directly (the +majority), using one of these modes is quite recommended. + + These were written with Ledger in mind, but also work with hledger +files: + +Editor +-------------------------------------------------------------------------- +Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html +Vim https://github.com/ledger/ledger/wiki/Getting-started +Sublime https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-Sublime-Text-or-RubyMine +Text +Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 +Text https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-TextWrangler +Wrangler +Visual https://marketplace.visualstudio.com/items?itemName=mark-hansen.hledger-vscode +Studio +Code + + +Tag Table: +Node: Top76 +Node: FILE FORMAT2419 +Ref: #file-format2550 +Node: Transactions2773 +Ref: #transactions2894 +Node: Postings3578 +Ref: #postings3705 +Node: Dates4700 +Ref: #dates4815 +Node: Simple dates4880 +Ref: #simple-dates5006 +Node: Secondary dates5372 +Ref: #secondary-dates5526 +Node: Posting dates7089 +Ref: #posting-dates7218 +Node: Status8592 +Ref: #status8712 +Node: Description10420 +Ref: #description10558 +Node: Payee and note10877 +Ref: #payee-and-note10991 +Node: Account names11233 +Ref: #account-names11376 +Node: Amounts11863 +Ref: #amounts11999 +Node: Virtual Postings15014 +Ref: #virtual-postings15173 +Node: Balance Assertions16393 +Ref: #balance-assertions16568 +Node: Assertions and ordering17464 +Ref: #assertions-and-ordering17650 +Node: Assertions and included files18350 +Ref: #assertions-and-included-files18591 +Node: Assertions and multiple -f options18924 +Ref: #assertions-and-multiple--f-options19178 +Node: Assertions and commodities19310 +Ref: #assertions-and-commodities19545 +Node: Assertions and subaccounts20241 +Ref: #assertions-and-subaccounts20473 +Node: Assertions and virtual postings20994 +Ref: #assertions-and-virtual-postings21201 +Node: Balance Assignments21343 +Ref: #balance-assignments21512 +Node: Prices22632 +Ref: #prices22765 +Node: Transaction prices22816 +Ref: #transaction-prices22961 +Node: Market prices25117 +Ref: #market-prices25252 +Node: Comments26212 +Ref: #comments26334 +Node: Tags27576 +Ref: #tags27694 +Node: Directives29096 +Ref: #directives29209 +Node: Account aliases29402 +Ref: #account-aliases29546 +Node: Basic aliases30150 +Ref: #basic-aliases30293 +Node: Regex aliases30983 +Ref: #regex-aliases31151 +Node: Multiple aliases31869 +Ref: #multiple-aliases32041 +Node: end aliases32539 +Ref: #end-aliases32679 +Node: account directive32780 +Ref: #account-directive32960 +Node: apply account directive34307 +Ref: #apply-account-directive34503 +Node: Multi-line comments35162 +Ref: #multi-line-comments35352 +Node: commodity directive35480 +Ref: #commodity-directive35664 +Node: Default commodity36536 +Ref: #default-commodity36709 +Node: Default year37246 +Ref: #default-year37411 +Node: Including other files37834 +Ref: #including-other-files37991 +Node: Periodic transactions38388 +Ref: #periodic-transactions38554 +Node: Automated postings39543 +Ref: #automated-postings39706 +Node: EDITOR SUPPORT40608 +Ref: #editor-support40733 + +End Tag Table diff --git a/embeddedfiles/hledger_journal.txt b/embeddedfiles/hledger_journal.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_journal.txt @@ -0,0 +1,950 @@ + +hledger_journal(5) hledger User Manuals hledger_journal(5) + + + +NAME + Journal - hledger's default file format, representing a General Journal + +DESCRIPTION + hledger's usual data source is a plain text file containing journal + entries in hledger journal format. This file represents a standard + accounting general journal. I use file names ending in .journal, but + that's not required. The journal file contains a number of transaction + entries, each describing a transfer of money (or any commodity) between + two or more named accounts, in a simple format readable by both hledger + and humans. + + hledger's journal format is a compatible subset, mostly, of ledger's + journal format, so hledger can work with compatible ledger journal + files as well. It's safe, and encouraged, to run both hledger and + ledger on the same journal file, eg to validate the results you're get- + ting. + + You can use hledger without learning any more about this file; just use + the add or web commands to create and update it. Many users, though, + also edit the journal file directly with a text editor, perhaps + assisted by the helper modes for emacs or vim. + + Here's an example: + + ; A sample journal file. This is a comment. + + 2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description + assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name + income:salary $-1 ; followed by at least two spaces and an amount + + 2008/06/01 gift + assets:bank:checking $1 ; <- at least two postings in a transaction + income:gifts $-1 ; <- their amounts must balance to 0 + + 2008/06/02 save + assets:bank:saving $1 + assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred + + 2008/06/03 eat & shop ; <- description can be anything + expenses:food $1 + expenses:supplies $1 ; <- this transaction debits two expense accounts + assets:cash ; <- $-2 inferred + + 2008/10/01 take a loan + assets:bank:checking $1 + liabilities:debts $-1 + + 2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) + liabilities:debts $1 + assets:bank:checking + +FILE FORMAT + Transactions + Transactions are movements of some quantity of commodities between + named accounts. Each transaction is represented by a journal entry + beginning with a simple date in column 0. This can be followed by any + of the following, separated by spaces: + + o (optional) a status character (empty, !, or *) + + o (optional) a transaction code (any short number or text, enclosed in + parentheses) + + o (optional) a transaction description (any remaining text until end of + line or a semicolon) + + o (optional) a transaction comment (any remaining text following a + semicolon until end of line) + + Then comes zero or more (but usually at least 2) indented lines repre- + senting... + + Postings + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or + tab (2 or 4 spaces is common), followed by: + + o (optional) a status character (empty, !, or *), followed by a space + + o (required) an account name (any text, optionally containing single + spaces, until end of line or a double space) + + o (optional) two or more spaces or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are + being removed. + + The amounts within a transaction must always sum up to zero. As a con- + venience, one amount may be left blank; it will be inferred so as to + balance the transaction. + + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the + amount, the amount will be considered part of the account name. + + Dates + Simple dates + Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) + Leading zeros are optional. The year may be omitted, in which case it + will be inferred from the context - the current transaction, the + default year set with a default year directive, or the current date + when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, + 2010.1.31. + + Secondary dates + Real-life transactions sometimes involve more than one date - eg the + date you write a cheque, and the date it clears in your bank. When you + want to model this, eg for more accurate balances, you can specify + individual posting dates, which I recommend. Or, you can use the sec- + ondary dates (aka auxiliary/effective dates) feature, supported for + compatibility with Ledger. + + A secondary date can be written after the primary date, separated by an + equals sign. The primary date, on the left, is used by default; the + secondary date, on the right, is used when the --date2 flag is speci- + fied (--aux-date or --effective also work). + + The meaning of secondary dates is up to you, but it's best to follow a + consistent rule. Eg write the bank's clearing date as primary, and + when needed, the date the transaction was initiated as secondary. + + Here's an example. Note that a secondary date will use the year of the + primary date if unspecified. + + 2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + + $ hledger register checking + 2010/02/23 movie ticket assets:checking $-10 $-10 + + $ hledger register checking --date2 + 2010/02/19 movie ticket assets:checking $-10 $-10 + + Secondary dates require some effort; you must use them consistently in + your journal entries and remember whether to use or not use the --date2 + flag for your reports. They are included in hledger for Ledger compat- + ibility, but posting dates are a more powerful and less confusing + alternative. + + Posting dates + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) + like date:DATE. This is probably the best way to control posting dates + precisely. Eg in this example the expense should appear in May + reports, and the deduction from checking should be reported on 6/1 for + easy bank reconciliation: + + 2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + + $ hledger -f t.j register food + 2015/05/30 expenses:food $10 $10 + + $ hledger -f t.j register checking + 2015/06/01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will use + the year of the transaction's date. You can set the secondary date + similarly, with date2:DATE2. The date: or date2: tags must have a + valid simple date value if they are present, eg a date: tag with no + value is not allowed. + + Ledger's earlier, more compact bracketed date syntax is also supported: + [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any + square-bracketed sequence of the 0123456789/-.= characters in this way. + With this syntax, DATE infers its year from the transaction and DATE2 + infers its year from DATE. + + Status + Transactions, or individual postings within a transaction, can have a + status mark, which is a single character before the transaction + description or posting account name, separated from it by a space, + indicating one of three statuses: + + + mark status + ------------------ + unmarked + ! pending + * cleared + + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags; or the status:, status:!, and + status:* queries; or the U, P, C keys in hledger-ui. + + Note, in Ledger and in older versions of hledger, the "unmarked" state + is called "uncleared". As of hledger 1.3 we have renamed it to + unmarked for clarity. + + To replicate Ledger and old hledger's behaviour of also matching pend- + ing, combine -U and -P. + + Status marks are optional, but can be helpful eg for reconciling with + real-world accounts. Some editor modes provide highlighting and short- + cuts for working with status. Eg in Emacs ledger-mode, you can toggle + transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to you. + Here's one suggestion: + + + status meaning + -------------------------------------------------------------------------- + uncleared recorded but not yet reconciled; needs review + pending tentatively reconciled (if needed, eg during a big reconcil- + iation) + cleared complete, reconciled as far as possible, and considered cor- + rect + + With this scheme, you would use -PC to see the current balance at your + bank, -U to see things which will probably hit your bank soon (like + uncashed checks), and no flags to see the most up-to-date state of your + finances. + + Description + A transaction's description is the rest of the line following the date + and status mark (or until a comment begins). Sometimes called the + "narration" in traditional bookkeeping, it can be used for whatever you + wish, or left blank. Transaction descriptions can be queried, unlike + comments. + + Payee and note + You can optionally include a | (pipe) character in a description to + subdivide it into a payee/payer name on the left and additional notes + on the right. This may be worthwhile if you need to do more precise + querying and pivoting by payee. + + Account names + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five + top-level accounts: assets, liabilities, income, expenses, and equity. + + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more + spaces (or newline). + + Account names can be aliased. + + Amounts + After the account name, there is usually an amount. Important: between + account name and amount, there must be two or more spaces. + + Amounts consist of a number and (usually) a currency symbol or commod- + ity name. Some examples: + + 2.00001 + $1 + 4000 AAPL + 3 "green apples" + -$1,000,000.00 + INR 9,99,99,999.00 + EUR -2.000.000,00 + 1 999 999.9455 + EUR 1E3 + 1000E-6s + + As you can see, the amount format is somewhat flexible: + + o amounts are a number (the "quantity") and optionally a currency sym- + bol/commodity name (the "commodity"). + + o the commodity is a symbol, word, or phrase, on the left or right, + with or without a separating space. If the commodity contains num- + bers, spaces or non-word punctuation it must be enclosed in double + quotes. + + o negative amounts with a commodity on the left can have the minus sign + before or after it + + o digit groups (thousands, or any other grouping) can be separated by + space or comma or period and should be used as separator between all + groups + + o decimal part can be separated by comma or period and should be dif- + ferent from digit groups separator + + o scientific E-notation is allowed. Be careful not to use a digit + group separator character in scientific notation, as it's not sup- + ported and it might get mistaken for a decimal point. (Declaring the + digit group separator character explicitly with a commodity directive + will prevent this.) + + You can use any of these variations when recording data. However, + there is some ambiguous way of representing numbers like $1.000 and + $1,000 both may mean either one thousand or one dollar. By default + hledger will assume that this is sole delimiter is used only for deci- + mals. On the other hand commodity format declared prior to that line + will help to resolve that ambiguity differently: + + commodity $1,000.00 + + 2017/12/25 New life of Scrooge + expenses:gifts $1,000 + assets + + Though journal may contain mixed styles to represent amount, when + hledger displays amounts, it will choose a consistent format for each + commodity. (Except for price amounts, which are always formatted as + written). The display format is chosen as follows: + + o if there is a commodity directive specifying the format, that is used + + o otherwise the format is inferred from the first posting amount in + that commodity in the journal, and the precision (number of decimal + places) will be the maximum from all posting amounts in that commmod- + ity + + o or if there are no such amounts in the journal, a default format is + used (like $1000.00). + + Price amounts and amounts in D directives usually don't affect amount + format inference, but in some situations they can do so indirectly. + (Eg when D's default commodity is applied to a commodity-less amount, + or when an amountless posting is balanced using a price's commodity, or + when -V is used.) If you find this causing problems, set the desired + format with a commodity directive. + + Virtual Postings + When you parenthesise the account name in a posting, we call that a + virtual posting, which means: + + o it is ignored when checking that the transaction is balanced + + o it is excluded from reports when the --real/-R flag is used, or the + real:1 query. + + You could use this, eg, to set an account's opening balance without + needing to use the equity:opening balances account: + + 1/1 special unbalanced posting to set initial balance + (assets:checking) $1000 + + When the account name is bracketed, we call it a balanced virtual post- + ing. This is like an ordinary virtual posting except the balanced vir- + tual postings in a transaction must balance to 0, like the real post- + ings (but separately from them). Balanced virtual postings are also + excluded by --real/-R or real:1. + + 1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere + expenses:food $10 + assets:cash $-10 + [assets:checking:available] $10 + [assets:checking:budget:food] $-10 + + Virtual postings have some legitimate uses, but those are few. You can + usually find an equivalent journal entry using real postings, which is + more correct and provides better error checking. + + Balance Assertions + hledger supports Ledger-style balance assertions in journal files. + These look like =EXPECTEDBALANCE following a posting's amount. Eg in + this example we assert the expected dollar balance in accounts a and b + after each posting: + + 2013/1/1 + a $1 =$1 + b =$-1 + + 2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance assertions + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the + --ignore-assertions flag, which can be useful for troubleshooting or + for reading Ledger files. + + Assertions and ordering + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- + ferent from Ledger, which sorts assertions only by parse order. (Also, + Ledger assertions do not see the accumulated effect of repeated post- + ings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder differ- + ently-dated transactions within the journal. But if you reorder + same-dated transactions or postings, assertions might break and require + updating. This order dependence does bring an advantage: precise con- + trol over the order of postings and assertions within a day, so you can + assert intra-day balances. + + Assertions and included files + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + ple postings to an account on the same day, split across different + files, and you also want to assert the account's balance on the same + day, you'll have to put the assertion in the right file. + + Assertions and multiple -f options + Balance assertions don't work well across files specified with multiple + -f options. Use include or concatenate the files instead. + + Assertions and commodities + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the + (possibly multi-commodity) account balance. We could call this a par- + tial balance assertion. This is compatible with Ledger, and makes it + possible to make assertions about accounts containing multiple commodi- + ties. + + To assert each commodity's balance in such a multi-commodity account, + you can add multiple postings (with amount 0 if necessary). But note + that no matter how many assertions you add, you can't be sure the + account does not contain some unexpected commodity. (We'll add support + for this kind of total balance assertion if there's demand.) + + Assertions and subaccounts + Balance assertions do not count the balance from subaccounts; they + check the posted account's exclusive balance. For example: + + 1/1 + checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 + checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 + equity + + The balance report's flat mode shows these exclusive balances more + clearly: + + $ hledger bal checking --flat + 1 checking + 1 checking:fund + -------------------- + 2 + + Assertions and virtual postings + Balance assertions are checked against all postings, both real and vir- + tual. They are not affected by the --real/-R flag or real: query. + + Balance Assignments + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when + setting opening balances: + + ; starting a new journal, set asset account balances + 2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + + ; no cash left; update balance, record any untracked spending as a generic expense + 2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the commodity + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- + ment). Note that using balance assignments makes your journal a little + less explicit; to know the exact amount posted, you have to run hledger + or do the calculations yourself, instead of just reading it. + + Prices + Transaction prices + Within a transaction, you can note an amount's price in another commod- + ity. This can be used to document the cost (in a purchase) or selling + price (in a sale). For example, transaction prices are useful to + record purchases of a foreign currency. + + Transaction prices are fixed, and do not change over time. (Ledger + users: Ledger uses a different syntax for fixed prices, {=UNITPRICE}, + which hledger currently ignores). + + There are several ways to record a transaction price: + + 1. Write the price per unit, as @ UNITPRICE after the amount: + + 2009/1/1 + assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as @@ TOTALPRICE after the amount: + + 2009/1/1 + assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros 100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts with transaction prices can be displayed in the transaction + price's commodity by using the -B/--cost flag (except for #551) ("B" is + from "cost Basis"). Eg for the above, here is how -B affects the bal- + ance report: + + $ hledger bal -N --flat + $-135 assets:dollars + 100 assets:euros + $ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last + amount. So if example 3's postings are reversed, while the transaction + is equivalent, -B shows something different: + + 2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros 100 ; for 100 euros + + $ hledger bal -N --flat -B + -100 assets:dollars # <- the dollars' selling price + 100 assets:euros + + Market prices + Market prices are not tied to a particular transaction; they represent + historical exchange rates between two commodities. (Ledger calls them + historical prices.) For example, the prices published by a stock + exchange or the foreign exchange market. hledger can use these prices + to show the market value of things at a given date, see market value. + + To record market prices, use P directives in the main journal or in an + included file. Their format is: + + P DATE COMMODITYBEINGPRICED UNITPRICE + + DATE is a simple date as usual. COMMODITYBEINGPRICED is the symbol of + the commodity being priced. UNITPRICE is an ordinary amount (symbol + and quantity) in a second commodity, specifying the unit price or con- + version rate for the first commodity in terms of the second, on the + given date. + + For example, the following directives say that one euro was worth 1.35 + US dollars during 2009, and $1.40 from 2010 onward: + + P 2009/1/1 $1.35 + P 2010/1/1 $1.40 + + Comments + Lines in the journal beginning with a semicolon (;) or hash (#) or star + (*) are comments, and will be ignored. (Star comments cause org-mode + nodes to be ignored, allowing emacs users to fold and navigate their + journals with org-mode or orgstruct-mode.) + + Also, anything between comment and end comment directives is a + (multi-line) comment. If there is no end comment, the comment extends + to the end of the file. + + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. + Transaction and posting comments must begin with a semicolon (;). + + Some examples: + + # a file comment + + ; also a file comment + + comment + This is a multiline file comment, + which continues until a line + where the "end comment" string + appears on its own (or end of file). + end comment + + 2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 + ; a file comment (because not indented) + + Tags + Tags are a way to add extra labels or labelled data to postings and + transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full + colon, written inside a transaction or posting comment line: + + 2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the + next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or new- + lines. Ending at commas means you can write multiple short tags on one + line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + o "a comment containing" is just comment text, not a tag + + o "tag1" is a tag with no value + + o "tag2" is another tag, whose value is "some value ..." + + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, + third-tag) and the posting has four (those plus posting-tag): + + 1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values + are simple strings. + + Directives + Account aliases + You can define aliases which rewrite your account names (after reading + the journal, before generating reports). hledger's account aliases can + be useful for: + + o expanding shorthand account names to their full form, allowing easier + data entry and a less verbose journal + + o adapting old journals to your current chart of accounts + + o experimenting with new account organisations, like a new hierarchy or + combining two accounts into one + + o customising reports + + See also Cookbook: rewrite account names. + + Basic aliases + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its + included files. The spaces around the = are optional: + + alias OLD = NEW + + Or, you can use the --alias 'OLD=NEW' option on the command line. This + affects all entries. It's useful for trying out aliases interactively. + + OLD and NEW are full account names. hledger will replace any occur- + rence of the old account name with the new one. Subaccounts are also + affected. Eg: + + alias checking = assets:bank:wells fargo:checking + # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + Regex aliases + There is also a more powerful variant that uses a regular expression, + indicated by the forward slashes: + + alias /REGEX/ = REPLACEMENT + + or --alias '/REGEX/=REPLACEMENT'. + + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- + erenced by the usual numeric backreferences in REPLACEMENT. Eg: + + alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 + # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + Also note that REPLACEMENT continues to the end of line (or on command + line, to end of option argument), so it can contain trailing white- + space. + + Multiple aliases + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where + aliases are non-recursive by default). Aliases are applied in the fol- + lowing order: + + 1. alias directives, most recently seen first (recent directives take + precedence over earlier ones; directives not yet seen are ignored) + + 2. alias options, in the order they appear on the command line + + end aliases + You can clear (forget) all currently defined aliases with the + end aliases directive: + + end aliases + + account directive + The account directive predeclares account names. The simplest form is + account ACCTNAME, eg: + + account assets:bank:checking + + Currently this mainly helps with account name autocompletion in eg + hledger add, hledger-iadd, hledger-web, and ledger-mode. + In future it will also help detect misspelled accounts. + + Account names can be followed by a numeric account code: + + account assets 1000 + account assets:bank:checking 1110 + account liabilities 2000 + account revenues 4000 + account expenses 6000 + + This affects account display order in reports: accounts with codes are + listed before accounts without codes, in increasing code order. (Oth- + erwise, accounts are listed alphabetically.) Account codes should be + all numeric digits, unique, and separated from the account name by at + least two spaces (since account names may contain single spaces). By + convention, often the first digit indicates the type of account, as in + this numbering scheme and the example above. In future, we might use + this to recognize account types. + + An account directive can also have indented subdirectives following it, + which are currently ignored. Here is the full syntax: + + ; account ACCTNAME [OPTIONALCODE] + ; [OPTIONALSUBDIRECTIVES] + + account assets:bank:checking 1110 + a comment + some-tag:12345 + + apply account directive + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and + end apply account directives like so: + + apply account home + + 2010/1/1 + food $10 + cash + + end apply account + + which is equivalent to: + + 2010/01/01 + home:food $10 + home:cash $-10 + + If end apply account is omitted, the effect lasts to the end of the + file. Included files are also affected, eg: + + apply account business + include biz.journal + end apply account + apply account personal + include personal.journal + + Prior to hledger 1.0, legacy account and end spellings were also sup- + ported. + + Multi-line comments + A line containing just comment starts a multi-line comment, and a line + containing just end comment ends it. See comments. + + commodity directive + The commodity directive predefines commodities (currently this is just + informational), and also it may define the display format for amounts + in this commodity (overriding the automatically inferred format). + + It may be written on a single line, like this: + + ; commodity EXAMPLEAMOUNT + + ; display AAAA amounts with the symbol on the right, space-separated, + ; using period as decimal point, with four decimal places, and + ; separating thousands with comma. + commodity 1,000.0000 AAAA + + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both + places: + + ; commodity SYMBOL + ; format EXAMPLEAMOUNT + + ; display indian rupees with currency name on the left, + ; thousands, lakhs and crores comma-separated, + ; period as decimal point, and two decimal places. + commodity INR + format INR 9,99,99,999.00 + + Default commodity + The D directive sets a default commodity (and display format), to be + used for amounts without a commodity symbol (ie, plain numbers). (Note + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less + amounts, or until the next D directive. + + # commodity-less amounts should be treated as dollars + # (and displayed with symbol on the left, thousands separators and two decimal places) + D $1,000.00 + + 1/1 + a 5 ; <- commodity-less amount, becomes $1 + b + + Default year + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. + Eg: + + Y2009 ; set default year to 2009 + + 12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + + Y2010 ; change default year to 2010 + + 2009/1/30 ; specifies the year, not affected + expenses 1 + assets + + 1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Including other files + You can pull in the content of additional journal files by writing an + include directive, like this: + + include path/to/file.journal + + If the path does not begin with a slash, it is relative to the current + file. Glob patterns (*) are not currently supported. + + The include directive can only be used in journal files. It can + include journal, timeclock or timedot files, but not CSV files. + +Periodic transactions + Periodic transactions are a kind of rule with a dual purpose: they can + specify recurring future transactions (with --forecast), or budget + goals (with --budget). They look a bit like a transaction, except the + first line is a tilde (~) followed by a period expression: + + ~ weekly + assets:bank:checking $400 ; paycheck + income:acme inc + + With --forecast, each periodic transaction rule generates recurring + "forecast" transactions at the specified interval, beginning the day + after the latest recorded journal transaction (or today, if there are + no transactions) and ending 6 months from today (or at the report end + date, if specified). + + With balance --budget, each periodic transaction declares recurring + budget goals for the specified accounts. Eg the example above declares + the goal of receiving $400 from income:acme inc (and also, depositing + $400 into assets:bank:checking) every week. + + For more details, see: balance: Budgeting and Budgeting and Forecast- + ing. + +Automated postings + Automated postings are postings added automatically by rule to certain + transactions (with --auto). An automated posting rule looks like a + transaction where the first line is an equal sign (=) followed by a + query: + + = expenses:gifts + budget:gifts *-1 + assets:budget *1 + + The posting amounts can be of the form *N, which means "the amount of + the matched transaction's first posting, multiplied by N". They can + also be ordinary fixed amounts. Fixed amounts with no commodity symbol + will be given the same commodity as the matched transaction's first + posting. + + This example adds a corresponding (unbalanced) budget posting to every + transaction involving the expenses:gifts account: + + = expenses:gifts + (budget:gifts) *-1 + + 2017-12-14 + expenses:gifts $20 + assets + + $ hledger print --auto + 2017/12/14 + expenses:gifts $20 + assets + (budget:gifts) $-20 + +EDITOR SUPPORT + Add-on modes exist for various text editors, to make working with jour- + nal files easier. They add colour, navigation aids and helpful com- + mands. For hledger users who edit the journal file directly (the + majority), using one of these modes is quite recommended. + + These were written with Ledger in mind, but also work with hledger + files: + + + Editor + -------------------------------------------------------------------------- + Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html + Vim https://github.com/ledger/ledger/wiki/Getting-started + Sublime Text https://github.com/ledger/ledger/wiki/Edit- + ing-Ledger-files-with-Sublime-Text-or-RubyMine + Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 + Text Wran- https://github.com/ledger/ledger/wiki/Edit- + gler ing-Ledger-files-with-TextWrangler + Visual Stu- https://marketplace.visualstudio.com/items?item- + dio Code Name=mark-hansen.hledger-vscode + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.9 March 2018 hledger_journal(5) diff --git a/embeddedfiles/hledger_timeclock.5 b/embeddedfiles/hledger_timeclock.5 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_timeclock.5 @@ -0,0 +1,92 @@ + +.TH "hledger_timeclock" "5" "March 2018" "hledger 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +Timeclock \- the time logging format of timeclock.el, as read by hledger +.SH DESCRIPTION +.PP +hledger can read timeclock files. +As with Ledger, these are (a subset of) timeclock.el's format, +containing clock\-in and clock\-out entries as in the example below. +The date is a simple date. +The time format is HH:MM[:SS][+\-ZZZZ]. +Seconds and timezone are optional. +The timezone, if present, must be four digits and is ignored (currently +the time is always interpreted as a local time). +.IP +.nf +\f[C] +i\ 2015/03/30\ 09:00:00\ some:account\ name\ \ optional\ description\ after\ two\ spaces +o\ 2015/03/30\ 09:20:00 +i\ 2015/03/31\ 22:21:45\ another\ account +o\ 2015/04/01\ 02:00:34 +\f[] +.fi +.PP +hledger treats each clock\-in/clock\-out pair as a transaction posting +some number of hours to an account. +Or if the session spans more than one day, it is split into several +transactions, one for each day. +For the above time log, \f[C]hledger\ print\f[] generates these journal +entries: +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.timeclock\ print +2015/03/30\ *\ optional\ description\ after\ two\ spaces +\ \ \ \ (some:account\ name)\ \ \ \ \ \ \ \ \ 0.33h + +2015/03/31\ *\ 22:21\-23:59 +\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 1.64h + +2015/04/01\ *\ 00:00\-02:00 +\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 2.01h +\f[] +.fi +.PP +Here is a sample.timeclock to download and some queries to try: +.IP +.nf +\f[C] +$\ hledger\ \-f\ sample.timeclock\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ current\ time\ balances +$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ 2009/3\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ sessions\ in\ march\ 2009 +$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ weekly\ \-\-depth\ 1\ \-\-empty\ \ #\ time\ summary\ by\ week +\f[] +.fi +.PP +To generate time logs, ie to clock in and clock out, you could: +.IP \[bu] 2 +use emacs and the built\-in timeclock.el, or the extended +timeclock\-x.el and perhaps the extras in ledgerutils.el +.IP \[bu] 2 +at the command line, use these bash aliases: +\f[C]shell\ \ \ alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG"\ \ \ alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG"\f[] +.IP \[bu] 2 +or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x +repository. +These rely on a \[lq]timeclock\[rq] executable which I think is just the +ledger 2 executable renamed. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger_timeclock.info b/embeddedfiles/hledger_timeclock.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_timeclock.info @@ -0,0 +1,60 @@ +This is hledger_timeclock.info, produced by makeinfo version 6.5 from +stdin. + + +File: hledger_timeclock.info, Node: Top, Up: (dir) + +hledger_timeclock(5) hledger 1.9 +******************************** + +hledger can read timeclock files. As with Ledger, these are (a subset +of) timeclock.el's format, containing clock-in and clock-out entries as +in the example below. The date is a simple date. The time format is +HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, if +present, must be four digits and is ignored (currently the time is +always interpreted as a local time). + +i 2015/03/30 09:00:00 some:account name optional description after two spaces +o 2015/03/30 09:20:00 +i 2015/03/31 22:21:45 another account +o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting +some number of hours to an account. Or if the session spans more than +one day, it is split into several transactions, one for each day. For +the above time log, 'hledger print' generates these journal entries: + +$ hledger -f t.timeclock print +2015/03/30 * optional description after two spaces + (some:account name) 0.33h + +2015/03/31 * 22:21-23:59 + (another account) 1.64h + +2015/04/01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + +$ hledger -f sample.timeclock balance # current time balances +$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + * use emacs and the built-in timeclock.el, or the extended + timeclock-x.el and perhaps the extras in ledgerutils.el + + * at the command line, use these bash aliases: 'shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' + * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + + +Tag Table: +Node: Top78 + +End Tag Table diff --git a/embeddedfiles/hledger_timeclock.txt b/embeddedfiles/hledger_timeclock.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_timeclock.txt @@ -0,0 +1,80 @@ + +hledger_timeclock(5) hledger User Manuals hledger_timeclock(5) + + + +NAME + Timeclock - the time logging format of timeclock.el, as read by hledger + +DESCRIPTION + hledger can read timeclock files. As with Ledger, these are (a subset + of) timeclock.el's format, containing clock-in and clock-out entries as + in the example below. The date is a simple date. The time format is + HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone, + if present, must be four digits and is ignored (currently the time is + always interpreted as a local time). + + i 2015/03/30 09:00:00 some:account name optional description after two spaces + o 2015/03/30 09:20:00 + i 2015/03/31 22:21:45 another account + o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For + the above time log, hledger print generates these journal entries: + + $ hledger -f t.timeclock print + 2015/03/30 * optional description after two spaces + (some:account name) 0.33h + + 2015/03/31 * 22:21-23:59 + (another account) 1.64h + + 2015/04/01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + + $ hledger -f sample.timeclock balance # current time balances + $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 + $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + o use emacs and the built-in timeclock.el, or the extended time- + clock-x.el and perhaps the extras in ledgerutils.el + + o at the command line, use these bash aliases: + shell alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" + + o or use the old ti and to scripts in the ledger 2.x repository. These + rely on a "timeclock" executable which I think is just the ledger 2 + executable renamed. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.9 March 2018 hledger_timeclock(5) diff --git a/embeddedfiles/hledger_timedot.5 b/embeddedfiles/hledger_timedot.5 new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_timedot.5 @@ -0,0 +1,154 @@ + +.TH "hledger_timedot" "5" "March 2018" "hledger 1.9" "hledger User Manuals" + + + +.SH NAME +.PP +Timedot \- hledger's human\-friendly time logging format +.SH DESCRIPTION +.PP +Timedot is a plain text format for logging dated, categorised quantities +(of time, usually), supported by hledger. +It is convenient for approximate and retroactive time logging, eg when +the real\-time clock\-in/out required with a timeclock file is too +precise or too interruptive. +It can be formatted like a bar chart, making clear at a glance where +time was spent. +.PP +Though called \[lq]timedot\[rq], this format is read by hledger as +commodityless quantities, so it could be used to represent dated +quantities other than time. +In the docs below we'll assume it's time. +.SH FILE FORMAT +.PP +A timedot file contains a series of day entries. +A day entry begins with a date, and is followed by category/quantity +pairs, one per line. +Dates are hledger\-style simple dates (see hledger_journal(5)). +Categories are hledger\-style account names, optionally indented. +As in a hledger journal, there must be at least two spaces between the +category (account name) and the quantity. +.PP +Quantities can be written as: +.IP \[bu] 2 +a sequence of dots (.) representing quarter hours. +Spaces may optionally be used for grouping and readability. +Eg: \&.... +\&.. +.IP \[bu] 2 +an integral or decimal number, representing hours. +Eg: 1.5 +.IP \[bu] 2 +an integral or decimal number immediately followed by a unit symbol +\f[C]s\f[], \f[C]m\f[], \f[C]h\f[], \f[C]d\f[], \f[C]w\f[], \f[C]mo\f[], +or \f[C]y\f[], representing seconds, minutes, hours, days weeks, months +or years respectively. +Eg: 90m. +The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, +1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. +.PP +Blank lines and lines beginning with #, ; or * are ignored. +An example: +.IP +.nf +\f[C] +#\ on\ this\ day,\ 6h\ was\ spent\ on\ client\ work,\ 1.5h\ on\ haskell\ FOSS\ work,\ etc. +2016/2/1 +inc:client1\ \ \ ....\ ....\ ....\ ....\ ....\ .... +fos:haskell\ \ \ ....\ ..\ +biz:research\ \ . + +2016/2/2 +inc:client1\ \ \ ....\ .... +biz:research\ \ . +\f[] +.fi +.PP +Or with numbers: +.IP +.nf +\f[C] +2016/2/3 +inc:client1\ \ \ 4 +fos:hledger\ \ \ 3 +biz:research\ \ 1 +\f[] +.fi +.PP +Reporting: +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.timedot\ print\ date:2016/2/2 +2016/02/02\ * +\ \ \ \ (inc:client1)\ \ \ \ \ \ \ \ \ \ 2.00 + +2016/02/02\ * +\ \ \ \ (biz:research)\ \ \ \ \ \ \ \ \ \ 0.25 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.timedot\ bal\ \-\-daily\ \-\-tree +Balance\ changes\ in\ 2016/02/01\-2016/02/03: + +\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2016/02/01d\ \ 2016/02/02d\ \ 2016/02/03d\ +============++======================================== +\ biz\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ +\ \ \ research\ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ +\ fos\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ +\ \ \ haskell\ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ +\ \ \ hledger\ \ ||\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ +\ inc\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ +\ \ \ client1\ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ +\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 7.75\ \ \ \ \ \ \ \ \ 2.25\ \ \ \ \ \ \ \ \ 8.00\ +\f[] +.fi +.PP +I prefer to use period for separating account components. +We can make this work with an account alias: +.IP +.nf +\f[C] +2016/2/4 +fos.hledger.timedot\ \ 4 +fos.ledger\ \ \ \ \ \ \ \ \ \ \ .. +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4 +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50\ \ fos +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.00\ \ \ \ hledger:timedot +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0.50\ \ \ \ ledger +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50 +\f[] +.fi +.PP +Here is a sample.timedot. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/embeddedfiles/hledger_timedot.info b/embeddedfiles/hledger_timedot.info new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_timedot.info @@ -0,0 +1,116 @@ +This is hledger_timedot.info, produced by makeinfo version 6.5 from +stdin. + + +File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir) + +hledger_timedot(5) hledger 1.9 +****************************** + +Timedot is a plain text format for logging dated, categorised quantities +(of time, usually), supported by hledger. It is convenient for +approximate and retroactive time logging, eg when the real-time +clock-in/out required with a timeclock file is too precise or too +interruptive. It can be formatted like a bar chart, making clear at a +glance where time was spent. + + Though called "timedot", this format is read by hledger as +commodityless quantities, so it could be used to represent dated +quantities other than time. In the docs below we'll assume it's time. +* Menu: + +* FILE FORMAT:: + + +File: hledger_timedot.info, Node: FILE FORMAT, Prev: Top, Up: Top + +1 FILE FORMAT +************* + +A timedot file contains a series of day entries. A day entry begins +with a date, and is followed by category/quantity pairs, one per line. +Dates are hledger-style simple dates (see hledger_journal(5)). +Categories are hledger-style account names, optionally indented. As in +a hledger journal, there must be at least two spaces between the +category (account name) and the quantity. + + Quantities can be written as: + + * a sequence of dots (.) representing quarter hours. Spaces may + optionally be used for grouping and readability. Eg: .... .. + + * an integral or decimal number, representing hours. Eg: 1.5 + + * an integral or decimal number immediately followed by a unit symbol + 's', 'm', 'h', 'd', 'w', 'mo', or 'y', representing seconds, + minutes, hours, days weeks, months or years respectively. Eg: 90m. + The following equivalencies are assumed, currently: 1m = 60s, 1h = + 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. + + Blank lines and lines beginning with #, ; or * are ignored. An +example: + +# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. +2016/2/1 +inc:client1 .... .... .... .... .... .... +fos:haskell .... .. +biz:research . + +2016/2/2 +inc:client1 .... .... +biz:research . + + Or with numbers: + +2016/2/3 +inc:client1 4 +fos:hledger 3 +biz:research 1 + + Reporting: + +$ hledger -f t.timedot print date:2016/2/2 +2016/02/02 * + (inc:client1) 2.00 + +2016/02/02 * + (biz:research) 0.25 + +$ hledger -f t.timedot bal --daily --tree +Balance changes in 2016/02/01-2016/02/03: + + || 2016/02/01d 2016/02/02d 2016/02/03d +============++======================================== + biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 +------------++---------------------------------------- + || 7.75 2.25 8.00 + + I prefer to use period for separating account components. We can +make this work with an account alias: + +2016/2/4 +fos.hledger.timedot 4 +fos.ledger .. + +$ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4 + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +-------------------- + 4.50 + + Here is a sample.timedot. + + +Tag Table: +Node: Top76 +Node: FILE FORMAT805 +Ref: #file-format906 + +End Tag Table diff --git a/embeddedfiles/hledger_timedot.txt b/embeddedfiles/hledger_timedot.txt new file mode 100644 --- /dev/null +++ b/embeddedfiles/hledger_timedot.txt @@ -0,0 +1,127 @@ + +hledger_timedot(5) hledger User Manuals hledger_timedot(5) + + + +NAME + Timedot - hledger's human-friendly time logging format + +DESCRIPTION + Timedot is a plain text format for logging dated, categorised quanti- + ties (of time, usually), supported by hledger. It is convenient for + approximate and retroactive time logging, eg when the real-time + clock-in/out required with a timeclock file is too precise or too + interruptive. It can be formatted like a bar chart, making clear at a + glance where time was spent. + + Though called "timedot", this format is read by hledger as commodity- + less quantities, so it could be used to represent dated quantities + other than time. In the docs below we'll assume it's time. + +FILE FORMAT + A timedot file contains a series of day entries. A day entry begins + with a date, and is followed by category/quantity pairs, one per line. + Dates are hledger-style simple dates (see hledger_journal(5)). Cate- + gories are hledger-style account names, optionally indented. As in a + hledger journal, there must be at least two spaces between the category + (account name) and the quantity. + + Quantities can be written as: + + o a sequence of dots (.) representing quarter hours. Spaces may + optionally be used for grouping and readability. Eg: .... .. + + o an integral or decimal number, representing hours. Eg: 1.5 + + o an integral or decimal number immediately followed by a unit symbol + s, m, h, d, w, mo, or y, representing seconds, minutes, hours, days + weeks, months or years respectively. Eg: 90m. The following equiva- + lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = + 7d, 1mo = 30d, 1y=365d. + + Blank lines and lines beginning with #, ; or * are ignored. An exam- + ple: + + # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. + 2016/2/1 + inc:client1 .... .... .... .... .... .... + fos:haskell .... .. + biz:research . + + 2016/2/2 + inc:client1 .... .... + biz:research . + + Or with numbers: + + 2016/2/3 + inc:client1 4 + fos:hledger 3 + biz:research 1 + + Reporting: + + $ hledger -f t.timedot print date:2016/2/2 + 2016/02/02 * + (inc:client1) 2.00 + + 2016/02/02 * + (biz:research) 0.25 + + $ hledger -f t.timedot bal --daily --tree + Balance changes in 2016/02/01-2016/02/03: + + || 2016/02/01d 2016/02/02d 2016/02/03d + ============++======================================== + biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 + ------------++---------------------------------------- + || 7.75 2.25 8.00 + + I prefer to use period for separating account components. We can make + this work with an account alias: + + 2016/2/4 + fos.hledger.timedot 4 + fos.ledger .. + + $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4 + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger + -------------------- + 4.50 + + Here is a sample.timedot. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 1.9 March 2018 hledger_timedot(5) diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "December 2017" "hledger 1.5" "hledger User Manuals" +.TH "hledger" "1" "March 2018" "hledger 1.9" "hledger User Manuals" @@ -282,7 +282,8 @@ .RE .TP .B \f[C]\-E\ \-\-empty\f[] -show items with zero amount, normally hidden +show items with zero amount, normally hidden (and vice\-versa in +hledger\-ui/hledger\-web) .RS .RE .TP @@ -987,6 +988,33 @@ Using \-B/\[en]cost and \-V/\[en]value together is currently allowed, but the results are probably not meaningful. Let us know if you find a use for this. +.SS Output destination +.PP +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. +This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) +$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE +\f[] +.fi +.SS Output format +.PP +Some commands can write their output in other formats. +Eg print and register can output CSV, and the balance commands can +output CSV or HTML. +This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by +specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with +\f[C]\-o/\-\-output\-file\f[]. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout +$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv +\f[] +.fi .SS Regular expressions .PP hledger uses regular expressions in a number of places: @@ -1200,8 +1228,18 @@ Show account names. Alias: a. .TP +.B \f[C]\-\-declared\f[] +show account names declared with account directives +.RS +.RE +.TP +.B \f[C]\-\-used\f[] +show account names posted to by transactions +.RS +.RE +.TP .B \f[C]\-\-tree\f[] -show short account names, as a tree +show short account names and their parents, as a tree .RS .RE .TP @@ -1215,16 +1253,17 @@ .RS .RE .PP -This command lists all account names that are in use (ie, all the -accounts which have at least one transaction posting to them). -With query arguments, only matched account names are shown. -.PP +This command lists account names, either declared with account +directives (\[en]declared), posted to (\[en]used), or both (default). +With query arguments, only matched account names and account names +referenced by matched postings are shown. It shows a flat list by default. With \f[C]\-\-tree\f[], it uses indentation to show the account hierarchy. -.PP In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few account name components. +Account names can be depth\-clipped with \f[C]\-\-depth\ N\f[] or +depth:N. .PP Examples: .IP @@ -1437,7 +1476,7 @@ .TP .B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] select the output format. -Supported formats: txt, csv. +Supported formats: txt, csv, html. .RS .RE .TP @@ -1453,12 +1492,17 @@ .RE .TP .B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account name (in flat mode). +sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. .RS .RE .TP +.B \f[C]\-\-invert\f[] +display all amounts with reversed sign +.RS +.RE +.TP .B \f[C]\-\-budget\f[] show performance compared to budget goals defined by periodic transactions @@ -1499,14 +1543,18 @@ .PP By default, accounts are displayed hierarchically, with subaccounts indented below their parent. +At each level of the tree, accounts are sorted by account code if any, +then by account name. +Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount. +.PP \[lq]Boring\[rq] accounts, which contain a single interesting subaccount and no balance of their own, are elided into the following line for more compact output. -(Use \f[C]\-\-no\-elide\f[] to prevent this. -Eliding of boring accounts is not yet supported in multicolumn reports.) +(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to +prevent this. .PP -Each account's balance is the \[lq]inclusive\[rq] balance \- it includes -the balances of any subaccounts. +Account balances are \[lq]inclusive\[rq] \- they include the balances of +any subaccounts. .PP Accounts which have zero balance (and no non\-zero subaccounts) are omitted. @@ -1780,11 +1828,15 @@ \f[] .fi .PP -For more examples and details, see Budgeting and Forecasting. +Note \[en]budget first arrived in hledger in 1.5 and is still pretty +young; join the discussions on mail list and issue tracker to help us +refine it. +.PP +For more examples, see Budgeting and Forecasting. .SS Custom balance output .PP -In simple (non\-multi\-column) balance reports, you can customise the -output with \f[C]\-\-format\ FMT\f[]: +You can customise the layout of simple (non\-tabular) balance reports +with \f[C]\-\-format\ FMT\f[]: .IP .nf \f[C] @@ -1852,6 +1904,9 @@ .IP \[bu] 2 \f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default format for the single\-column balance report +.PP +This command also supports output destination and output format +selection. .SS Colour support .PP The balance command shows negative amounts in red, if: @@ -1859,37 +1914,18 @@ the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[] .IP \[bu] 2 the output is not being redirected or piped anywhere -.SS Output destination -.PP -The balance, print, register and stats commands can write their output -to a destination other than the console. -This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) -$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE -\f[] -.fi -.SS CSV output -.PP -The balance, print and register commands can write their output as CSV. -This is useful for exporting data to other applications, eg to make -charts in a spreadsheet. -This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by -specifying a \f[C]\&.csv\f[] file extension with -\f[C]\-o/\-\-output\-file\f[]. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout -$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv -\f[] -.fi .SS balancesheet .PP -Show a balance sheet. -Alias: bs. +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). +It assumes that these accounts are under a top\-level \f[C]asset\f[] or +\f[C]liability\f[] account (case insensitive, plural forms also +allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +(bs) .TP .B \f[C]\-\-change\f[] show balance change in each period, instead of historical ending @@ -1952,13 +1988,11 @@ .RE .TP .B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account name +sort by amount instead of account code/name .RS .RE .PP -This command displays a simple balance sheet. -It currently assumes that you have top\-level accounts named -\f[C]asset\f[] and \f[C]liability\f[] (plural forms also allowed.) +Example: .IP .nf \f[C] @@ -1990,19 +2024,15 @@ Normally balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. -.SS balancesheetequity .PP -Show a balance sheet including equity. -Alias: bse. +This command also supports output destination and output format +selection. +.SS balancesheetequity .PP -Other than showing the equity accounts, this command is exactly the same -as the command balancesheet. -Please refer to it for the available options. +Just like balancesheet, but also reports Equity (which it assumes is +under a top\-level \f[C]equity\f[] account). .PP -This command displays a balancesheet. -It currently assumes that you have top\-level accounts named -\f[C]asset\f[], \f[C]liability\f[] and \f[C]equity\f[] (plural forms -also allowed.) +Example: .IP .nf \f[C] @@ -2033,8 +2063,15 @@ .fi .SS cashflow .PP -Show a cashflow statement. -Alias: cf. +This command displays a simple cashflow statement, showing changes in +\[lq]cash\[rq] accounts. +It assumes that these accounts are under a top\-level \f[C]asset\f[] +account (case insensitive, plural forms also allowed) and do not contain +\f[C]receivable\f[] or \f[C]A/R\f[] in their name. +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +(cf) .TP .B \f[C]\-\-change\f[] show balance change in each period (default) @@ -2096,15 +2133,11 @@ .RE .TP .B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account name +sort by amount instead of account code/name .RS .RE .PP -This command displays a simple cashflow statement It shows the change in -all \[lq]cash\[rq] (ie, liquid assets) accounts for the period. -It currently assumes that cash accounts are under a top\-level account -named \f[C]asset\f[] and do not contain \f[C]receivable\f[], -\f[C]:A/R\f[] or \f[C]:fixed\f[]. +Example: .IP .nf \f[C] @@ -2129,6 +2162,9 @@ Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report mode with \f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. .SS check\-dates .PP Check that transactions are sorted by increasing date. @@ -2137,11 +2173,15 @@ .PP Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger\-dupes.html -.SS equity +.SS close .PP Print closing/opening transactions that bring some or all account balances to zero and back. -Can be useful for bringing account balances across file boundaries. +Can be useful for bringing asset/liability balances across file +boundaries, or for closing out income/expenses for a period. +This was formerly called \[lq]equity\[rq], as in Ledger, and that alias +is also accepted. +See close \[en]help for more. .SS help .PP Show any of the hledger manuals. @@ -2213,8 +2253,15 @@ .fi .SS incomestatement .PP -Show an income statement. -Alias: is. +This command displays a simple income statement, showing revenues and +expenses during a period. +It assumes that these accounts are under a top\-level \f[C]revenue\f[] +or \f[C]income\f[] or \f[C]expense\f[] account (case insensitive, plural +forms also allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). +(is) .TP .B \f[C]\-\-change\f[] show balance change in each period (default) @@ -2276,7 +2323,7 @@ .RE .TP .B \f[C]\-\-sort\-amount\f[] -sort by amount instead of account name +sort by amount instead of account code/name .RS .RE .PP @@ -2315,6 +2362,9 @@ Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the report mode with \f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output format +selection. .SS prices .PP Print all market prices from the journal. @@ -2427,7 +2477,8 @@ reordered. See also the import command. .PP -The print command also supports output destination and CSV output. +This command also supports output destination and output format +selection. Here's an example of print's CSV output: .IP .nf @@ -2639,9 +2690,8 @@ \f[] .fi .PP -The register command also supports the \f[C]\-o/\-\-output\-file\f[] and -\f[C]\-O/\-\-output\-format\f[] options for controlling output -destination and CSV output. +This command also supports output destination and output format +selection. .SS register\-match .PP Print the one posting whose transaction description is closest to DESC, @@ -2680,8 +2730,8 @@ a matched part of it. With a reporting interval, it shows a report for each report period. .PP -The stats command also supports \f[C]\-o/\-\-output\-file\f[] for -controlling output destination. +This command also supports output destination and output format +selection. .SS tags .PP List all the tag names used in the journal. @@ -2783,9 +2833,6 @@ ledger\-autosync does deduplicating conversion of OFX data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. -.SS budget -.PP -hledger\-budget.hs adds more budget\-tracking features to hledger. .SS chart .PP hledger\-chart.hs is an old pie chart generator, in need of some love. diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -2,10 +2,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 8e14dbb3cafd99102e0a85bd39076ca0af4c9554f348cd6cacb0d59faf63623b +-- hash: 99eb38f5627e64b90fe33622dba3444cfb4f1d57f69c12b19731fb061f2b896a name: hledger -version: 1.5 +version: 1.9 synopsis: Command-line interface for the hledger accounting tool description: This is hledger's command-line interface. Its basic function is to read a plain text file describing @@ -32,34 +32,35 @@ extra-source-files: bench/10000x1000x10.journal CHANGES - README.md - test/test.hs - -data-files: - .otherdocs/hledger-api.1 - .otherdocs/hledger-api.info - .otherdocs/hledger-api.txt - .otherdocs/hledger-ui.1 - .otherdocs/hledger-ui.info - .otherdocs/hledger-ui.txt - .otherdocs/hledger-web.1 - .otherdocs/hledger-web.info - .otherdocs/hledger-web.txt - .otherdocs/hledger_csv.5 - .otherdocs/hledger_csv.info - .otherdocs/hledger_csv.txt - .otherdocs/hledger_journal.5 - .otherdocs/hledger_journal.info - .otherdocs/hledger_journal.txt - .otherdocs/hledger_timeclock.5 - .otherdocs/hledger_timeclock.info - .otherdocs/hledger_timeclock.txt - .otherdocs/hledger_timedot.5 - .otherdocs/hledger_timedot.info - .otherdocs/hledger_timedot.txt + embeddedfiles/hledger-api.1 + embeddedfiles/hledger-api.info + embeddedfiles/hledger-api.txt + embeddedfiles/hledger-ui.1 + embeddedfiles/hledger-ui.info + embeddedfiles/hledger-ui.txt + embeddedfiles/hledger-web.1 + embeddedfiles/hledger-web.info + embeddedfiles/hledger-web.txt + embeddedfiles/hledger.1 + embeddedfiles/hledger.info + embeddedfiles/hledger.txt + embeddedfiles/hledger_csv.5 + embeddedfiles/hledger_csv.info + embeddedfiles/hledger_csv.txt + embeddedfiles/hledger_journal.5 + embeddedfiles/hledger_journal.info + embeddedfiles/hledger_journal.txt + embeddedfiles/hledger_timeclock.5 + embeddedfiles/hledger_timeclock.info + embeddedfiles/hledger_timeclock.txt + embeddedfiles/hledger_timedot.5 + embeddedfiles/hledger_timedot.info + embeddedfiles/hledger_timedot.txt hledger.1 hledger.info hledger.txt + README.md + test/test.hs source-repository head type: git @@ -76,14 +77,14 @@ default: True library - ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.5" + ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path + cpp-options: -DVERSION="1.9" build-depends: Decimal , Diff , HUnit , ansi-terminal >=0.6.2.3 - , base >=4.8 && <5 + , base >=4.8 && <4.12 , base-compat >=0.8.1 , bytestring , cmdargs >=0.10 @@ -96,7 +97,8 @@ , hashable >=1.2.4 , haskeline >=0.6 , here - , hledger-lib >=1.5 && <1.6 + , hledger-lib >=1.9 && <2.0 + , lucid , megaparsec >=5.0 , mtl , mtl-compat @@ -136,7 +138,7 @@ Hledger.Cli.Commands.Cashflow Hledger.Cli.Commands.Checkdates Hledger.Cli.Commands.Checkdupes - Hledger.Cli.Commands.Equity + Hledger.Cli.Commands.Close Hledger.Cli.Commands.Help Hledger.Cli.Commands.Import Hledger.Cli.Commands.Incomestatement @@ -158,13 +160,13 @@ main-is: hledger-cli.hs hs-source-dirs: app - ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.5" + ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path + cpp-options: -DVERSION="1.9" build-depends: Decimal , HUnit , ansi-terminal >=0.6.2.3 - , base >=4.8 && <5 + , base >=4.8 && <4.12 , base-compat >=0.8.1 , bytestring , cmdargs >=0.10 @@ -177,7 +179,7 @@ , haskeline >=0.6 , here , hledger - , hledger-lib >=1.5 && <1.6 + , hledger-lib >=1.9 && <2.0 , mtl , mtl-compat , old-time @@ -210,13 +212,13 @@ main-is: test.hs hs-source-dirs: test - ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.5" + ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path + cpp-options: -DVERSION="1.9" build-depends: Decimal , HUnit , ansi-terminal >=0.6.2.3 - , base >=4.8 && <5 + , base >=4.8 && <4.12 , base-compat >=0.8.1 , bytestring , cmdargs >=0.10 @@ -229,7 +231,7 @@ , haskeline >=0.6 , here , hledger - , hledger-lib >=1.5 && <1.6 + , hledger-lib >=1.9 && <2.0 , mtl , mtl-compat , old-time @@ -262,10 +264,10 @@ main-is: bench.hs hs-source-dirs: bench - ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans + ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path build-depends: ansi-terminal >=0.6.2.3 - , base >=4.8 && <5 + , base >=4.8 && <4.12 , base-compat >=0.8.1 , criterion , directory @@ -273,7 +275,7 @@ , filepath , here , hledger - , hledger-lib >=1.5 && <1.6 + , hledger-lib >=1.9 && <2.0 , html , pretty-show >=1.6.4 , process diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -3,7 +3,7 @@  File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.5 +hledger(1) hledger 1.9 ********************** This is hledger's command-line interface (there are also curses and web @@ -130,6 +130,8 @@ * Cost:: * Market value:: * Combining -B and -V:: +* Output destination:: +* Output format:: * Regular expressions::  @@ -223,7 +225,8 @@ hide/aggregate accounts or postings more than NUM levels deep '-E --empty' - show items with zero amount, normally hidden + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) '-B --cost' convert amounts to their cost at transaction time (using the @@ -673,7 +676,7 @@ directives, not transaction prices (unlike Ledger).  -File: hledger.info, Node: Combining -B and -V, Next: Regular expressions, Prev: Market value, Up: OPTIONS +File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS 2.15 Combining -B and -V ======================== @@ -683,9 +686,36 @@ this.  -File: hledger.info, Node: Regular expressions, Prev: Combining -B and -V, Up: OPTIONS +File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS -2.16 Regular expressions +2.16 Output destination +======================= + +Some commands (print, register, stats, the balance commands) can write +their output to a destination other than the console. This is +controlled by the '-o/--output-file' option. + +$ hledger balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE + + +File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS + +2.17 Output format +================== + +Some commands can write their output in other formats. Eg print and +register can output CSV, and the balance commands can output CSV or +HTML. This is controlled by the '-O/--output-format' option, or by +specifying a '.csv' or '.html' file extension with '-o/--output-file'. + +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv + + +File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS + +2.18 Regular expressions ======================== hledger uses regular expressions in a number of places: @@ -865,7 +895,7 @@ * cashflow:: * check-dates:: * check-dupes:: -* equity:: +* close:: * help:: * import:: * incomestatement:: @@ -887,9 +917,15 @@ Show account names. Alias: a. +'--declared' + + show account names declared with account directives +'--used' + + show account names posted to by transactions '--tree' - show short account names, as a tree + show short account names and their parents, as a tree '--flat' show full account names, as a list (default) @@ -897,15 +933,14 @@ in flat mode: omit N leading account name parts - This command lists all account names that are in use (ie, all the -accounts which have at least one transaction posting to them). With -query arguments, only matched account names are shown. - - It shows a flat list by default. With '--tree', it uses indentation -to show the account hierarchy. - - In flat mode you can add '--drop N' to omit the first few account -name components. + This command lists account names, either declared with account +directives (-declared), posted to (-used), or both (default). With +query arguments, only matched account names and account names referenced +by matched postings are shown. It shows a flat list by default. With +'--tree', it uses indentation to show the account hierarchy. In flat +mode you can add '--drop N' to omit the first few account name +components. Account names can be depth-clipped with '--depth N' or +depth:N. Examples: @@ -1079,7 +1114,7 @@ in single-column balance reports: use this custom line format '-O FMT --output-format=FMT' - select the output format. Supported formats: txt, csv. + select the output format. Supported formats: txt, csv, html. '-o FILE --output-file=FILE' write output to FILE. A file extension matching one of the above @@ -1089,9 +1124,12 @@ use unicode to display prettier tables. '--sort-amount' - sort by amount instead of account name (in flat mode). With + sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. +'--invert' + + display all amounts with reversed sign '--budget' show performance compared to budget goals defined by periodic @@ -1123,15 +1161,18 @@ opening balances, this is the same as the account's ending balance. By default, accounts are displayed hierarchically, with subaccounts -indented below their parent. "Boring" accounts, which contain a single -interesting subaccount and no balance of their own, are elided into the -following line for more compact output. (Use '--no-elide' to prevent -this. Eliding of boring accounts is not yet supported in multicolumn -reports.) +indented below their parent. At each level of the tree, accounts are +sorted by account code if any, then by account name. Or with +'-S/--sort-amount', by their balance amount. - Each account's balance is the "inclusive" balance - it includes the -balances of any subaccounts. + "Boring" accounts, which contain a single interesting subaccount and +no balance of their own, are elided into the following line for more +compact output. (Not yet supported in tabular reports.) Use +'--no-elide' to prevent this. + Account balances are "inclusive" - they include the balances of any +subaccounts. + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use '-E/--empty' to show them. @@ -1151,8 +1192,6 @@ * Budgets:: * Custom balance output:: * Colour support:: -* Output destination:: -* CSV output::  File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance @@ -1377,16 +1416,20 @@ ----------------------++------------------------------------------------- || 0 0 - For more examples and details, see Budgeting and Forecasting. + Note -budget first arrived in hledger in 1.5 and is still pretty +young; join the discussions on mail list and issue tracker to help us +refine it. + For more examples, see Budgeting and Forecasting. +  File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance 4.4.5 Custom balance output --------------------------- -In simple (non-multi-column) balance reports, you can customise the -output with '--format FMT': +You can customise the layout of simple (non-tabular) balance reports +with '--format FMT': $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -1439,8 +1482,11 @@ * '%20(total) %2(depth_spacer)%-(account)' - the default format for the single-column balance report + This command also supports output destination and output format +selection. +  -File: hledger.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance +File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance 4.4.6 Colour support -------------------- @@ -1451,40 +1497,18 @@ * the output is not being redirected or piped anywhere  -File: hledger.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance - -4.4.7 Output destination ------------------------- - -The balance, print, register and stats commands can write their output -to a destination other than the console. This is controlled by the -'-o/--output-file' option. - -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE - - -File: hledger.info, Node: CSV output, Prev: Output destination, Up: balance - -4.4.8 CSV output ----------------- - -The balance, print and register commands can write their output as CSV. -This is useful for exporting data to other applications, eg to make -charts in a spreadsheet. This is controlled by the '-O/--output-format' -option, or by specifying a '.csv' file extension with -'-o/--output-file'. - -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv - - File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS 4.5 balancesheet ================ -Show a balance sheet. Alias: bs. +This command displays a simple balance sheet, showing historical ending +balances of asset and liability accounts (ignoring any report begin +date). It assumes that these accounts are under a top-level 'asset' or +'liability' account (case insensitive, plural forms also allowed). Note +this report shows all account balances with normal positive sign (like +conventional financial statements, unlike balance/print/register) +(experimental). (bs) '--change' @@ -1526,11 +1550,9 @@ in single-column balance reports: use this custom line format '--sort-amount' - sort by amount instead of account name + sort by amount instead of account code/name - This command displays a simple balance sheet. It currently assumes -that you have top-level accounts named 'asset' and 'liability' (plural -forms also allowed.) + Example: $ hledger balancesheet Balance Sheet @@ -1557,21 +1579,19 @@ balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. + This command also supports output destination and output format +selection. +  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS 4.6 balancesheetequity ====================== -Show a balance sheet including equity. Alias: bse. - - Other than showing the equity accounts, this command is exactly the -same as the command balancesheet. Please refer to it for the available -options. +Just like balancesheet, but also reports Equity (which it assumes is +under a top-level 'equity' account). - This command displays a balancesheet. It currently assumes that you -have top-level accounts named 'asset', 'liability' and 'equity' (plural -forms also allowed.) + Example: $ hledger balancesheetequity Balance Sheet With Equity @@ -1603,7 +1623,12 @@ 4.7 cashflow ============ -Show a cashflow statement. Alias: cf. +This command displays a simple cashflow statement, showing changes in +"cash" accounts. It assumes that these accounts are under a top-level +'asset' account (case insensitive, plural forms also allowed) and do not +contain 'receivable' or 'A/R' in their name. Note this report shows all +account balances with normal positive sign (like conventional financial +statements, unlike balance/print/register) (experimental). (cf) '--change' @@ -1644,12 +1669,9 @@ in single-column balance reports: use this custom line format '--sort-amount' - sort by amount instead of account name + sort by amount instead of account code/name - This command displays a simple cashflow statement It shows the change -in all "cash" (ie, liquid assets) accounts for the period. It currently -assumes that cash accounts are under a top-level account named 'asset' -and do not contain 'receivable', ':A/R' or ':fixed'. + Example: $ hledger cashflow Cashflow Statement @@ -1670,6 +1692,9 @@ period, though as with multicolumn balance reports you can alter the report mode with '--change'/'--cumulative'/'--historical'. + This command also supports output destination and output format +selection. +  File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS @@ -1680,7 +1705,7 @@ only matched transactions' dates are checked.  -File: hledger.info, Node: check-dupes, Next: equity, Prev: check-dates, Up: COMMANDS +File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS 4.9 check-dupes =============== @@ -1689,17 +1714,19 @@ example: http://stefanorodighiero.net/software/hledger-dupes.html  -File: hledger.info, Node: equity, Next: help, Prev: check-dupes, Up: COMMANDS +File: hledger.info, Node: close, Next: help, Prev: check-dupes, Up: COMMANDS -4.10 equity -=========== +4.10 close +========== Print closing/opening transactions that bring some or all account -balances to zero and back. Can be useful for bringing account balances -across file boundaries. +balances to zero and back. Can be useful for bringing asset/liability +balances across file boundaries, or for closing out income/expenses for +a period. This was formerly called "equity", as in Ledger, and that +alias is also accepted. See close -help for more.  -File: hledger.info, Node: help, Next: import, Prev: equity, Up: COMMANDS +File: hledger.info, Node: help, Next: import, Prev: close, Up: COMMANDS 4.11 help ========= @@ -1767,7 +1794,12 @@ 4.13 incomestatement ==================== -Show an income statement. Alias: is. +This command displays a simple income statement, showing revenues and +expenses during a period. It assumes that these accounts are under a +top-level 'revenue' or 'income' or 'expense' account (case insensitive, +plural forms also allowed). Note this report shows all account balances +with normal positive sign (like conventional financial statements, +unlike balance/print/register) (experimental). (is) '--change' @@ -1808,7 +1840,7 @@ in single-column balance reports: use this custom line format '--sort-amount' - sort by amount instead of account name + sort by amount instead of account code/name This command displays a simple income statement. It currently assumes that you have top-level accounts named 'income' (or 'revenue') @@ -1840,6 +1872,9 @@ per period, though as with multicolumn balance reports you can alter the report mode with '--change'/'--cumulative'/'--historical'. + This command also supports output destination and output format +selection. +  File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS @@ -1935,8 +1970,8 @@ increasing dates, and that transactions on the same day do not get reordered. See also the import command. - The print command also supports output destination and CSV output. -Here's an example of print's CSV output: + This command also supports output destination and output format +selection. Here's an example of print's CSV output: $ hledger print -Ocsv "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" @@ -2106,9 +2141,8 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - The register command also supports the '-o/--output-file' and -'-O/--output-format' options for controlling output destination and CSV -output. + This command also supports output destination and output format +selection.  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS @@ -2157,8 +2191,8 @@ or a matched part of it. With a reporting interval, it shows a report for each report period. - The stats command also supports '-o/--output-file' for controlling -output destination. + This command also supports output destination and output format +selection.  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS @@ -2326,12 +2360,11 @@ * Menu: * autosync:: -* budget:: * chart:: * check::  -File: hledger.info, Node: autosync, Next: budget, Up: Experimental add-ons +File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons 5.3.1 autosync -------------- @@ -2342,17 +2375,9 @@ OFX Direct Connect.  -File: hledger.info, Node: budget, Next: chart, Prev: autosync, Up: Experimental add-ons - -5.3.2 budget ------------- - -hledger-budget.hs adds more budget-tracking features to hledger. - - -File: hledger.info, Node: chart, Next: check, Prev: budget, Up: Experimental add-ons +File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons -5.3.3 chart +5.3.2 chart ----------- hledger-chart.hs is an old pie chart generator, in need of some love. @@ -2360,7 +2385,7 @@  File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons -5.3.4 check +5.3.3 check ----------- hledger-check.hs checks more powerful account balance assertions. @@ -2372,133 +2397,131 @@ Ref: #examples1982 Node: OPTIONS3628 Ref: #options3730 -Node: General options4054 -Ref: #general-options4179 -Node: Command options6730 -Ref: #command-options6881 -Node: Command arguments7279 -Ref: #command-arguments7433 -Node: Argument files7554 -Ref: #argument-files7705 -Node: Special characters7971 -Ref: #special-characters8124 -Node: Input files9543 -Ref: #input-files9679 -Node: Smart dates11649 -Ref: #smart-dates11790 -Node: Report start & end date12769 -Ref: #report-start-end-date12939 -Node: Report intervals14004 -Ref: #report-intervals14167 -Node: Period expressions14568 -Ref: #period-expressions14728 -Node: Depth limiting18685 -Ref: #depth-limiting18829 -Node: Pivoting19171 -Ref: #pivoting19289 -Node: Cost20965 -Ref: #cost21073 -Node: Market value21191 -Ref: #market-value21326 -Node: Combining -B and -V22509 -Ref: #combining--b-and--v22673 -Node: Regular expressions22820 -Ref: #regular-expressions22963 -Node: QUERIES24324 -Ref: #queries24426 -Node: COMMANDS28393 -Ref: #commands28505 -Node: accounts29488 -Ref: #accounts29586 -Node: activity30579 -Ref: #activity30689 -Node: add31049 -Ref: #add31148 -Node: balance33809 -Ref: #balance33920 -Node: Flat mode37294 -Ref: #flat-mode37419 -Node: Depth limited balance reports37839 -Ref: #depth-limited-balance-reports38040 -Node: Multicolumn balance reports38460 -Ref: #multicolumn-balance-reports38655 -Node: Budgets43344 -Ref: #budgets43491 -Node: Custom balance output47322 -Ref: #custom-balance-output47484 -Node: Colour support49577 -Ref: #colour-support49736 -Node: Output destination49909 -Ref: #output-destination50065 -Node: CSV output50335 -Ref: #csv-output50452 -Node: balancesheet50849 -Ref: #balancesheet50985 -Node: balancesheetequity52953 -Ref: #balancesheetequity53102 -Node: cashflow53891 -Ref: #cashflow54019 -Node: check-dates55931 -Ref: #check-dates56058 -Node: check-dupes56175 -Ref: #check-dupes56300 -Node: equity56437 -Ref: #equity56547 -Node: help56710 -Ref: #help56811 -Node: import57885 -Ref: #import57999 -Node: incomestatement58729 -Ref: #incomestatement58863 -Node: prices60816 -Ref: #prices60931 -Node: print60974 -Ref: #print61084 -Node: print-unique65969 -Ref: #print-unique66095 -Node: register66163 -Ref: #register66290 -Node: Custom register output70791 -Ref: #custom-register-output70920 -Node: register-match72217 -Ref: #register-match72351 -Node: rewrite72534 -Ref: #rewrite72651 -Node: stats72720 -Ref: #stats72823 -Node: tags73705 -Ref: #tags73803 -Node: test74039 -Ref: #test74123 -Node: ADD-ON COMMANDS74491 -Ref: #add-on-commands74601 -Node: Official add-ons75888 -Ref: #official-add-ons76028 -Node: api76115 -Ref: #api76204 -Node: ui76256 -Ref: #ui76355 -Node: web76413 -Ref: #web76502 -Node: Third party add-ons76548 -Ref: #third-party-add-ons76723 -Node: diff76858 -Ref: #diff76955 -Node: iadd77054 -Ref: #iadd77168 -Node: interest77251 -Ref: #interest77372 -Node: irr77467 -Ref: #irr77565 -Node: Experimental add-ons77643 -Ref: #experimental-add-ons77795 -Node: autosync78086 -Ref: #autosync78198 -Node: budget78437 -Ref: #budget78559 -Node: chart78625 -Ref: #chart78742 -Node: check78813 -Ref: #check78915 +Node: General options4095 +Ref: #general-options4220 +Node: Command options6819 +Ref: #command-options6970 +Node: Command arguments7368 +Ref: #command-arguments7522 +Node: Argument files7643 +Ref: #argument-files7794 +Node: Special characters8060 +Ref: #special-characters8213 +Node: Input files9632 +Ref: #input-files9768 +Node: Smart dates11738 +Ref: #smart-dates11879 +Node: Report start & end date12858 +Ref: #report-start-end-date13028 +Node: Report intervals14093 +Ref: #report-intervals14256 +Node: Period expressions14657 +Ref: #period-expressions14817 +Node: Depth limiting18774 +Ref: #depth-limiting18918 +Node: Pivoting19260 +Ref: #pivoting19378 +Node: Cost21054 +Ref: #cost21162 +Node: Market value21280 +Ref: #market-value21415 +Node: Combining -B and -V22598 +Ref: #combining--b-and--v22761 +Node: Output destination22908 +Ref: #output-destination23070 +Node: Output format23353 +Ref: #output-format23505 +Node: Regular expressions23890 +Ref: #regular-expressions24027 +Node: QUERIES25388 +Ref: #queries25490 +Node: COMMANDS29457 +Ref: #commands29569 +Node: accounts30551 +Ref: #accounts30649 +Node: activity31895 +Ref: #activity32005 +Node: add32365 +Ref: #add32464 +Node: balance35125 +Ref: #balance35236 +Node: Flat mode38740 +Ref: #flat-mode38865 +Node: Depth limited balance reports39285 +Ref: #depth-limited-balance-reports39486 +Node: Multicolumn balance reports39906 +Ref: #multicolumn-balance-reports40101 +Node: Budgets44790 +Ref: #budgets44937 +Node: Custom balance output48906 +Ref: #custom-balance-output49068 +Node: Colour support51234 +Ref: #colour-support51366 +Node: balancesheet51539 +Ref: #balancesheet51675 +Node: balancesheetequity53986 +Ref: #balancesheetequity54135 +Node: cashflow54672 +Ref: #cashflow54800 +Node: check-dates56923 +Ref: #check-dates57050 +Node: check-dupes57167 +Ref: #check-dupes57291 +Node: close57428 +Ref: #close57535 +Node: help57865 +Ref: #help57965 +Node: import59039 +Ref: #import59153 +Node: incomestatement59883 +Ref: #incomestatement60017 +Node: prices62421 +Ref: #prices62536 +Node: print62579 +Ref: #print62689 +Node: print-unique67583 +Ref: #print-unique67709 +Node: register67777 +Ref: #register67904 +Node: Custom register output72405 +Ref: #custom-register-output72534 +Node: register-match73764 +Ref: #register-match73898 +Node: rewrite74081 +Ref: #rewrite74198 +Node: stats74267 +Ref: #stats74370 +Node: tags75240 +Ref: #tags75338 +Node: test75574 +Ref: #test75658 +Node: ADD-ON COMMANDS76026 +Ref: #add-on-commands76136 +Node: Official add-ons77423 +Ref: #official-add-ons77563 +Node: api77650 +Ref: #api77739 +Node: ui77791 +Ref: #ui77890 +Node: web77948 +Ref: #web78037 +Node: Third party add-ons78083 +Ref: #third-party-add-ons78258 +Node: diff78393 +Ref: #diff78490 +Node: iadd78589 +Ref: #iadd78703 +Node: interest78786 +Ref: #interest78907 +Node: irr79002 +Ref: #irr79100 +Node: Experimental add-ons79178 +Ref: #experimental-add-ons79330 +Node: autosync79610 +Ref: #autosync79721 +Node: chart79960 +Ref: #chart80079 +Node: check80150 +Ref: #check80252  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -192,20 +192,21 @@ hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden + show items with zero amount, normally hidden (and vice-versa in + hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the + convert amounts to their cost at transaction time (using the transaction price, if any) -V --value - convert amounts to their market value on the report end date + convert amounts to their market value on the report end date (using the most recent applicable market price, if any) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- + apply periodic transaction rules to generate future transac- tions, to 6 months from now or report end date. When a reporting option appears more than once in the command line, the @@ -214,48 +215,48 @@ Some reporting options can also be written as query arguments. Command options - To see options for a particular command, including command-specific + 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: + Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an addon, you may need to put its - options after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an addon, you may need to put its + options after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the addon executable directly: hledger-ui --watch. Command arguments - Most hledger commands accept arguments after the command name, which + Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way. Argument files You can save a set of command line options/arguments in a file, one per - line, and then reuse them by writing @FILENAME in a command line. To + line, and then reuse them by writing @FILENAME in a command line. To prevent this expansion of @-arguments, precede them with a -- argument. For more, see Save frequently used options. Special characters - Option and argument values which contain problematic characters should - be escaped with double quotes, backslashes, or (best) single quotes. + Option and argument values which contain problematic characters should + be escaped with double quotes, backslashes, or (best) single quotes. Problematic characters means spaces, and also characters which are sig- - nificant to your command shell, such as less-than/greater-than. Eg: + nificant to your command shell, such as less-than/greater-than. Eg: hledger register -p 'last year' "accounts receivable (receiv- able|payable)" amt:\>100. - Characters which are significant both to the shell and in regular - expressions sometimes need to be double-escaped. These include paren- - theses, the pipe symbol and the dollar sign. Eg, to match the dollar - symbol, bash users should do: hledger balance cur:'\$' or hledger bal- + Characters which are significant both to the shell and in regular + expressions sometimes need to be double-escaped. These include paren- + theses, the pipe symbol and the dollar sign. Eg, to match the dollar + symbol, bash users should do: hledger balance cur:'\$' or hledger bal- ance cur:\\$. When hledger is invoking an addon executable (like hledger-ui), options and arguments get de-escaped once more, so you might need triple-escap- - ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The - number of backslashes in fish shell is left as an exercise for the + ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The + number of backslashes in fish shell is left as an exercise for the reader.) - Inside a file used for argument expansion, one less level of escaping - is enough. (And in this case, backslashes seem to work better than + Inside a file used for argument expansion, one less level of escaping + is enough. (And in this case, backslashes seem to work better than quotes. Eg: cur:\$). If in doubt, keep things simple: @@ -273,7 +274,7 @@ Input files hledger reads transactions from a data file (and the add command writes to it). By default this file is $HOME/.hledger.journal (or on Windows, - something like C:/Users/USER/.hledger.journal). You can override this + something like C:/Users/USER/.hledger.journal). You can override this with the $LEDGER_FILE environment variable: $ setenv LEDGER_FILE ~/finance/2016.journal @@ -287,9 +288,9 @@ $ cat some.journal | hledger -f- - Usually the data file is in hledger's journal format, but it can also - be one of several other formats, listed below. hledger detects the - format automatically based on the file extension, or if that is not + Usually the data file is in hledger's journal format, but it can also + be one of several other formats, listed below. hledger detects the + format automatically based on the file extension, or if that is not recognised, by trying each built-in "reader" in turn: @@ -297,15 +298,15 @@ ----------------------------------------------------------------------------- journal hledger's journal format, also .journal .j .hledger some Ledger journals .ledger - timeclock timeclock files (precise time .timeclock + timeclock timeclock files (precise time .timeclock logging) - timedot timedot files (approximate time .timedot + timedot timedot files (approximate time .timedot logging) - csv comma-separated values (data .csv + csv comma-separated values (data .csv interchange) - If needed (eg to ensure correct error messages when a file has the - "wrong" extension), you can force a specific reader/format by prepend- + If needed (eg to ensure correct error messages when a file has the + "wrong" extension), you can force a specific reader/format by prepend- ing it to the file path with a colon. Examples: $ hledger -f csv:/some/csv-file.dat stats @@ -316,7 +317,7 @@ o directives in one file will not affect the other files - o balance assertions will not see any account balances from previous + o balance assertions will not see any account balances from previous files If you need those, either use the include directive, or concatenate the @@ -324,8 +325,8 @@ Smart dates hledger's user interfaces accept a flexible "smart date" syntax (unlike - dates in the journal file). Smart dates allow some english words, can - be relative to today's date, and can have less-significant date parts + dates in the journal file). Smart dates allow some english words, can + be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). Examples: @@ -333,10 +334,12 @@ 2009/1/1, 2009/01/01, simple dates, several sep- 2009-1-1, 2009.1.1 arators allowed - 2009/1, 2009 same as above - a missing + + + 2009/1, 2009 same as above - a missing day or month defaults to 1 - 1/1, january, jan, relative dates, meaning - this year january 1 of the current + 1/1, january, jan, relative dates, meaning + this year january 1 of the current year next year january 1 of next year this month the 1st of the current @@ -348,16 +351,16 @@ today, yesterday, tomorrow Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these - accept the smart date syntax. One important thing to be aware of when - specifying end dates: as in Ledger, end dates are exclusive, so you + accept the smart date syntax. One important thing to be aware of when + specifying end dates: as in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. Examples: @@ -367,10 +370,10 @@ 2016 -e 12/1 end at the start of decem- ber 1st of the current - year (11/30 will be the + year (11/30 will be the last date included) - -b thismonth all transactions on or - after the 1st of the cur- + -b thismonth all transactions on or + after the 1st of the cur- rent month -p thismonth all transactions in the current month @@ -382,24 +385,24 @@ Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report intervals can not be specified with a query, currently. Period expressions - The -p/--period option accepts period expressions, a shorthand way of - expressing a start date, end date, and/or report interval all at once. + The -p/--period option accepts period expressions, a shorthand way of + expressing a start date, end date, and/or report interval all at once. - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as exclusive: -p "from 2009/1/1 to 2009/4/1" - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: @@ -407,7 +410,7 @@ -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: @@ -423,25 +426,25 @@ 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -p "2009/1" the month of jan; equiva- lent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" just that day; equivalent + -p "2009/1/1" just that day; equivalent to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval - expression. The basic report intervals are daily, weekly, monthly, + The argument of -p can also begin with, or be, a report interval + expression. The basic report intervals are daily, weekly, monthly, quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or - -Y flags. Between report interval and start/end dates (if any), the + -Y flags. Between report interval and start/end dates (if any), the word in is optional. Examples: @@ -449,26 +452,23 @@ -p "monthly in 2008" -p "quarterly" - Note that weekly, monthly, quarterly and yearly intervals will always + Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period + will end on the last day of same period, even if associated period expression specifies different explicit start and end date. For example: -p "weekly from 2009/1/1 to 2009/4/1" - - starts on 2008/12/29, closest preceed- + starts on 2008/12/29, closest preceed- ing Monday - -p "monthly in 2008/11/25" - starts on + -p "monthly in 2008/11/25" - starts on 2018/11/01 - - - -p "quar- terly from 2009-05-05 to 2009-06-01" - - starts on 2009/04/01, ends on - 2009/06/30, which are first and last + starts on 2009/04/01, ends on + 2009/06/30, which are first and last days of Q2 2009 -p "yearly from 2009-12-29" - starts on 2009/01/01, first day of 2009 @@ -477,7 +477,7 @@ biweekly, bimonthly, every day|week|month|quarter|year, every N days|weeks|months|quarters|years. - All of these will start on the first day of the requested period and + All of these will start on the first day of the requested period and end on the last one, as described above. Examples: @@ -486,13 +486,13 @@ -p "bimonthly from 2008" - periods will have boundaries on 2008/01/01, 2008/03/01, ... - -p "every 2 weeks" - starts on closest + -p "every 2 weeks" - starts on closest preceeding Monday -p "every 5 month from 2009/03" - peri- ods will have boundaries on 2009/03/01, 2009/08/01, ... - If you want intervals that start on arbitrary day of your choosing and + If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: every Nth day of week, every , every Nth day [of month], @@ -502,47 +502,47 @@ Examples: - -p "every 2nd day of week" - periods + -p "every 2nd day of week" - periods will go from Tue to Tue -p "every Tue" - same -p "every 15th day" - period boundaries will be on 15th of each month - -p "every 2nd Monday" - period bound- - aries will be on second Monday of each + -p "every 2nd Monday" - period bound- + aries will be on second Monday of each month - -p "every 11/05" - yearly periods with + -p "every 11/05" - yearly periods with boundaries on 5th of Nov -p "every 5th Nov" - same -p "every Nov 5th" - same - Show historical balances at end of 15th each month (N is exclusive end + Show historical balances at end of 15th each month (N is exclusive end date): hledger balance -H -p "every 16th day" - Group postings from start of wednesday to end of next tuesday (N is + Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date): hledger register checking -p "every 3rd day of week" Depth limiting With the --depth N option (short form: -N), commands like account, bal- - ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less - detail. This flag has the same effect as a depth: query argument (so + ance and register will show only the uppermost accounts in the account + tree, down to level N. Use this when you want a summary with less + detail. This flag has the same effect as a depth: query argument (so -2, --depth=2 or depth:2 are basically equivalent). Pivoting Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD can be: code, description, payee, note, or the full name (case insensi- tive) of any tag. As with account names, values containing colon:sepa- rated:parts will be displayed hierarchically in reports. - --pivot is a general option affecting all reports; you can think of + --pivot is a general option affecting all reports; you can think of hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on + every posting's account name with the value of the specified field on that posting, inheriting it from the transaction or using a blank value if it's not present. @@ -568,7 +568,7 @@ -------------------- 0 - One way to show only amounts with a member: value (using a query, + One way to show only amounts with a member: value (using a query, described below): $ hledger balance --pivot member tag:member=. @@ -576,7 +576,7 @@ -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -585,17 +585,17 @@ -2 EUR Cost - The -B/--cost flag converts amounts to their cost at transaction time, + The -B/--cost flag converts amounts to their cost at transaction time, if they have a transaction price specified. Market value - The -V/--value flag converts reported amounts to their current market - value. Specifically, when there is a market price (P directive) for - the amount's commodity, dated on or before today's date (or the report - end date if specified), the amount will be converted to the price's + The -V/--value flag converts reported amounts to their current market + value. Specifically, when there is a market price (P directive) for + the amount's commodity, dated on or before today's date (or the report + end date if specified), the amount will be converted to the price's commodity. - When there are multiple applicable P directives, -V chooses the most + When there are multiple applicable P directives, -V chooses the most recent one, or in case of equal dates, the last-parsed one. For example: @@ -627,14 +627,31 @@ $ hledger -f t.j bal euros -V -e 2016/12/21 $103.00 assets:euros - Currently, hledger's -V only uses market prices recorded with P direc- + Currently, hledger's -V only uses market prices recorded with P direc- tives, not transaction prices (unlike Ledger). Combining -B and -V - Using -B/-cost and -V/-value together is currently allowed, but the + Using -B/-cost and -V/-value together is currently allowed, but the results are probably not meaningful. Let us know if you find a use for this. + Output destination + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- + trolled by the -o/--output-file option. + + $ hledger balance -o - # write to stdout (the default) + $ hledger balance -o FILE # write to FILE + + Output format + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or + HTML. This is controlled by the -O/--output-format option, or by spec- + ifying a .csv or .html file extension with -o/--output-file. + + $ hledger balance -O csv # write CSV to stdout + $ hledger balance -o FILE.csv # write CSV to FILE.csv + Regular expressions hledger uses regular expressions in a number of places: @@ -806,22 +823,25 @@ accounts Show account names. Alias: a. - --tree show short account names, as a tree + --declared + show account names declared with account directives + --used show account names posted to by transactions + + --tree show short account names and their parents, as a tree + --flat show full account names, as a list (default) --drop=N in flat mode: omit N leading account name parts - This command lists all account names that are in use (ie, all the - accounts which have at least one transaction posting to them). With - query arguments, only matched account names are shown. - - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. - - In flat mode you can add --drop N to omit the first few account name - components. + This command lists account names, either declared with account direc- + tives (-declared), posted to (-used), or both (default). With query + arguments, only matched account names and account names referenced by + matched postings are shown. It shows a flat list by default. With + --tree, it uses indentation to show the account hierarchy. In flat + mode you can add --drop N to omit the first few account name compo- + nents. Account names can be depth-clipped with --depth N or depth:N. Examples: @@ -984,7 +1004,7 @@ in single-column balance reports: use this custom line format -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv. + select the output format. Supported formats: txt, csv, html. -o FILE --output-file=FILE write output to FILE. A file extension matching one of the @@ -994,10 +1014,13 @@ use unicode to display prettier tables. --sort-amount - sort by amount instead of account name (in flat mode). With - multiple columns, sorts by the row total, or by row average if - that is displayed. + sort by amount instead of account code/name (in flat mode). + With multiple columns, sorts by the row total, or by row average + if that is displayed. + --invert + display all amounts with reversed sign + --budget show performance compared to budget goals defined by periodic transactions @@ -1028,19 +1051,22 @@ ances, this is the same as the account's ending balance. By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. "Boring" accounts, which contain a single - interesting subaccount and no balance of their own, are elided into the - following line for more compact output. (Use --no-elide to prevent - this. Eliding of boring accounts is not yet supported in multicolumn - reports.) + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with + -S/--sort-amount, by their balance amount. - Each account's balance is the "inclusive" balance - it includes the - balances of any subaccounts. + "Boring" accounts, which contain a single interesting subaccount and no + balance of their own, are elided into the following line for more com- + pact output. (Not yet supported in tabular reports.) Use --no-elide to + prevent this. - Accounts which have zero balance (and no non-zero subaccounts) are + Account balances are "inclusive" - they include the balances of any + subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it: $ hledger balance -p 2008/6 expenses --no-total @@ -1050,9 +1076,9 @@ Flat mode To see a flat list of full account names instead of the default hierar- - chical display, use --flat. In this mode, accounts (unless + chical display, use --flat. In this mode, accounts (unless depth-clipped) show their "exclusive" balance, excluding any subaccount - balances. In this mode, you can also use --drop N to omit the first + balances. In this mode, you can also use --drop N to omit the first few account name components. $ hledger balance -p 2008/6 expenses -N --flat --drop 1 @@ -1060,9 +1086,9 @@ $1 supplies Depth limited balance reports - With --depth N, balance shows accounts only to the specified depth. - This is very useful to show a complex charts of accounts in less - detail. In flat mode, balances from accounts below the depth limit + With --depth N, balance shows accounts only to the specified depth. + This is very useful to show a complex charts of accounts in less + detail. In flat mode, balances from accounts below the depth limit will be shown as part of a parent account at the depth limit. $ hledger balance -N --depth 1 @@ -1072,12 +1098,12 @@ $1 liabilities Multicolumn balance reports - With a reporting interval, multiple balance columns will be shown, one - for each report period. There are three types of multi-column balance + With a reporting interval, multiple balance columns will be shown, one + for each report period. There are three types of multi-column balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -1092,8 +1118,8 @@ -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1109,8 +1135,8 @@ || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1126,26 +1152,26 @@ ----------------------++------------------------------------- || 0 0 0 - Multi-column balance reports display accounts in flat mode by default; + Multi-column balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: - first, the report will show all columns within the specified report - period (without -E, leading and trailing columns with all zeroes are - not shown). Second, all accounts which existed at the report start - date will be considered, not just the ones with activity during the + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report + period (without -E, leading and trailing columns with all zeroes are + not shown). Second, all accounts which existed at the report start + date will be considered, not just the ones with activity during the report period (use -E to include low-activity accounts which would oth- erwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1167,13 +1193,13 @@ # Average is rounded to the dollar here since all journal amounts are Budgets - With --budget and a report interval, all periodic transactions in your - journal with that interval, active during the requested report period, - are interpreted as recurring budget goals for the specified accounts - (and subaccounts), and the report will show the difference between + With --budget and a report interval, all periodic transactions in your + journal with that interval, active during the requested report period, + are interpreted as recurring budget goals for the specified accounts + (and subaccounts), and the report will show the difference between actual and budgeted balances. - For example, you can take average monthly expenses in the common + For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ;; Budget @@ -1232,8 +1258,8 @@ -----------------------++------------------------------------------------- || 0 0 - Accounts with no budget goals (not mentioned in the periodic transac- - tions) will be aggregated under , unless you add the + Accounts with no budget goals (not mentioned in the periodic transac- + tions) will be aggregated under , unless you add the --show-unbudgeted flag to display them normally: $ hledger balance --budget --show-unbudgeted @@ -1251,11 +1277,15 @@ ----------------------++------------------------------------------------- || 0 0 - For more examples and details, see Budgeting and Forecasting. + Note -budget first arrived in hledger in 1.5 and is still pretty young; + join the discussions on mail list and issue tracker to help us refine + it. + For more examples, see Budgeting and Forecasting. + Custom balance output - In simple (non-multi-column) balance reports, you can customise the - output with --format FMT: + You can customise the layout of simple (non-tabular) balance reports + with --format FMT: $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -1272,7 +1302,7 @@ 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1283,14 +1313,14 @@ o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1299,7 +1329,7 @@ o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no + There are some quirks. Eg in one-line mode, %(depth_spacer) has no effect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. @@ -1307,16 +1337,19 @@ o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report + This command also supports output destination and output format selec- + tion. + Colour support The balance command shows negative amounts in red, if: @@ -1324,32 +1357,21 @@ o the output is not being redirected or piped anywhere - Output destination - The balance, print, register and stats commands can write their output - to a destination other than the console. This is controlled by the - -o/--output-file option. - - $ hledger balance -o - # write to stdout (the default) - $ hledger balance -o FILE # write to FILE - - CSV output - The balance, print and register commands can write their output as CSV. - This is useful for exporting data to other applications, eg to make - charts in a spreadsheet. This is controlled by the -O/--output-format - option, or by specifying a .csv file extension with -o/--output-file. - - $ hledger balance -O csv # write CSV to stdout - $ hledger balance -o FILE.csv # write CSV to FILE.csv - balancesheet - Show a balance sheet. Alias: bs. + This command displays a simple balance sheet, showing historical ending + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). Note + this report shows all account balances with normal positive sign (like + conventional financial statements, unlike balance/print/register) + (experimental). (bs) --change show balance change in each period, instead of historical ending balances --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of historical ending balances -H --historical @@ -1381,11 +1403,9 @@ in single-column balance reports: use this custom line format --sort-amount - sort by amount instead of account name + sort by amount instead of account code/name - This command displays a simple balance sheet. It currently assumes - that you have top-level accounts named asset and liability (plural - forms also allowed.) + Example: $ hledger balancesheet Balance Sheet @@ -1407,21 +1427,19 @@ 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. - balancesheetequity - Show a balance sheet including equity. Alias: bse. + This command also supports output destination and output format selec- + tion. - Other than showing the equity accounts, this command is exactly the - same as the command balancesheet. Please refer to it for the available - options. + balancesheetequity + Just like balancesheet, but also reports Equity (which it assumes is + under a top-level equity account). - This command displays a balancesheet. It currently assumes that you - have top-level accounts named asset, liability and equity (plural forms - also allowed.) + Example: $ hledger balancesheetequity Balance Sheet With Equity @@ -1448,7 +1466,12 @@ 0 cashflow - Show a cashflow statement. Alias: cf. + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all + account balances with normal positive sign (like conventional financial + statements, unlike balance/print/register) (experimental). (cf) --change show balance change in each period (default) @@ -1486,12 +1509,9 @@ in single-column balance reports: use this custom line format --sort-amount - sort by amount instead of account name + sort by amount instead of account code/name - This command displays a simple cashflow statement It shows the change - in all "cash" (ie, liquid assets) accounts for the period. It cur- - rently assumes that cash accounts are under a top-level account named - asset and do not contain receivable, :A/R or :fixed. + Example: $ hledger cashflow Cashflow Statement @@ -1508,10 +1528,13 @@ $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. + This command also supports output destination and output format selec- + tion. + check-dates Check that transactions are sorted by increasing date. With a query, only matched transactions' dates are checked. @@ -1520,10 +1543,12 @@ Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger-dupes.html - equity + close Print closing/opening transactions that bring some or all account bal- - ances to zero and back. Can be useful for bringing account balances - across file boundaries. + ances to zero and back. Can be useful for bringing asset/liability + balances across file boundaries, or for closing out income/expenses for + a period. This was formerly called "equity", as in Ledger, and that + alias is also accepted. See close -help for more. help Show any of the hledger manuals. @@ -1578,13 +1603,18 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions incomestatement - Show an income statement. Alias: is. + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, + unlike balance/print/register) (experimental). (is) --change show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1616,10 +1646,10 @@ in single-column balance reports: use this custom line format --sort-amount - sort by amount instead of account name + sort by amount instead of account code/name - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1644,10 +1674,13 @@ 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. + This command also supports output destination and output format selec- + tion. + prices Print all market prices from the journal. @@ -1731,8 +1764,8 @@ increasing dates, and that transactions on the same day do not get reordered. See also the import command. - The print command also supports output destination and CSV output. - Here's an example of print's CSV output: + This command also supports output destination and output format selec- + tion. Here's an example of print's CSV output: $ hledger print -Ocsv "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" @@ -1885,8 +1918,8 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - The register command also supports the -o/--output-file and -O/--out- - put-format options for controlling output destination and CSV output. + This command also supports output destination and output format selec- + tion. register-match Print the one posting whose transaction description is closest to DESC, @@ -1919,8 +1952,8 @@ or a matched part of it. With a reporting interval, it shows a report for each report period. - The stats command also supports -o/--output-file for controlling output - destination. + This command also supports output destination and output format selec- + tion. tags List all the tag names used in the journal. With a TAGREGEX argument, @@ -2010,9 +2043,6 @@ data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. - budget - hledger-budget.hs adds more budget-tracking features to hledger. - chart hledger-chart.hs is an old pie chart generator, in need of some love. @@ -2135,4 +2165,4 @@ -hledger 1.5 December 2017 hledger(1) +hledger 1.9 March 2018 hledger(1)