diff --git a/.otherdocs/hledger-api.1 b/.otherdocs/hledger-api.1 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-api.1 @@ -0,0 +1,122 @@ + +.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-api.info @@ -0,0 +1,70 @@ +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-api.txt @@ -0,0 +1,105 @@ + +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-ui.1 @@ -0,0 +1,485 @@ + +.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-ui.info @@ -0,0 +1,394 @@ +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-ui.txt @@ -0,0 +1,386 @@ + +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-web.1 @@ -0,0 +1,326 @@ + +.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-web.info @@ -0,0 +1,214 @@ +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger-web.txt @@ -0,0 +1,250 @@ + +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger_csv.5 @@ -0,0 +1,334 @@ + +.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/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.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/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.5 December 2017 hledger_csv(5) diff --git a/.otherdocs/hledger_journal.5 b/.otherdocs/hledger_journal.5 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger_journal.5 @@ -0,0 +1,1249 @@ +.\"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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger_journal.info @@ -0,0 +1,1235 @@ +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger_journal.txt @@ -0,0 +1,918 @@ + +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 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger_timeclock.5 @@ -0,0 +1,92 @@ + +.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/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.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/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.5 December 2017 hledger_timeclock(5) diff --git a/.otherdocs/hledger_timedot.5 b/.otherdocs/hledger_timedot.5 new file mode 100644 --- /dev/null +++ b/.otherdocs/hledger_timedot.5 @@ -0,0 +1,154 @@ + +.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/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.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 new file mode 100644 --- /dev/null +++ b/.otherdocs/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.5 December 2017 hledger_timedot(5) diff --git a/CHANGES b/CHANGES --- a/CHANGES +++ b/CHANGES @@ -1,5 +1,31 @@ -User-visible changes in the hledger and hledger-lib packages. -See also the project change log. +User-visible changes in the hledger CLI tool. See also hledger-lib. + + +# 1.5 (2017/12/31) + +* --auto adds Ledger-style automated postings to transactions (Dmitry Astapov, Mykola Orliuk) + +* --forecast generates Ledger-style periodic transactions in the future (Dmitry Astapov, Mykola Orliuk) + +* -V/--value uses today's market prices by default, not those of last transaction date. #683, #648 + +* add: suggest implied (parent) and declared (by account directives) account names also + +* bal: --budget shows performance compared to budget goals defined + with periodic transactions. Accounts with budget goals are + displayed folded (depth-clipped) at a depth matching the budget + specification. Unbudgeted accounts are hidden, or with + --show-unbudgeted, shown at their usual depth. (Dmitry Astapov) + +* import: the output of --dry-run is now valid journal format + +* print: -B shows converted amounts again, as in 1.1, even without + -x. #551 (Mykola Orliuk, Simon Michael) + +* tag: the first argument now filters tag names, additional arguments + filter transactions (#261) + +* remove upper bounds on all but hledger* and base (experimental) # 1.4 (2017/9/30) diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs --- a/Hledger/Cli/CliOptions.hs +++ b/Hledger/Cli/CliOptions.hs @@ -155,6 +155,8 @@ ,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden" ,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" + ,flagNone ["forecast"] (setboolopt "forecast") "apply periodic transaction rules to generate future transactions, to 6 months from now or report end date" ] -- | Common output-related flags: --output-file, --output-format... 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 @@ -262,7 +262,7 @@ flip evalState esJournal $ runParserT (accountnamep <* eof) "" (T.pack s) -- otherwise, try to parse the input as an accountname where validateAccount :: Text -> Maybe Text - validateAccount t | no_new_accounts_ esOpts && not (t `elem` journalAccountNames esJournal) = Nothing + validateAccount t | no_new_accounts_ esOpts && not (t `elem` journalAccountNamesDeclaredOrImplied esJournal) = Nothing | otherwise = Just t dbg1 = id -- strace @@ -337,7 +337,7 @@ descriptionCompleter j = completer (map T.unpack $ journalDescriptions j) accountCompleter :: Journal -> String -> CompletionFunc IO -accountCompleter j = completer (map T.unpack $ journalAccountNamesUsed j) +accountCompleter j = completer (map T.unpack $ journalAccountNamesDeclaredOrImplied j) amountCompleter :: String -> CompletionFunc IO amountCompleter = completer [] 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 @@ -246,11 +246,13 @@ ,tests_Hledger_Cli_Commands_Balance ) where -import Data.List (intercalate) +import Data.List (intercalate, nub) import Data.Maybe +import qualified Data.Map as Map -- import Data.Monoid import qualified Data.Text as T import System.Console.CmdArgs.Explicit as C +import Data.Decimal (roundTo) import Text.CSV import Test.HUnit import Text.Printf (printf) @@ -281,8 +283,10 @@ ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)" ,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 ["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 ["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" ] ++ outputflags ,groupHidden = [] @@ -293,7 +297,7 @@ -- | The balance command, prints a balance report. balance :: CliOpts -> Journal -> IO () -balance opts@CliOpts{reportopts_=ropts} j = do +balance opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do d <- getCurrentDay case lineFormatFromOpts ropts of Left err -> error' $ unlines [err] @@ -319,13 +323,59 @@ "csv" -> \ropts r -> (++ "\n") $ printCSV $ balanceReportAsCsv ropts r _ -> balanceReportAsText writeOutput opts $ render ropts report - _ -> do + + _ | boolopt "budget" rawopts -> do + let budget = budgetJournal opts j + j' = budgetRollUp opts budget j + report = multiBalanceReport ropts (queryFromOpts d ropts) j' + budgetReport = multiBalanceReport ropts (queryFromOpts d ropts) budget + render = case format of + -- XXX: implement csv rendering + "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv ropts + _ -> multiBalanceReportWithBudgetAsText ropts budgetReport + writeOutput opts $ render report + + | otherwise -> do let report = multiBalanceReport ropts (queryFromOpts d ropts) j render = case format of - "csv" -> \ropts r -> (++ "\n") $ printCSV $ multiBalanceReportAsCsv ropts r - _ -> multiBalanceReportAsText - writeOutput opts $ render ropts report + "csv" -> (++ "\n") . printCSV . multiBalanceReportAsCsv 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 +budgetRollUp :: CliOpts -> Journal -> Journal -> Journal +budgetRollUp CliOpts{rawopts_=rawopts} budget j = j { jtxns = remapTxn <$> jtxns j } + where + budgetAccounts = nub $ concatMap (map paccount . ptpostings) $ jperiodictxns budget + remapAccount origAcctName = remapAccount' origAcctName + where + remapAccount' acctName + | acctName `elem` budgetAccounts = acctName + | otherwise = + case parentAccountName acctName of + "" | boolopt "show-unbudgeted" rawopts -> origAcctName + | otherwise -> T.append (T.pack ":") acctName + 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 } + 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" } + journalBalanceTransactions' opts j = + let assrt = not . ignore_assertions_ $ inputopts_ opts + in + either error' id $ journalBalanceTransactions assrt j + + -- single-column balance reports -- | Find the best commodity to convert to when asked to show the @@ -494,16 +544,78 @@ 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 + where + tabl = combine (balanceReportAsTable opts r) (balanceReportAsTable opts budget) + typeStr :: String + typeStr = 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 = + -- percentage of budget consumed is always computed in the cost basis + case (toCost real, 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 -> + Just $ 100 * aquantity a1 / aquantity a2 + _ -> Nothing + where + toCost = normaliseMixedAmount . costOfMixedAmount + 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' + -- | 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 (ReportOpts { pretty_tables_ = pretty, color_=usecolor }) = +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 = unlines . addtrailingblank . trimborder . lines - . render pretty id id showamt + . render pretty id id showCell . align where addtrailingblank = (++[""]) @@ -512,8 +624,6 @@ where acctswidth = maximum' $ map strWidth (headerContents l) l' = padRightWide acctswidth <$> l - showamt | usecolor = cshowMixedAmountOneLineWithoutPrice - | otherwise = showMixedAmountOneLineWithoutPrice -- | Build a 'Table' from a multi-column balance report. balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount diff --git a/Hledger/Cli/Commands/Equity.hs b/Hledger/Cli/Commands/Equity.hs --- a/Hledger/Cli/Commands/Equity.hs +++ b/Hledger/Cli/Commands/Equity.hs @@ -66,7 +66,7 @@ balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmountSquashPricesForDisplay b) acctbals ps = [posting{paccount=a ,pamount=mixed [b] - ,pbalanceassertion=Just b + ,pbalanceassertion=Just (b,nullsourcepos) } |(a,_,_,mb) <- acctbals ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb @@ -75,7 +75,7 @@ enddate = fromMaybe today $ queryEndDate (date2_ ropts_) q nps = [posting{paccount=a ,pamount=mixed [negate b] - ,pbalanceassertion=Just b{aquantity=0} + ,pbalanceassertion=Just (b{aquantity=0}, nullsourcepos) } |(a,_,_,mb) <- acctbals ,b <- amounts $ normaliseMixedAmountSquashPricesForDisplay mb diff --git a/Hledger/Cli/Commands/Import.hs b/Hledger/Cli/Commands/Import.hs --- a/Hledger/Cli/Commands/Import.hs +++ b/Hledger/Cli/Commands/Import.hs @@ -51,7 +51,7 @@ case sortBy (comparing tdate) $ jtxns newj of [] -> putStrLn "no new transactions" newts | dryrun -> do - printf "would import %d new transactions:\n\n" (length newts) + printf "; would import %d new transactions:\n\n" (length newts) -- TODO how to force output here ? -- length (jtxns newj) `seq` print' opts{rawopts_=("explicit",""):rawopts} newj mapM_ (putStr . showTransactionUnelided) newts 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 @@ -66,8 +66,15 @@ entriesReportAsText :: CliOpts -> EntriesReport -> String entriesReportAsText opts = concatMap (showTransactionUnelided . gettxn) where - gettxn | boolopt "explicit" $ rawopts_ opts = id -- use the fully inferred/explicit txn - | otherwise = originalTransaction -- use the original txn (more or less) + gettxn | useexplicittxn = id -- use the fully inferred/explicit txn + | otherwise = originalTransaction -- use the original as-written txn, more or less + -- Original vs inferred transactions/postings were causing problems here, disabling -B (#551). + -- Use the explicit one if -B or -x are active. + -- This passes tests; does it also mean -B sometimes shows missing amounts unnecessarily ? + useexplicittxn = or + [ boolopt "explicit" $ rawopts_ opts + , cost_ $ reportopts_ opts + ] -- Replace this transaction's postings with the original postings if any, but keep the -- current possibly rewritten account names. diff --git a/Hledger/Cli/Commands/Tags.hs b/Hledger/Cli/Commands/Tags.hs --- a/Hledger/Cli/Commands/Tags.hs +++ b/Hledger/Cli/Commands/Tags.hs @@ -9,26 +9,34 @@ import Data.List import Data.String.Here -import qualified Data.Text.IO as T +import qualified Data.Text as T +import Safe import Hledger import Hledger.Cli.CliOptions tagsmode = hledgerCommandMode [here| tags -List all the tag names in use. -With a query, only matched transactions' tags are shown. +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 QUERY arguments, only transactions matching the query are considered. Reads the default journal file, or another specified with -f. FLAGS |] [] -- [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] -- [generalflagsgroup1] [] - ([], Just $ argsFlag "[QUERY]") + ([], Just $ argsFlag "[TAGREGEX [QUERY...]]") -tags CliOpts{rawopts_=_rawopts,reportopts_=ropts} j = do +tags CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do d <- getCurrentDay let - q = queryFromOpts d ropts - ts = filter (q `matchesTransaction`) $ jtxns $ journalSelectingAmountFromOpts ropts j - tags = nub $ sort $ map fst $ concatMap transactionAllTags ts - mapM_ T.putStrLn tags + args = listofstringopt "args" rawopts + mtagpats = headMay args + queryargs = drop 1 args + q = queryFromOpts d $ ropts{query_ = unwords queryargs} + txns = filter (q `matchesTransaction`) $ jtxns $ journalSelectingAmountFromOpts ropts j + tags = + nub $ sort $ + (maybe id (filter . regexMatchesCI) mtagpats) $ + map (T.unpack . fst) $ concatMap transactionAllTags txns + mapM_ putStrLn tags 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 "doc/hledger.1" >>= embedStringFile) - ,$(makeRelativeToProject "doc/hledger.1.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/hledger.1.info" >>= embedStringFile) + ($(makeRelativeToProject "hledger.1" >>= embedStringFile) + ,$(makeRelativeToProject "hledger.txt" >>= embedStringFile) + ,$(makeRelativeToProject "hledger.info" >>= embedStringFile) )) ,("hledger-ui", - ($(makeRelativeToProject "doc/other/hledger-ui.1" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger-ui.1.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger-ui.1.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger-ui.1" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger-ui.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger-ui.info" >>= embedStringFile) )) ,("hledger-web", - ($(makeRelativeToProject "doc/other/hledger-web.1" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger-web.1.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger-web.1.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger-web.1" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger-web.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger-web.info" >>= embedStringFile) )) ,("hledger-api", - ($(makeRelativeToProject "doc/other/hledger-api.1" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger-api.1.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger-api.1.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger-api.1" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger-api.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger-api.info" >>= embedStringFile) )) ,("journal", - ($(makeRelativeToProject "doc/other/hledger_journal.5" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_journal.5.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_journal.5.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger_journal.5" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_journal.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_journal.info" >>= embedStringFile) )) ,("csv", - ($(makeRelativeToProject "doc/other/hledger_csv.5" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_csv.5.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_csv.5.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger_csv.5" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_csv.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_csv.info" >>= embedStringFile) )) ,("timeclock", - ($(makeRelativeToProject "doc/other/hledger_timeclock.5" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_timeclock.5.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_timeclock.5.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger_timeclock.5" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_timeclock.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_timeclock.info" >>= embedStringFile) )) ,("timedot", - ($(makeRelativeToProject "doc/other/hledger_timedot.5" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_timedot.5.txt" >>= embedStringFile) - ,$(makeRelativeToProject "doc/other/hledger_timedot.5.info" >>= embedStringFile) + ($(makeRelativeToProject ".otherdocs/hledger_timedot.5" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/hledger_timedot.txt" >>= embedStringFile) + ,$(makeRelativeToProject ".otherdocs/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 @@ -10,6 +10,9 @@ ( withJournalDo, writeOutput, + journalApplyValue, + journalAddForecast, + generateAutomaticPostings, journalReload, journalReloadIfChanged, journalFileIsNewer, @@ -31,7 +34,7 @@ import Data.Maybe import qualified Data.Text as T import qualified Data.Text.IO as T -import Data.Time (Day) +import Data.Time (Day, addDays) import Data.Word import Numeric import Safe (readMay) @@ -54,6 +57,7 @@ import Hledger.Read import Hledger.Reports import Hledger.Utils +import Hledger.Query (Query(Any)) -- | Parse the user's specified journal file, maybe apply some transformations @@ -70,6 +74,8 @@ . anonymiseByOpts opts . journalApplyAliases (aliasesFromOpts opts) <=< journalApplyValue (reportopts_ opts) + <=< journalAddForecast opts + . generateAutomaticPostings (reportopts_ opts) either error' f ej -- | Apply the pivot transformation on a journal, if option is present. @@ -103,19 +109,52 @@ where anon = T.pack . flip showHex "" . (fromIntegral :: Int -> Word32) . hash --- XXX as of since 2017/4 this is used instead of --- balanceReportValue/multiBalanceReportValue (mostly; not yet hledger-ui) +-- TODO move journalApplyValue and friends to Hledger.Data.Journal ? They are here because they use ReportOpts + -- | If -V/--value was requested, convert all journal amounts to their market value -- as of the report end date. Cf http://hledger.org/manual.html#market-value +-- Since 2017/4 we do this early, before commands run, which affects all commands +-- and seems to have the same effect as doing it last on the reported values. journalApplyValue :: ReportOpts -> Journal -> IO Journal journalApplyValue ropts j = do - mvaluedate <- reportEndDate j ropts - let convert | value_ ropts - , Just d <- mvaluedate - = overJournalAmounts (amountValue j d) - | otherwise - = id + today <- getCurrentDay + mspecifiedenddate <- specifiedEndDate ropts + let d = fromMaybe today mspecifiedenddate + convert | value_ ropts = overJournalAmounts (amountValue j d) + | otherwise = id return $ convert j + +-- | Run PeriodicTransactions from journal from today or journal end to requested end day. +-- Add generated transactions to the journal +journalAddForecast :: CliOpts -> Journal -> IO Journal +journalAddForecast opts j = do + today <- getCurrentDay + -- Create forecast starting from end of journal + 1 day, and until the end of requested reporting period + -- If end is not provided, do 180 days of forecast. + -- Note that jdatespan already returns last day + 1 + let startDate = fromMaybe today $ spanEnd (jdatespan j) + endDate = fromMaybe (addDays 180 today) $ periodEnd (period_ ropts) + dates = DateSpan (Just startDate) (Just endDate) + withForecast = [makeForecast t | pt <- jperiodictxns j, t <- runPeriodicTransaction pt dates, spanContainsDate dates (tdate t) ] ++ (jtxns j) + makeForecast t = txnTieKnot $ t { tdescription = T.pack "Forecast transaction" } + ropts = reportopts_ opts + if forecast_ ropts + then return $ journalBalanceTransactions' opts j { jtxns = withForecast } + else return j + where + journalBalanceTransactions' opts j = + let assrt = not . ignore_assertions_ $ inputopts_ opts + in + either error' id $ journalBalanceTransactions assrt j + +-- | Generate Automatic postings and add them to the current journal. +generateAutomaticPostings :: ReportOpts -> Journal -> Journal +generateAutomaticPostings ropts j = + if auto_ ropts then j { jtxns = map modifier $ jtxns j } else j + where + modifier = foldr (flip (.) . runModifierTransaction') id mtxns + runModifierTransaction' = fmap txnTieKnot . runModifierTransaction Any + mtxns = jmodifiertxns j -- | Write some output to stdout or to a file selected by --output-file. -- If the file exists it will be overwritten. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ For more, see http://hledger.org. -##Support +## Support ### Backers Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/hledger#backer)] diff --git a/doc/hledger.1 b/doc/hledger.1 deleted file mode 100644 --- a/doc/hledger.1 +++ /dev/null @@ -1,2715 +0,0 @@ -.\"t - -.TH "hledger" "1" "September 2017" "hledger 1.4" "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 -(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 -.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 expansion -.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]\@FILE\f[] in a command line. -(To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with -a \f[C]\-\-\f[] argument.) -.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\[aq]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\[aq]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: -.PP -.TS -tab(@); -lw(10.7n) lw(33.2n) lw(26.1n). -T{ -Reader: -T}@T{ -Reads: -T}@T{ -Used for file extensions: -T} -_ -T{ -\f[C]journal\f[] -T}@T{ -hledger\[aq]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 -"wrong" 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\[aq]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\[aq]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\[aq]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\[aq]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 "from" and "to" are optional, and so are the spaces, as -long as you don\[aq]t run two dates together. -"to" can also be written as "\-". -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 "from" or "to" 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 "2009/1/1 to 2010/1/1" -T} -T{ -\f[C]\-p\ "2009/1"\f[] -T}@T{ -the month of jan; equivalent to "2009/1/1 to 2009/2/1" -T} -T{ -\f[C]\-p\ "2009/1/1"\f[] -T}@T{ -just that day; equivalent to "2009/1/1 to 2009/1/2" -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 -The following more complex report intervals are also supported: -\f[C]biweekly\f[], \f[C]bimonthly\f[], -\f[C]every\ N\ days|weeks|months|quarters|years\f[], -\f[C]every\ Nth\ day\ [of\ month]\f[], -\f[C]every\ Nth\ day\ of\ week\f[]. -.PP -Examples: -.PP -.TS -tab(@); -l. -T{ -\f[C]\-p\ "bimonthly\ from\ 2008"\f[] -T} -T{ -\f[C]\-p\ "every\ 2\ weeks"\f[] -T} -T{ -\f[C]\-p\ "every\ 5\ days\ from\ 1/3"\f[] -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\[aq]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\[aq]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 "account -name"): -.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 the reported amounts to their -market value on the report end date, using the most recent applicable -market prices, when known. -Specifically, when there is a market price (P directive) for the -amount\[aq]s commodity, dated on or before the report end date (see -hledger \-> Report start & end date), the amount will be converted to -the price\[aq]s commodity. -If multiple applicable prices are defined, the latest\-dated one is used -(and if dates are equal, the one last parsed). -.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\[aq]s \-V only uses market prices recorded with P -directives, not transaction prices (unlike Ledger). -.PP -Using \-B and \-V together is allowed. -.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\[aq]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\[aq]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[C]not:\f[]\f[], eg to -exclude a particular subaccount. -.TP -.B \f[B]\f[C]REGEX\f[]\f[] -match account names by this regular expression. -(No prefix is equivalent to \f[C]acct:\f[]). -.RS -.RE -.TP -.B \f[B]\f[C]acct:REGEX\f[]\f[] -same as above -.RS -.RE -.TP -.B \f[B]\f[C]amt:N,\ amt:N,\ amt:>=N\f[]\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[C]code:REGEX\f[]\f[] -match by transaction code (eg check number) -.RS -.RE -.TP -.B \f[B]\f[C]cur:REGEX\f[]\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[C]desc:REGEX\f[]\f[] -match transaction descriptions. -.RS -.RE -.TP -.B \f[B]\f[C]date:PERIODEXPR\f[]\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[C]date2:PERIODEXPR\f[]\f[] -match secondary dates within the specified period. -.RS -.RE -.TP -.B \f[B]\f[C]depth:N\f[]\f[] -match (or display, depending on command) accounts at or above this depth -.RS -.RE -.TP -.B \f[B]\f[C]note:REGEX\f[]\f[] -match transaction notes (part of description right of \f[C]|\f[], or -whole description when there\[aq]s no \f[C]|\f[]) -.RS -.RE -.TP -.B \f[B]\f[C]payee:REGEX\f[]\f[] -match transaction payee/payer names (part of description left of -\f[C]|\f[], or whole description when there\[aq]s no \f[C]|\f[]) -.RS -.RE -.TP -.B \f[B]\f[C]real:,\ real:0\f[]\f[] -match real or virtual postings respectively -.RS -.RE -.TP -.B \f[B]\f[C]status:,\ status:!,\ status:*\f[]\f[] -match unmarked, pending, or cleared transactions respectively -.RS -.RE -.TP -.B \f[B]\f[C]tag:REGEX[=REGEX]\f[]\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[C]inacct:ACCTNAME\f[]\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]\-\-tree\f[] -show short account names, 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 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 -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. -.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\[aq]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\[aq]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\[aq]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. -.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 (total row amount, or by average if that is displayed), -instead of account name (in flat mode) -.RS -.RE -.PP -The balance command displays accounts and balances. -It is hledger\[aq]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\[aq]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\[aq]s -ending balance. -.PP -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 \f[C]\-\-no\-elide\f[] to prevent this. -Eliding of boring accounts is not yet supported in multicolumn reports.) -.PP -Each account\[aq]s balance is the "inclusive" balance \- it includes 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 "exclusive" -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\[aq]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 "full" 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\[aq]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 Custom balance output -.PP -In simple (non\-multi\-column) balance reports, you can customise the -output 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\[aq]s -depth, or if MIN is specified, MIN * depth spaces. -.IP \[bu] 2 -\f[C]account\f[] \- the account\[aq]s name -.IP \[bu] 2 -\f[C]total\f[] \- the account\[aq]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\[aq]s total -.IP \[bu] 2 -\f[C]%\-20.20(account)\f[] \- the account\[aq]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 -.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 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. -.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\[aq]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\[aq]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 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.) -.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. -.SS balancesheetequity -.PP -Show a balance sheet including equity. -Alias: bse. -.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. -.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.) -.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 -Show a cashflow statement. -Alias: 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\[aq]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\[aq]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 name -.RS -.RE -.PP -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 \f[C]asset\f[] and do not contain \f[C]receivable\f[], -\f[C]:A/R\f[] or \f[C]:fixed\f[]. -.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[]. -.SS check\-dates -.PP -Check that transactions are sorted by increasing date. -With a query, only matched transactions\[aq] 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 equity -.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. -.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 -Input files are provided as arguments, or glob patterns. -So eg to add new transactions from all CSV files to the main journal: -hledger import *.csv -.PP -New transactions are detected like print \-\-new (using .latest.FILE -state files). -.SS incomestatement -.PP -Show an income statement. -Alias: 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\[aq]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\[aq]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 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[]. -.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\[aq]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\[aq]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. -.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 -The print command also supports output destination and CSV output. -Here\[aq]s an example of print\[aq]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\[aq]s -fields repeated. -.IP \[bu] 2 -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.) -.IP \[bu] 2 -The amount is separated into "commodity" (the symbol) and "amount" -(numeric quantity) fields. -.IP \[bu] 2 -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.) -.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 -\-\-empty) -.RS -.RE -.TP -.B \f[C]\-r\ \-\-related\f[] -show postings\[aq] 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\[aq]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\[aq]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 -\-\-width\[aq]s argument, comma\-separated: \f[C]\-\-width\ W,D\f[] . -Here\[aq]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 -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. -.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 -The stats command also supports \f[C]\-o/\-\-output\-file\f[] for -controlling output destination. -.SS tags -.PP -List all the tag names in use. -.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\[aq]s built\-in unit tests and displays a -quick report. -With a regular expression argument, it selects only tests with matching -names. -It\[aq]s mainly used in development, but it\[aq]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\[aq]s help, while -\f[C]hledger\ web\ \-h\f[] shows hledger\-web\[aq]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\[aq]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\[aq]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 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. -.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\[aq]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 "No command \[aq]hledger\[aq] -found"\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\[aq]s an explanation. -.PP -\f[B]"Illegal byte sequence" or "Invalid or incomplete multibyte or wide -character" 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\[aq]m not sure yet). -.PP -Here\[aq]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\[aq]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/doc/hledger.1.info b/doc/hledger.1.info deleted file mode 100644 --- a/doc/hledger.1.info +++ /dev/null @@ -1,2341 +0,0 @@ -This is hledger.1.info, produced by makeinfo version 6.0 from stdin. - - -File: hledger.1.info, Node: Top, Next: EXAMPLES, Up: (dir) - -hledger(1) hledger 1.4 -********************** - -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.1.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.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top - -2 OPTIONS -********* - -* Menu: - -* General options:: -* Command options:: -* Command arguments:: -* Argument expansion:: -* Special characters:: -* Input files:: -* Smart dates:: -* Report start & end date:: -* Report intervals:: -* Period expressions:: -* Depth limiting:: -* Pivoting:: -* Cost:: -* Market value:: -* Regular expressions:: - - -File: hledger.1.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 - (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) - - 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.1.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.1.info, Node: Command arguments, Next: Argument expansion, 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.1.info, Node: Argument expansion, Next: Special characters, Prev: Command arguments, Up: OPTIONS - -2.4 Argument expansion -====================== - -You can save a set of command line options/arguments in a file, one per -line, and then reuse them by writing '@FILE' in a command line. (To -prevent this expansion of '@'-arguments, precede them with a '--' -argument.) - - -File: hledger.1.info, Node: Special characters, Next: Input files, Prev: Argument expansion, 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.1.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.1.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.1.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.1.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.1.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"' - - The following more complex report intervals are also supported: -'biweekly', 'bimonthly', 'every N days|weeks|months|quarters|years', -'every Nth day [of month]', 'every Nth day of week'. - - Examples: - -'-p "bimonthly from 2008"' -'-p "every 2 weeks"' -'-p "every 5 days from 1/3"' - - 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.1.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.1.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.1.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.1.info, Node: Market value, Next: Regular expressions, Prev: Cost, Up: OPTIONS - -2.14 Market value -================= - -The '-V/--value' flag converts the reported amounts to their market -value on the report end date, using the most recent applicable market -prices, when known. Specifically, when there is a market price (P -directive) for the amount's commodity, dated on or before the report end -date (see hledger -> Report start & end date), the amount will be -converted to the price's commodity. If multiple applicable prices are -defined, the latest-dated one is used (and if dates are equal, the one -last parsed). - - 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). - - Using -B and -V together is allowed. - - -File: hledger.1.info, Node: Regular expressions, Prev: Market value, Up: OPTIONS - -2.15 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.1.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.1.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:: -* equity:: -* help:: -* import:: -* incomestatement:: -* prices:: -* print:: -* print-unique:: -* register:: -* register-match:: -* rewrite:: -* stats:: -* tags:: -* test:: - - -File: hledger.1.info, Node: accounts, Next: activity, Up: COMMANDS - -4.1 accounts -============ - -Show account names. Alias: a. - -'--tree' - - show short account names, 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. - - 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.1.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.1.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.1.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. -'-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 (total row amount, or by average if that is - displayed), instead of account name (in flat mode) - - 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. "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.) - - Each account's balance is the "inclusive" balance - it includes 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:: -* Custom balance output:: -* Colour support:: -* Output destination:: -* CSV output:: - - -File: hledger.1.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.1.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.1.info, Node: Multicolumn balance reports, Next: Custom balance output, 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.1.info, Node: Custom balance output, Next: Colour support, Prev: Multicolumn balance reports, Up: balance - -4.4.4 Custom balance output ---------------------------- - -In simple (non-multi-column) balance reports, you can customise the -output 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 - - -File: hledger.1.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance - -4.4.5 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.1.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance - -4.4.6 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.1.info, Node: CSV output, Prev: Output destination, Up: balance - -4.4.7 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.1.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS - -4.5 balancesheet -================ - -Show a balance sheet. Alias: 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 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.) - -$ 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. - - -File: hledger.1.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. - - This command displays a balancesheet. It currently assumes that you -have top-level accounts named 'asset', 'liability' and 'equity' (plural -forms also allowed.) - -$ 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.1.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS - -4.7 cashflow -============ - -Show a cashflow statement. Alias: 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 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'. - -$ 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'. - - -File: hledger.1.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.1.info, Node: check-dupes, Next: equity, 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.1.info, Node: equity, Next: help, Prev: check-dupes, Up: COMMANDS - -4.10 equity -=========== - -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. - - -File: hledger.1.info, Node: help, Next: import, Prev: equity, 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.1.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 - - Input files are provided as arguments, or glob patterns. So eg to -add new transactions from all CSV files to the main journal: hledger -import *.csv - - New transactions are detected like print -new (using .latest.FILE -state files). - - -File: hledger.1.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS - -4.13 incomestatement -==================== - -Show an income statement. Alias: 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 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'. - - -File: hledger.1.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS - -4.14 prices -=========== - -Print all market prices from the journal. - - -File: hledger.1.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. - - 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. - - The print command also supports output destination and CSV output. -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.1.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.1.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.1.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 - - The register command also supports the '-o/--output-file' and -'-O/--output-format' options for controlling output destination and CSV -output. - - -File: hledger.1.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.1.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.1.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. - - The stats command also supports '-o/--output-file' for controlling -output destination. - - -File: hledger.1.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS - -4.21 tags -========= - -List all the tag names in use. - - -File: hledger.1.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.1.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.1.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.1.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.1.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.1.info, Node: web, Prev: ui, Up: Official add-ons - -5.1.3 web ---------- - -hledger-web provides a simple web interface. - - -File: hledger.1.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.1.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.1.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.1.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.1.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.1.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:: -* budget:: -* chart:: -* check:: - - -File: hledger.1.info, Node: autosync, Next: budget, 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.1.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.1.info, Node: chart, Next: check, Prev: budget, Up: Experimental add-ons - -5.3.3 chart ------------ - -hledger-chart.hs is an old pie chart generator, in need of some love. - - -File: hledger.1.info, Node: check, Prev: chart, Up: Experimental add-ons - -5.3.4 check ------------ - -hledger-check.hs checks more powerful account balance assertions. - - -Tag Table: -Node: Top70 -Node: EXAMPLES1886 -Ref: #examples1988 -Node: OPTIONS3634 -Ref: #options3738 -Node: General options4042 -Ref: #general-options4169 -Node: Command options6488 -Ref: #command-options6641 -Node: Command arguments7039 -Ref: #command-arguments7199 -Node: Argument expansion7320 -Ref: #argument-expansion7485 -Node: Special characters7704 -Ref: #special-characters7863 -Node: Input files9282 -Ref: #input-files9420 -Node: Smart dates11383 -Ref: #smart-dates11526 -Node: Report start & end date12505 -Ref: #report-start-end-date12677 -Node: Report intervals13743 -Ref: #report-intervals13908 -Node: Period expressions14309 -Ref: #period-expressions14471 -Node: Depth limiting16811 -Ref: #depth-limiting16957 -Node: Pivoting17299 -Ref: #pivoting17419 -Node: Cost19095 -Ref: #cost19205 -Node: Market value19323 -Ref: #market-value19460 -Node: Regular expressions20760 -Ref: #regular-expressions20898 -Node: QUERIES22259 -Ref: #queries22363 -Node: COMMANDS26330 -Ref: #commands26444 -Node: accounts27427 -Ref: #accounts27527 -Node: activity28520 -Ref: #activity28632 -Node: add28991 -Ref: #add29092 -Node: balance31750 -Ref: #balance31863 -Node: Flat mode35020 -Ref: #flat-mode35147 -Node: Depth limited balance reports35567 -Ref: #depth-limited-balance-reports35770 -Node: Multicolumn balance reports36190 -Ref: #multicolumn-balance-reports36401 -Node: Custom balance output41049 -Ref: #custom-balance-output41233 -Node: Colour support43326 -Ref: #colour-support43487 -Node: Output destination43660 -Ref: #output-destination43818 -Node: CSV output44088 -Ref: #csv-output44207 -Node: balancesheet44604 -Ref: #balancesheet44742 -Node: balancesheetequity46710 -Ref: #balancesheetequity46861 -Node: cashflow47650 -Ref: #cashflow47780 -Node: check-dates49692 -Ref: #check-dates49821 -Node: check-dupes49938 -Ref: #check-dupes50065 -Node: equity50202 -Ref: #equity50314 -Node: help50477 -Ref: #help50580 -Node: import51654 -Ref: #import51770 -Node: incomestatement52165 -Ref: #incomestatement52301 -Node: prices54254 -Ref: #prices54371 -Node: print54414 -Ref: #print54526 -Node: print-unique59372 -Ref: #print-unique59500 -Node: register59568 -Ref: #register59697 -Node: Custom register output64198 -Ref: #custom-register-output64329 -Node: register-match65626 -Ref: #register-match65762 -Node: rewrite65945 -Ref: #rewrite66064 -Node: stats66133 -Ref: #stats66238 -Node: tags67119 -Ref: #tags67219 -Node: test67251 -Ref: #test67337 -Node: ADD-ON COMMANDS67705 -Ref: #add-on-commands67817 -Node: Official add-ons69104 -Ref: #official-add-ons69246 -Node: api69333 -Ref: #api69424 -Node: ui69476 -Ref: #ui69577 -Node: web69635 -Ref: #web69726 -Node: Third party add-ons69772 -Ref: #third-party-add-ons69949 -Node: diff70084 -Ref: #diff70183 -Node: iadd70282 -Ref: #iadd70398 -Node: interest70481 -Ref: #interest70604 -Node: irr70699 -Ref: #irr70799 -Node: Experimental add-ons70877 -Ref: #experimental-add-ons71031 -Node: autosync71322 -Ref: #autosync71436 -Node: budget71675 -Ref: #budget71799 -Node: chart71865 -Ref: #chart71984 -Node: check72055 -Ref: #check72159 - -End Tag Table diff --git a/doc/hledger.1.txt b/doc/hledger.1.txt deleted file mode 100644 --- a/doc/hledger.1.txt +++ /dev/null @@ -1,1969 +0,0 @@ - -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 - (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) - - 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 expansion - You can save a set of command line options/arguments in a file, one per - line, and then reuse them by writing @FILE in a command line. (To pre- - vent this expansion of @-arguments, precede them with a -- argument.) - - 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" - - The following more complex report intervals are also supported: - biweekly, bimonthly, every N days|weeks|months|quarters|years, - every Nth day [of month], every Nth day of week. - - Examples: - - - -p "bimonthly from 2008" - -p "every 2 weeks" - -p "every 5 days from 1/3" - - 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 the reported amounts to their market value - on the report end date, using the most recent applicable market prices, - when known. Specifically, when there is a market price (P directive) - for the amount's commodity, dated on or before the report end date (see - hledger -> Report start & end date), the amount will be converted to - the price's commodity. If multiple applicable prices are defined, the - latest-dated one is used (and if dates are equal, the one last parsed). - - 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). - - Using -B and -V together is allowed. - - 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. - - --tree show short account names, 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. - - 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. - - -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 (total row amount, or by average if that is dis- - played), instead of account name (in flat mode) - - 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. "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.) - - Each account's balance is the "inclusive" balance - it includes 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 - - Custom balance output - In simple (non-multi-column) balance reports, you can customise the - output 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 - - 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 - - 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. - - --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 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.) - - $ 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. - - 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. - - This command displays a balancesheet. It currently assumes that you - have top-level accounts named asset, liability and equity (plural forms - also allowed.) - - $ 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 - Show a cashflow statement. Alias: 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 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. - - $ 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. - - 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 - - equity - 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. - - 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 - - Input files are provided as arguments, or glob patterns. So eg to add - new transactions from all CSV files to the main journal: hledger import - *.csv - - New transactions are detected like print --new (using .latest.FILE - state files). - - incomestatement - Show an income statement. Alias: 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 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. - - 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. - - 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. - - The print command also supports output destination and CSV output. - 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 - - The register command also supports the -o/--output-file and -O/--out- - put-format options for controlling output destination and CSV output. - - 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. - - The stats command also supports -o/--output-file for controlling output - destination. - - tags - List all the tag names in use. - - 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. - - 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. - - 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.4 September 2017 hledger(1) diff --git a/doc/other/hledger-api.1 b/doc/other/hledger-api.1 deleted file mode 100644 --- a/doc/other/hledger-api.1 +++ /dev/null @@ -1,122 +0,0 @@ - -.TH "hledger\-api" "1" "September 2017" "hledger\-api 1.4" "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/doc/other/hledger-api.1.info b/doc/other/hledger-api.1.info deleted file mode 100644 --- a/doc/other/hledger-api.1.info +++ /dev/null @@ -1,70 +0,0 @@ -This is hledger-api.1.info, produced by makeinfo version 6.0 from stdin. - - -File: hledger-api.1.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-api(1) hledger-api 1.4 -****************************** - -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.1.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: Top74 -Node: OPTIONS1220 -Ref: #options1307 - -End Tag Table diff --git a/doc/other/hledger-api.1.txt b/doc/other/hledger-api.1.txt deleted file mode 100644 --- a/doc/other/hledger-api.1.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.4 September 2017 hledger-api(1) diff --git a/doc/other/hledger-ui.1 b/doc/other/hledger-ui.1 deleted file mode 100644 --- a/doc/other/hledger-ui.1 +++ /dev/null @@ -1,470 +0,0 @@ - -.TH "hledger\-ui" "1" "September 2017" "hledger\-ui 1.4" "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\[aq]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\[aq]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\[aq]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 -(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 -.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\[aq]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 "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 \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\[aq]t be centered, since we -don\[aq]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\[aq]s add command, and reloads the -updated file. -This allows some basic data entry. -.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\[aq]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\[aq]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\[aq]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\[aq]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\[aq]s print command and journal format -(hledger_journal(5)). -.PP -The transaction\[aq]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\[aq]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\[aq]t work (hledger\-ui can\[aq]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/doc/other/hledger-ui.1.info b/doc/other/hledger-ui.1.info deleted file mode 100644 --- a/doc/other/hledger-ui.1.info +++ /dev/null @@ -1,383 +0,0 @@ -This is hledger-ui.1.info, produced by makeinfo version 6.0 from stdin. - - -File: hledger-ui.1.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-ui(1) hledger-ui 1.4 -**************************** - -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.1.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 - (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) - - 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.1.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. - - '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.1.info, Node: SCREENS, Prev: KEYS, Up: Top - -3 SCREENS -********* - -* Menu: - -* Accounts screen:: -* Register screen:: -* Transaction screen:: -* Error screen:: - - -File: hledger-ui.1.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.1.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.1.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.1.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: Top73 -Node: OPTIONS825 -Ref: #options924 -Node: KEYS3861 -Ref: #keys3958 -Node: SCREENS6754 -Ref: #screens6841 -Node: Accounts screen6931 -Ref: #accounts-screen7061 -Node: Register screen9291 -Ref: #register-screen9448 -Node: Transaction screen11522 -Ref: #transaction-screen11682 -Node: Error screen12552 -Ref: #error-screen12676 - -End Tag Table diff --git a/doc/other/hledger-ui.1.txt b/doc/other/hledger-ui.1.txt deleted file mode 100644 --- a/doc/other/hledger-ui.1.txt +++ /dev/null @@ -1,376 +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 - (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) - - 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. - - 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.4 September 2017 hledger-ui(1) diff --git a/doc/other/hledger-web.1 b/doc/other/hledger-web.1 deleted file mode 100644 --- a/doc/other/hledger-web.1 +++ /dev/null @@ -1,317 +0,0 @@ - -.TH "hledger\-web" "1" "September 2017" "hledger\-web 1.4" "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\[aq]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 "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 \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\[aq]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\[aq]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 -(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 -.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\[aq]t work (hledger\-web can\[aq]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/doc/other/hledger-web.1.info b/doc/other/hledger-web.1.info deleted file mode 100644 --- a/doc/other/hledger-web.1.info +++ /dev/null @@ -1,207 +0,0 @@ -This is hledger-web.1.info, produced by makeinfo version 6.0 from stdin. - - -File: hledger-web.1.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-web(1) hledger-web 1.4 -****************************** - -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.1.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 - (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) - - 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: Top74 -Node: OPTIONS3156 -Ref: #options3243 - -End Tag Table diff --git a/doc/other/hledger-web.1.txt b/doc/other/hledger-web.1.txt deleted file mode 100644 --- a/doc/other/hledger-web.1.txt +++ /dev/null @@ -1,244 +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 - (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) - - 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.4 September 2017 hledger-web(1) diff --git a/doc/other/hledger_csv.5 b/doc/other/hledger_csv.5 deleted file mode 100644 --- a/doc/other/hledger_csv.5 +++ /dev/null @@ -1,277 +0,0 @@ - -.TH "hledger_csv" "5" "September 2017" "hledger 1.4" "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 files, converting each CSV record into a journal -entry (transaction), if you provide some conversion hints in a "rules -file". -This file should be named like the CSV file with an additional -\f[C]\&.rules\f[] suffix (eg: \f[C]mybank.csv.rules\f[]); or, you can -specify the file with \f[C]\-\-rules\-file\ PATH\f[]. -hledger will create it if necessary, with some default rules which -you\[aq]ll need to adjust. -At minimum, the rules file must specify the \f[C]date\f[] and -\f[C]amount\f[] fields. -For an example, see Cookbook: convert CSV files. -.PP -To learn about \f[I]exporting\f[] CSV, see CSV output. -.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[C]N\f[]\f[] -.PP -Skip this number of CSV records at the beginning. -You\[aq]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[C]DATEFMT\f[]\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\[aq]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[C]FIELDNAME1\f[]\f[], -\f[I]\f[C]FIELDNAME2\f[]\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[C]ENTRYFIELDNAME\f[]\f[] \f[I]\f[C]FIELDVALUE\f[]\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[C]PATTERN\f[]\f[] -.PD 0 -.P -.PD -\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]... -.PP -\f[C]if\f[] -.PD 0 -.P -.PD -\f[I]\f[C]PATTERN\f[]\f[] -.PD 0 -.P -.PD -\f[I]\f[C]PATTERN\f[]\f[]... -.PD 0 -.P -.PD -\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\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\[aq]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[C]RULESFILE\f[]\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\[aq]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\[aq]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\[aq]s not yet possible to generate entries with more than two -postings. -It\[aq]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/doc/other/hledger_csv.5.info b/doc/other/hledger_csv.5.info deleted file mode 100644 --- a/doc/other/hledger_csv.5.info +++ /dev/null @@ -1,302 +0,0 @@ -This is hledger_csv.5.info, produced by makeinfo version 6.0 from stdin. - - -File: hledger_csv.5.info, Node: Top, Next: CSV RULES, Up: (dir) - -hledger_csv(5) hledger 1.4 -************************** - -hledger can read CSV files, converting each CSV record into a journal -entry (transaction), if you provide some conversion hints in a "rules -file". This file should be named like the CSV file with an additional -'.rules' suffix (eg: 'mybank.csv.rules'); or, you can specify the file -with '--rules-file PATH'. hledger will create it if necessary, with -some default rules which you'll need to adjust. At minimum, the rules -file must specify the 'date' and 'amount' fields. For an example, see -Cookbook: convert CSV files. - - To learn about _exporting_ CSV, see CSV output. -* Menu: - -* CSV RULES:: -* CSV TIPS:: - - -File: hledger_csv.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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: Top74 -Node: CSV RULES810 -Ref: #csv-rules920 -Node: skip1182 -Ref: #skip1278 -Node: date-format1450 -Ref: #date-format1579 -Node: field list2085 -Ref: #field-list2224 -Node: field assignment2929 -Ref: #field-assignment3086 -Node: conditional block3590 -Ref: #conditional-block3746 -Node: include4642 -Ref: #include4774 -Node: newest-first5005 -Ref: #newest-first5121 -Node: CSV TIPS5532 -Ref: #csv-tips5628 -Node: CSV ordering5746 -Ref: #csv-ordering5866 -Node: CSV accounts6047 -Ref: #csv-accounts6187 -Node: CSV amounts6441 -Ref: #csv-amounts6589 -Node: CSV balance assertions7364 -Ref: #csv-balance-assertions7548 -Node: Reading multiple CSV files7753 -Ref: #reading-multiple-csv-files7925 - -End Tag Table diff --git a/doc/other/hledger_csv.5.txt b/doc/other/hledger_csv.5.txt deleted file mode 100644 --- a/doc/other/hledger_csv.5.txt +++ /dev/null @@ -1,203 +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 files, converting each CSV record into a journal - entry (transaction), if you provide some conversion hints in a "rules - file". This file should be named like the CSV file with an additional - .rules suffix (eg: mybank.csv.rules); or, you can specify the file with - --rules-file PATH. hledger will create it if necessary, with some - default rules which you'll need to adjust. At minimum, the rules file - must specify the date and amount fields. For an example, see Cookbook: - convert CSV files. - - To learn about exporting CSV, see CSV output. - -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.4 September 2017 hledger_csv(5) diff --git a/doc/other/hledger_journal.5 b/doc/other/hledger_journal.5 deleted file mode 100644 --- a/doc/other/hledger_journal.5 +++ /dev/null @@ -1,1153 +0,0 @@ -.\"t - -.TH "hledger_journal" "5" "September 2017" "hledger 1.4" "hledger User Manuals" - - - -.SH NAME -.PP -Journal \- hledger\[aq]s default file format, representing a General -Journal -.SH DESCRIPTION -.PP -hledger\[aq]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\[aq]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\[aq]s journal format is a compatible subset, mostly, of -ledger\[aq]s journal format, so hledger can work with compatible ledger -journal files as well. -It\[aq]s safe, and encouraged, to run both hledger and ledger on the -same journal file, eg to validate the results you\[aq]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\[aq]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\[aq]s best to follow -a consistent rule. -Eg write the bank\[aq]s clearing date as primary, and when needed, the -date the transaction was initiated as secondary. -.PP -Here\[aq]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\[aq]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\[aq]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 "unmarked" state -is called "uncleared". -As of hledger 1.3 we have renamed it to unmarked for clarity. -.PP -To replicate Ledger and old hledger\[aq]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 "uncleared", "pending", and "cleared" actually mean is up to you. -Here\[aq]s one suggestion: -.PP -.TS -tab(@); -lw(10.5n) lw(59.5n). -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\[aq]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. -.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[] -.PP -As you can see, the amount format is somewhat flexible: -.IP \[bu] 2 -amounts are a number (the "quantity") and optionally a currency -symbol/commodity name (the "commodity"). -.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 -commas (in which case period is used for decimal point) or periods (in -which case comma is used for decimal point) -.PP -You can use any of these variations when recording data, but 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\[aq]t affect -amount format inference, but in some situations they can do so -indirectly. -(Eg when D\[aq]s default commodity is applied to a commodity\-less -amount, or when an amountless posting is balanced using a price\[aq]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\[aq]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\[aq]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\[aq]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\[aq]s -balance on the same day, you\[aq]ll have to put the assertion in the -right file. -.SS Assertions and multiple \-f options -.PP -Balance assertions don\[aq]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\[aq]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\[aq]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\[aq]t be -sure the account does not contain some unexpected commodity. -(We\[aq]ll add support for this kind of total balance assertion if -there\[aq]s demand.) -.SS Assertions and subaccounts -.PP -Balance assertions do not count the balance from subaccounts; they check -the posted account\[aq]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\[aq]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\[aq]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\[aq]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\[aq]s commodity by using the \f[C]\-B/\-\-cost\f[] flag (except -for #551) ("B" is from "cost Basis"). -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\[aq]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 asterisk (\f[C]*\f[]) are comments, and will be ignored. -(Asterisk comments make it easy to treat your journal like an org\-mode -outline in emacs.) -.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. -.PP -Some examples: -.IP -.nf -\f[C] -#\ a\ journal\ comment - -;\ also\ a\ journal\ comment - -comment -This\ is\ a\ multiline\ comment, -which\ continues\ until\ a\ line -where\ the\ "end\ comment"\ string -appears\ on\ its\ own. -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\ journal\ 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\[aq]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 -"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag -.IP \[bu] 2 -"\f[C]tag1\f[]" is a tag with no value -.IP \[bu] 2 -"\f[C]tag2\f[]" is another tag, whose value is -"\f[C]some\ value\ ...\f[]" -.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\[aq]s metadata feature, except hledger\[aq]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\[aq]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\[aq]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\[aq]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 "format" 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\[aq]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\[aq]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 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(51.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/doc/other/hledger_journal.5.info b/doc/other/hledger_journal.5.info deleted file mode 100644 --- a/doc/other/hledger_journal.5.info +++ /dev/null @@ -1,1147 +0,0 @@ -This is hledger_journal.5.info, produced by makeinfo version 6.0 from -stdin. - - -File: hledger_journal.5.info, Node: Top, Next: FILE FORMAT, Up: (dir) - -hledger_journal(5) hledger 1.4 -****************************** - -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:: -* EDITOR SUPPORT:: - - -File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, 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.5.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.5.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.5.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT - -1.3 Dates -========= - -* Menu: - -* Simple dates:: -* Secondary dates:: -* Posting dates:: - - -File: hledger_journal.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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' - - 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 - commas (in which case period is used for decimal point) or periods - (in which case comma is used for decimal point) - - You can use any of these variations when recording data, but 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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT - -1.11 Prices -=========== - -* Menu: - -* Transaction prices:: -* Market prices:: - - -File: hledger_journal.5.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.5.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.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT - -1.12 Comments -============= - -Lines in the journal beginning with a semicolon (';') or hash ('#') or -asterisk ('*') are comments, and will be ignored. (Asterisk comments -make it easy to treat your journal like an org-mode outline in emacs.) - - 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. - - Some examples: - -# a journal comment - -; also a journal comment - -comment -This is a multiline comment, -which continues until a line -where the "end comment" string -appears on its own. -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 journal comment (because not indented) - - -File: hledger_journal.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top - -2 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: Top78 -Node: FILE FORMAT2374 -Ref: #file-format2500 -Node: Transactions2723 -Ref: #transactions2846 -Node: Postings3530 -Ref: #postings3659 -Node: Dates4654 -Ref: #dates4771 -Node: Simple dates4836 -Ref: #simple-dates4964 -Node: Secondary dates5330 -Ref: #secondary-dates5486 -Node: Posting dates7049 -Ref: #posting-dates7180 -Node: Status8554 -Ref: #status8676 -Node: Description10390 -Ref: #description10530 -Node: Payee and note10849 -Ref: #payee-and-note10965 -Node: Account names11207 -Ref: #account-names11352 -Node: Amounts11839 -Ref: #amounts11977 -Node: Virtual Postings14078 -Ref: #virtual-postings14239 -Node: Balance Assertions15459 -Ref: #balance-assertions15636 -Node: Assertions and ordering16532 -Ref: #assertions-and-ordering16720 -Node: Assertions and included files17420 -Ref: #assertions-and-included-files17663 -Node: Assertions and multiple -f options17996 -Ref: #assertions-and-multiple--f-options18252 -Node: Assertions and commodities18384 -Ref: #assertions-and-commodities18621 -Node: Assertions and subaccounts19317 -Ref: #assertions-and-subaccounts19551 -Node: Assertions and virtual postings20072 -Ref: #assertions-and-virtual-postings20281 -Node: Balance Assignments20423 -Ref: #balance-assignments20594 -Node: Prices21713 -Ref: #prices21848 -Node: Transaction prices21899 -Ref: #transaction-prices22046 -Node: Market prices24202 -Ref: #market-prices24339 -Node: Comments25299 -Ref: #comments25423 -Node: Tags26536 -Ref: #tags26656 -Node: Directives28058 -Ref: #directives28173 -Node: Account aliases28366 -Ref: #account-aliases28512 -Node: Basic aliases29116 -Ref: #basic-aliases29261 -Node: Regex aliases29951 -Ref: #regex-aliases30121 -Node: Multiple aliases30839 -Ref: #multiple-aliases31013 -Node: end aliases31511 -Ref: #end-aliases31653 -Node: account directive31754 -Ref: #account-directive31936 -Node: apply account directive32232 -Ref: #apply-account-directive32430 -Node: Multi-line comments33089 -Ref: #multi-line-comments33281 -Node: commodity directive33409 -Ref: #commodity-directive33595 -Node: Default commodity34467 -Ref: #default-commodity34642 -Node: Default year35179 -Ref: #default-year35346 -Node: Including other files35769 -Ref: #including-other-files35928 -Node: EDITOR SUPPORT36325 -Ref: #editor-support36445 - -End Tag Table diff --git a/doc/other/hledger_journal.5.txt b/doc/other/hledger_journal.5.txt deleted file mode 100644 --- a/doc/other/hledger_journal.5.txt +++ /dev/null @@ -1,848 +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 recon- - ciliation) - 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. - - 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 - - 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 - commas (in which case period is used for decimal point) or periods - (in which case comma is used for decimal point) - - You can use any of these variations when recording data, but 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 - asterisk (*) are comments, and will be ignored. (Asterisk comments - make it easy to treat your journal like an org-mode outline in emacs.) - - 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. - - Some examples: - - # a journal comment - - ; also a journal comment - - comment - This is a multiline comment, - which continues until a line - where the "end comment" string - appears on its own. - 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 journal 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. - -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/Get- - ting-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.4 September 2017 hledger_journal(5) diff --git a/doc/other/hledger_timeclock.5 b/doc/other/hledger_timeclock.5 deleted file mode 100644 --- a/doc/other/hledger_timeclock.5 +++ /dev/null @@ -1,100 +0,0 @@ - -.TH "hledger_timeclock" "5" "September 2017" "hledger 1.4" "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\[aq]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: -.RS 2 -.IP -.nf -\f[C] -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[] -.fi -.RE -.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 "timeclock" 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/doc/other/hledger_timeclock.5.info b/doc/other/hledger_timeclock.5.info deleted file mode 100644 --- a/doc/other/hledger_timeclock.5.info +++ /dev/null @@ -1,62 +0,0 @@ -This is hledger_timeclock.5.info, produced by makeinfo version 6.0 from -stdin. - - -File: hledger_timeclock.5.info, Node: Top, Up: (dir) - -hledger_timeclock(5) hledger 1.4 -******************************** - -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: - - 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: Top80 - -End Tag Table diff --git a/doc/other/hledger_timeclock.5.txt b/doc/other/hledger_timeclock.5.txt deleted file mode 100644 --- a/doc/other/hledger_timeclock.5.txt +++ /dev/null @@ -1,82 +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: - - 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.4 September 2017 hledger_timeclock(5) diff --git a/doc/other/hledger_timedot.5 b/doc/other/hledger_timedot.5 deleted file mode 100644 --- a/doc/other/hledger_timedot.5 +++ /dev/null @@ -1,154 +0,0 @@ - -.TH "hledger_timedot" "5" "September 2017" "hledger 1.4" "hledger User Manuals" - - - -.SH NAME -.PP -Timedot \- hledger\[aq]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 "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\[aq]ll assume it\[aq]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/doc/other/hledger_timedot.5.info b/doc/other/hledger_timedot.5.info deleted file mode 100644 --- a/doc/other/hledger_timedot.5.info +++ /dev/null @@ -1,116 +0,0 @@ -This is hledger_timedot.5.info, produced by makeinfo version 6.0 from -stdin. - - -File: hledger_timedot.5.info, Node: Top, Next: FILE FORMAT, Up: (dir) - -hledger_timedot(5) hledger 1.4 -****************************** - -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.5.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: Top78 -Node: FILE FORMAT809 -Ref: #file-format912 - -End Tag Table diff --git a/doc/other/hledger_timedot.5.txt b/doc/other/hledger_timedot.5.txt deleted file mode 100644 --- a/doc/other/hledger_timedot.5.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.4 September 2017 hledger_timedot(5) diff --git a/hledger.1 b/hledger.1 new file mode 100644 --- /dev/null +++ b/hledger.1 @@ -0,0 +1,2934 @@ +.\"t + +.TH "hledger" "1" "December 2017" "hledger 1.5" "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 +.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 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]\-\-tree\f[] +show short account names, 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 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 +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. +.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. +.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 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]\-\-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. +\[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.) +.PP +Each account's balance is the \[lq]inclusive\[rq] balance \- it includes +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 +For more examples and details, 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[]: +.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 +.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 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. +.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 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.) +.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. +.SS balancesheetequity +.PP +Show a balance sheet including equity. +Alias: bse. +.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. +.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.) +.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 +Show a cashflow statement. +Alias: 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 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[]. +.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[]. +.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 equity +.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. +.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 +Show an income statement. +Alias: 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 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[]. +.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 +The print command also supports output destination and CSV output. +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 +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. +.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 +The stats command also supports \f[C]\-o/\-\-output\-file\f[] for +controlling output destination. +.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 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. +.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/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -1,9 +1,11 @@ --- This file has been generated from package.yaml by hpack version 0.17.1. +-- This file has been generated from package.yaml by hpack version 0.20.0. -- -- see: https://github.com/sol/hpack +-- +-- hash: 8e14dbb3cafd99102e0a85bd39076ca0af4c9554f348cd6cacb0d59faf63623b name: hledger -version: 1.4 +version: 1.5 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 @@ -34,30 +36,30 @@ test/test.hs data-files: - doc/hledger.1 - doc/hledger.1.info - doc/hledger.1.txt - doc/other/hledger-api.1 - doc/other/hledger-api.1.info - doc/other/hledger-api.1.txt - doc/other/hledger-ui.1 - doc/other/hledger-ui.1.info - doc/other/hledger-ui.1.txt - doc/other/hledger-web.1 - doc/other/hledger-web.1.info - doc/other/hledger-web.1.txt - doc/other/hledger_csv.5 - doc/other/hledger_csv.5.info - doc/other/hledger_csv.5.txt - doc/other/hledger_journal.5 - doc/other/hledger_journal.5.info - doc/other/hledger_journal.5.txt - doc/other/hledger_timeclock.5 - doc/other/hledger_timeclock.5.info - doc/other/hledger_timeclock.5.txt - doc/other/hledger_timedot.5 - doc/other/hledger_timedot.5.info - doc/other/hledger_timedot.5.txt + .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 + hledger.1 + hledger.info + hledger.txt source-repository head type: git @@ -75,44 +77,45 @@ 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.4" + cpp-options: -DVERSION="1.5" build-depends: - base >=4.8 && <5 + Decimal + , Diff + , HUnit + , ansi-terminal >=0.6.2.3 + , base >=4.8 && <5 , base-compat >=0.8.1 - , ansi-terminal >= 0.6.2.3 && < 0.8 - , directory - , file-embed >=0.0.10 && <0.1 - , filepath - , here - , pretty-show >=1.6.4 - , process - , shakespeare >=2.0.2.2 && <2.1 - , temporary - , tabular >=0.2 && <0.3 - , time >=1.5 - , utility-ht >= 0.0.13 - , hledger-lib >= 1.4 && < 1.5 , bytestring + , cmdargs >=0.10 , containers - , unordered-containers - , cmdargs >=0.10 && <0.11 , csv , data-default >=0.5 - , Diff + , directory + , file-embed >=0.0.10 + , filepath , hashable >=1.2.4 - , haskeline >=0.6 && <=0.8 - , HUnit + , haskeline >=0.6 + , here + , hledger-lib >=1.5 && <1.6 + , megaparsec >=5.0 , mtl , mtl-compat , old-time - , megaparsec >=5.0 && < 6.2 + , pretty-show >=1.6.4 + , process , regex-tdfa , safe >=0.2 - , split >=0.1 && <0.3 - , transformers + , shakespeare >=2.0.2.2 + , split >=0.1 + , tabular >=0.2 + , temporary , text >=0.11 - , utf8-string >=0.3.5 && <1.1 - , wizards ==1.0.* + , time >=1.5 + , transformers + , unordered-containers + , utf8-string >=0.3.5 + , utility-ht >=0.0.13 + , wizards >=1.0 if (!(os(windows))) && (flag(terminfo)) build-depends: terminfo @@ -156,47 +159,50 @@ 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.4" + cpp-options: -DVERSION="1.5" build-depends: - base >=4.8 && <5 + Decimal + , HUnit + , ansi-terminal >=0.6.2.3 + , base >=4.8 && <5 , base-compat >=0.8.1 - , ansi-terminal >= 0.6.2.3 && < 0.8 - , directory - , file-embed >=0.0.10 && <0.1 - , filepath - , here - , pretty-show >=1.6.4 - , process - , shakespeare >=2.0.2.2 && <2.1 - , temporary - , tabular >=0.2 && <0.3 - , time >=1.5 - , utility-ht >= 0.0.13 - , hledger-lib >= 1.4 && < 1.5 - , hledger , bytestring + , cmdargs >=0.10 , containers - , unordered-containers - , cmdargs >=0.10 && <0.11 , csv , data-default >=0.5 - , haskeline >=0.6 && <=0.8 - , HUnit + , directory + , file-embed >=0.0.10 + , filepath + , haskeline >=0.6 + , here + , hledger + , hledger-lib >=1.5 && <1.6 , mtl , mtl-compat , old-time , parsec >=3 + , pretty-show >=1.6.4 + , process , regex-tdfa , safe >=0.2 - , split >=0.1 && <0.3 + , shakespeare >=2.0.2.2 + , split >=0.1 + , tabular >=0.2 + , temporary , text >=0.11 - , utf8-string >=0.3.5 && <1.1 - , wizards ==1.0.* + , time >=1.5 + , unordered-containers + , utf8-string >=0.3.5 + , utility-ht >=0.0.13 + , wizards >=1.0 if (!(os(windows))) && (flag(terminfo)) build-depends: terminfo if flag(threaded) ghc-options: -threaded + other-modules: + Paths_hledger default-language: Haskell2010 test-suite test @@ -205,47 +211,50 @@ 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.4" + cpp-options: -DVERSION="1.5" build-depends: - base >=4.8 && <5 + Decimal + , HUnit + , ansi-terminal >=0.6.2.3 + , base >=4.8 && <5 , base-compat >=0.8.1 - , ansi-terminal >= 0.6.2.3 && < 0.8 - , directory - , file-embed >=0.0.10 && <0.1 - , filepath - , here - , pretty-show >=1.6.4 - , process - , shakespeare >=2.0.2.2 && <2.1 - , temporary - , tabular >=0.2 && <0.3 - , time >=1.5 - , utility-ht >= 0.0.13 - , hledger-lib >= 1.4 && < 1.5 - , hledger , bytestring + , cmdargs >=0.10 , containers - , unordered-containers - , cmdargs >=0.10 && <0.11 , csv , data-default >=0.5 - , haskeline >=0.6 && <=0.8 - , HUnit + , directory + , file-embed >=0.0.10 + , filepath + , haskeline >=0.6 + , here + , hledger + , hledger-lib >=1.5 && <1.6 , mtl , mtl-compat , old-time , parsec >=3 + , pretty-show >=1.6.4 + , process , regex-tdfa , safe >=0.2 - , split >=0.1 && <0.3 - , text >=0.11 - , utf8-string >=0.3.5 && <1.1 - , wizards ==1.0.* + , shakespeare >=2.0.2.2 + , split >=0.1 + , tabular >=0.2 + , temporary , test-framework , test-framework-hunit + , text >=0.11 + , time >=1.5 + , unordered-containers + , utf8-string >=0.3.5 + , utility-ht >=0.0.13 + , wizards >=1.0 if (!(os(windows))) && (flag(terminfo)) build-depends: terminfo + other-modules: + Paths_hledger default-language: Haskell2010 benchmark bench @@ -255,26 +264,28 @@ bench ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans build-depends: - base >=4.8 && <5 + ansi-terminal >=0.6.2.3 + , base >=4.8 && <5 , base-compat >=0.8.1 - , ansi-terminal >= 0.6.2.3 && < 0.8 + , criterion , directory - , file-embed >=0.0.10 && <0.1 + , file-embed >=0.0.10 , filepath , here + , hledger + , hledger-lib >=1.5 && <1.6 + , html , pretty-show >=1.6.4 , process - , shakespeare >=2.0.2.2 && <2.1 + , shakespeare >=2.0.2.2 + , tabular >=0.2 , temporary - , tabular >=0.2 && <0.3 , time >=1.5 - , utility-ht >= 0.0.13 - , hledger-lib >= 1.4 && < 1.5 - , hledger - , criterion - , html , timeit + , utility-ht >=0.0.13 if (!(os(windows))) && (flag(terminfo)) build-depends: terminfo + other-modules: + Paths_hledger default-language: Haskell2010 diff --git a/hledger.info b/hledger.info new file mode 100644 --- /dev/null +++ b/hledger.info @@ -0,0 +1,2504 @@ +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.5 +********************** + +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:: +* 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 +'-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: Regular expressions, 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: Regular expressions, Prev: Combining -B and -V, Up: OPTIONS + +2.16 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:: +* equity:: +* 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. + +'--tree' + + show short account names, 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. + + 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. +'-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 name (in flat mode). With + multiple columns, sorts by the row total, or by row average if that + is displayed. +'--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. "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.) + + Each account's balance is the "inclusive" balance - it includes 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:: +* Output destination:: +* CSV output:: + + +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 + + For more examples and details, 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': + +$ 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 + + +File: hledger.info, Node: Colour support, Next: Output destination, 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: 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. + +'--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 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.) + +$ 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. + + +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. + + This command displays a balancesheet. It currently assumes that you +have top-level accounts named 'asset', 'liability' and 'equity' (plural +forms also allowed.) + +$ 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 +============ + +Show a cashflow statement. Alias: 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 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'. + +$ 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'. + + +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: equity, 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: equity, Next: help, Prev: check-dupes, Up: COMMANDS + +4.10 equity +=========== + +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. + + +File: hledger.info, Node: help, Next: import, Prev: equity, 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 +==================== + +Show an income statement. Alias: 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 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'. + + +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. + + The print command also supports output destination and CSV output. +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 + + The register command also supports the '-o/--output-file' and +'-O/--output-format' options for controlling output destination and CSV +output. + + +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. + + The stats command also supports '-o/--output-file' for controlling +output destination. + + +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:: +* budget:: +* chart:: +* check:: + + +File: hledger.info, Node: autosync, Next: budget, 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: 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 + +5.3.3 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.4 check +----------- + +hledger-check.hs checks more powerful account balance assertions. + + +Tag Table: +Node: Top68 +Node: EXAMPLES1882 +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 + +End Tag Table diff --git a/hledger.txt b/hledger.txt new file mode 100644 --- /dev/null +++ b/hledger.txt @@ -0,0 +1,2138 @@ + +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 + + -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. + + 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. + + --tree show short account names, 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. + + 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. + + -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 name (in flat mode). With + multiple columns, sorts by the row total, or by row average if + that is displayed. + + --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. "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.) + + Each account's balance is the "inclusive" balance - it includes 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 + + For more examples and details, see Budgeting and Forecasting. + + Custom balance output + In simple (non-multi-column) balance reports, you can customise the + output 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 + + 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 + + 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. + + --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 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.) + + $ 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. + + 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. + + This command displays a balancesheet. It currently assumes that you + have top-level accounts named asset, liability and equity (plural forms + also allowed.) + + $ 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 + Show a cashflow statement. Alias: 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 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. + + $ 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. + + 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 + + equity + 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. + + 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 + Show an income statement. Alias: 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 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. + + 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. + + The print command also supports output destination and CSV output. + 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 + + The register command also supports the -o/--output-file and -O/--out- + put-format options for controlling output destination and CSV output. + + 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. + + The stats command also supports -o/--output-file for controlling output + destination. + + 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. + + 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. + + 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.5 December 2017 hledger(1)