diff --git a/site/css/syntax.css b/site/css/syntax.css new file mode 100644 index 000000000..93f64d0c6 --- /dev/null +++ b/site/css/syntax.css @@ -0,0 +1,139 @@ +/* Generated with pandoc --highlight-style=X */ + +/* pygments */ + +/* +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode, table.sourceCode pre + { margin: 0; padding: 0; border: 0; vertical-align: baseline; border: none; } +td.lineNumbers { border-right: 1px solid #AAAAAA; text-align: right; color: #AAAAAA; padding-right: 5px; padding-left: 5px; } +td.sourceCode { padding-left: 5px; } +pre.sourceCode span.kw { color: #007020; font-weight: bold; } +pre.sourceCode span.dt { color: #902000; } +pre.sourceCode span.dv { color: #40a070; } +pre.sourceCode span.bn { color: #40a070; } +pre.sourceCode span.fl { color: #40a070; } +pre.sourceCode span.ch { color: #4070a0; } +pre.sourceCode span.st { color: #4070a0; } +pre.sourceCode span.co { color: #60a0b0; font-style: italic; } +pre.sourceCode span.ot { color: #007020; } +pre.sourceCode span.al { color: red; font-weight: bold; } +pre.sourceCode span.fu { color: #06287e; } +pre.sourceCode span.re { } +pre.sourceCode span.er { color: red; font-weight: bold; } +*/ + +/* kate */ + +/* +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; background-color: #dddddd; } +td.sourceCode { padding-left: 5px; } +code > span.kw { font-weight: bold; } +code > span.dt { color: #800000; } +code > span.dv { color: #0000ff; } +code > span.bn { color: #0000ff; } +code > span.fl { color: #800080; } +code > span.ch { color: #ff00ff; } +code > span.st { color: #dd0000; } +code > span.co { color: #808080; font-style: italic; } +code > span.al { color: #00ff00; font-weight: bold; } +code > span.fu { color: #000080; } +code > span.er { color: #ff0000; font-weight: bold; } +*/ + +/* monochrome */ +/* +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; } +td.sourceCode { padding-left: 5px; } +code > span.kw { font-weight: bold; } +code > span.dt { text-decoration: underline; } +code > span.co { font-style: italic; } +code > span.al { font-weight: bold; } +code > span.er { font-weight: bold; } +*/ + +/* espresso */ +/* +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; background-color: #2a211c; color: #bdae9d; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; background-color: #2a211c; color: #bdae9d; border-right: 1px solid #bdae9d; } +td.sourceCode { padding-left: 5px; } +pre, code { color: #bdae9d; background-color: #2a211c; } +code > span.kw { color: #43a8ed; font-weight: bold; } +code > span.dt { text-decoration: underline; } +code > span.dv { color: #44aa43; } +code > span.bn { color: #44aa43; } +code > span.fl { color: #44aa43; } +code > span.ch { color: #049b0a; } +code > span.st { color: #049b0a; } +code > span.co { color: #0066ff; font-style: italic; } +code > span.al { color: #ffff00; } +code > span.fu { color: #ff9358; font-weight: bold; } +code > span.er { font-weight: bold; } + */ + +/* zenburn */ +/* +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; background-color: #303030; color: #cccccc; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; } +td.sourceCode { padding-left: 5px; } +pre, code { color: #cccccc; background-color: #303030; } +code > span.kw { color: #f0dfaf; } +code > span.dt { color: #dfdfbf; } +code > span.dv { color: #dcdccc; } +code > span.bn { color: #dca3a3; } +code > span.fl { color: #c0bed1; } +code > span.ch { color: #dca3a3; } +code > span.st { color: #cc9393; } +code > span.co { color: #7f9f7f; } +code > span.ot { color: #efef8f; } +code > span.al { color: #ffcfaf; } +code > span.fu { color: #efef8f; } +code > span.er { color: #c3bf9f; } + */ + +/* haddock */ +/* +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } +td.sourceCode { padding-left: 5px; } +code > span.kw { color: #0000ff; } +code > span.ch { color: #008080; } +code > span.st { color: #008080; } +code > span.co { color: #008000; } +code > span.ot { color: #ff4000; } +code > span.al { color: #ff0000; } +code > span.er { font-weight: bold; } + */ + +/* tango */ + +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; background-color: #f8f8f8; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } +td.sourceCode { padding-left: 5px; } +pre, code { background-color: #f8f8f8; } +code > span.kw { color: #204a87; font-weight: bold; } +code > span.dt { color: #204a87; } +code > span.dv { color: #0000cf; } +code > span.bn { color: #0000cf; } +code > span.fl { color: #0000cf; } +code > span.ch { color: #4e9a06; } +code > span.st { color: #4e9a06; } +code > span.co { color: #8f5902; font-style: italic; } +code > span.ot { color: #8f5902; } +code > span.al { color: #ef2929; } +code > span.fu { color: #000000; } +code > span.er { font-weight: bold; } + */ diff --git a/site/doc/1.1/csv.md b/site/doc/1.1/csv.md index f452b21df..8580497f7 100644 --- a/site/doc/1.1/csv.md +++ b/site/doc/1.1/csv.md @@ -1,6 +1,6 @@ # csv format -This doc is for version **1.1**. +This doc is for version **dev**. - toc diff --git a/site/doc/1.1/hledger-api.md b/site/doc/1.1/hledger-api.md index 7f8e4b788..aa43254f2 100644 --- a/site/doc/1.1/hledger-api.md +++ b/site/doc/1.1/hledger-api.md @@ -1,6 +1,6 @@ # hledger-api -This doc is for version **1.1**. +This doc is for version **dev**. - toc diff --git a/site/doc/1.1/hledger-ui.md b/site/doc/1.1/hledger-ui.md index a2692e458..265a878b7 100644 --- a/site/doc/1.1/hledger-ui.md +++ b/site/doc/1.1/hledger-ui.md @@ -1,6 +1,6 @@ # hledger-ui -This doc is for version **1.1**. +This doc is for version **dev**. - toc + + + + + + + + + + +### 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 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. + +### 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 time) 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 + +`-V --value` +: show amounts as their current market value in their default + valuation commodity (accounts screen only) + +hledger general options: + +`-h` +: show general usage (or after COMMAND, the command's usage) + +`--help` +: show the current program's manual as plain text (or after an add-on + COMMAND, the add-on's manual) + +`--man` +: show the current program's manual with man + +`--info` +: show the current program's manual with info + +`--version` +: show version + +`--debug[=N]` +: show debug output (levels 1-9, default: 1) + +`-f FILE --file=FILE` +: use a different input file. For stdin, use - + +`--rules-file=RULESFILE` +: Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW` +: display accounts named OLD as NEW + +`-I --ignore-assertions` +: ignore any failing balance assertions in the journal + +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` +: show, and match with -b/-e/-p/date:, secondary dates instead + +`-C --cleared` +: include only cleared postings/txns + +`--pending` +: include only pending postings/txns + +`-U --uncleared` +: include only uncleared (and pending) postings/txns + +`-R --real` +: include only non-virtual postings + +`--depth=N` +: hide accounts/postings deeper than N + +`-E --empty` +: show items with zero amount, normally hidden + +`-B --cost` +: convert amounts to their cost at transaction time (using the + [transaction price](journal.html#transaction-prices), if any) + +`--pivot TAG` +: will transform the journal before any other processing by replacing + the account name of every posting having the tag TAG with content + VALUE by the account name "TAG:VALUE". The TAG will only match if it + is a full-length match. The pivot will only happen if the TAG is on + a posting, not if it is on the transaction. If the tag value is a + multi:level:account:name the new account name will + be "TAG:multi:level:account:name". + +`--anon` +: show anonymized accounts and payees + +### 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` 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](/hledger.html#queries) as in hledger and +hledger-web. While editing the query, you can use [CTRL-a/e/d/k, BS, +cursor +keys](http://hackage.haskell.org/package/brick-0.7/docs/Brick-Widgets-Edit.html#t:Editor); +press `ENTER` to set it, or `ESCAPE`to cancel. There are also keys for +quickly adjusting some common filters like account depth and +cleared/uncleared (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. + +`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. + +### 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 +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. + +`C` toggles cleared mode, in which [uncleared transactions and +postings](/journal.html#transactions) are not shown. `U` toggles +uncleared mode, in which only uncleared transactions/postings are shown. + +`R` toggles real mode, in which [virtual +postings](/journal.html#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: + +- 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`. + +`C` toggles cleared mode, in which [uncleared transactions and +postings](/journal.html#transactions) are not shown. `U` toggles +uncleared mode, in which only uncleared transactions/postings are shown. + +`R` toggles real mode, in which [virtual +postings](/journal.html#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. + +#### 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). + +#### 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.journal`). + +### FILES + +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`). + +### BUGS + +The need to precede options with `--` when invoked from hledger is +awkward. + +`-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. 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. + + +## hledger-web + +
+ +This doc is for version **1.1**. Available versions: +dev | +1.1 | +1.0 | +0.27 + +
+ +### 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 +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). + +``` {.shell} +$ hledger web +Starting web app on port 5000 with base url http://localhost:5000 +Starting web browser if possible +Web app will auto-exit after a few minutes with no browsers (or press ctrl-c) +``` + +With `--serve`, it starts the web app in non-transient mode 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. + +`--server` +: disable browser-opening and auto-exit-on-idle, and log all requests + to stdout + +`--port=PORT` +: set the TCP port to listen on (default: 5000) + +`--base-url=URL` +: set the base url (default: http://localhost: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 general options: + +`-h` +: show general usage (or after COMMAND, the command's usage) + +`--help` +: show the current program's manual as plain text (or after an add-on + COMMAND, the add-on's manual) + +`--man` +: show the current program's manual with man + +`--info` +: show the current program's manual with info + +`--version` +: show version + +`--debug[=N]` +: show debug output (levels 1-9, default: 1) + +`-f FILE --file=FILE` +: use a different input file. For stdin, use - + +`--rules-file=RULESFILE` +: Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW` +: display accounts named OLD as NEW + +`-I --ignore-assertions` +: ignore any failing balance assertions in the journal + +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` +: show, and match with -b/-e/-p/date:, secondary dates instead + +`-C --cleared` +: include only cleared postings/txns + +`--pending` +: include only pending postings/txns + +`-U --uncleared` +: include only uncleared (and pending) postings/txns + +`-R --real` +: include only non-virtual postings + +`--depth=N` +: hide accounts/postings deeper than N + +`-E --empty` +: show items with zero amount, normally hidden + +`-B --cost` +: convert amounts to their cost at transaction time (using the + [transaction price](journal.html#transaction-prices), if any) + +`--pivot TAG` +: will transform the journal before any other processing by replacing + the account name of every posting having the tag TAG with content + VALUE by the account name "TAG:VALUE". The TAG will only match if it + is a full-length match. The pivot will only happen if the TAG is on + a posting, not if it is on the transaction. If the tag value is a + multi:level:account:name the new account name will + be "TAG:multi:level:account:name". + +`--anon` +: show anonymized accounts and payees + +### ENVIRONMENT + +**LEDGER\_FILE** The journal file path when not specified with `-f`. +Default: `~/.hledger.journal` (on windows, perhaps +`C:/Users/USER/.hledger.journal`). + +### FILES + +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`). + +### BUGS + +The need to precede options with `--` when invoked from hledger is +awkward. + +`-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. + + +## hledger-api + +
+ +This doc is for version **1.1**. Available versions: +dev | +1.1 | +1.0 | +0.27 + +
+ +### NAME + +hledger-api - web API server for the hledger accounting tool + +### SYNOPSIS + +`hledger-api [OPTIONS]`\ +`hledger-api --swagger`\ +`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 +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. + +### OPTIONS + +Note: if invoking hledger-api as a hledger subcommand, write `--` before +options as shown above. + +`-d --static-dir=DIR` +: serve files from a different directory (default: `.`) + +`-p --port=PORT` +: use a different TCP port (default: 8001) + +`--swagger` +: print API docs in Swagger 2.0 format, and exit + +hledger general options: + +`-h` +: show general usage (or after COMMAND, the command's usage) + +`--help` +: show the current program's manual as plain text (or after an add-on + COMMAND, the add-on's manual) + +`--man` +: show the current program's manual with man + +`--info` +: show the current program's manual with info + +`--version` +: show version + +`--debug[=N]` +: show debug output (levels 1-9, default: 1) + +`-f FILE --file=FILE` +: use a different input file. For stdin, use - + +`--rules-file=RULESFILE` +: Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW` +: display accounts named OLD as NEW + +`-I --ignore-assertions` +: ignore any failing balance assertions in the journal + +### ENVIRONMENT + +**LEDGER\_FILE** The journal file path when not specified with `-f`. +Default: `~/.hledger.journal` (on windows, perhaps +`C:/Users/USER/.hledger.journal`). + +### FILES + +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`). + +### BUGS + +The need to precede options with `--` when invoked from hledger is +awkward. + + +## journal format + +
+ +This doc is for version **1.1**. Available versions: +dev | +1.1 | +1.0 | +0.27 + +
+ +### 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](http://en.wikipedia.org/wiki/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](faq.html#file-format-differences), of [ledger's journal +format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so +hledger can work with [compatible](faq.html#file-format-differences) +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](#add) or [web](#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: + +``` {.journal} +; 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/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 represented by journal entries. Each begins with a +[simple date](#simple-dates) in column 0, followed by three optional +fields with spaces between them: + +- a status flag, which can be empty or `!` or `*` (meaning + "uncleared", "pending" and "cleared", or whatever you want) +- a transaction code (eg a check number), +- and/or a description + +then some number of postings, of some amount to some account. Each +posting is on its own line, consisting of: + +- indentation of one or more spaces (or tabs) +- optionally, a `!` or `*` status flag followed by a space +- an account name, optionally containing single spaces +- optionally, two or more spaces or tabs followed by an amount + +Usually there are two or more postings, though one or none is also +possible. The posting amounts within a transaction must always balance, +ie add up to 0. Optionally one amount can be left blank, in which case +it will be inferred. + +#### 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](#default-year), 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](#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. + +``` {.journal} +2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking +``` + +``` {.shell} +$ hledger register checking +2010/02/23 movie ticket assets:checking $-10 $-10 +``` + +``` {.shell} +$ 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. + +##### Posting dates + +You can give individual postings a different date from their parent +transaction, by adding a [posting comment](#comments) containing a +[tag](#tags) (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: + +``` {.journal} +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 +``` + +``` {.shell} +$ hledger -f t.j register food +2015/05/30 expenses:food $10 $10 +``` + +``` {.shell} +$ hledger -f t.j register checking +2015/06/01 assets:checking $-10 $-10 +``` + +DATE should be a [simple date](#simple-dates); 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. + +#### 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](#account-aliases). + +#### 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](#prices), which are always +formatted as written). The display format is chosen as follows: + +- if there is a [commodity directive](#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. + +#### 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: + +``` {.journal} +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`. + +``` {.journal} +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](http://ledger-cli.org/3.0/doc/ledger3.html#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: + +``` {.journal} +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. + +##### 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. + +With [included files](#including-other-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. + +##### 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.) + +##### Assertions and subaccounts + +Balance assertions do not count the balance from subaccounts; they check +the posted account's exclusive balance. For example: + +``` {.journal} +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: + +``` {.shell} +$ hledger bal checking --flat + 1 checking + 1 checking:fund +-------------------- + 2 +``` + +##### Assertions and virtual postings + +Balance assertions are checked against all postings, both real and +[virtual](#virtual-postings). They are not affected by the `--real/-R` +flag or `real:` query. + +#### Balance Assignments + +[Ledger-style balance +assignments](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assignments) +are also supported. These are like [balance +assertions](#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: + +``` {.journal} +; 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: + +``` {.journal} +; 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. + +#### Prices + +##### Transaction prices + +Within a transaction posting, you can record an amount's price in +another commodity. This can be used to document the cost (for a +purchase), or selling price (for a sale), or the exchange rate that was +used, for this transaction. These transaction prices are fixed, and do +not change over time. + + +Amounts with transaction prices can be displayed in the transaction +price's commodity, by using the +[`--cost/-B`](hledger.html#reporting-options) flag supported by most +hledger commands (mnemonic: "cost Basis"). + +There are several ways to record a transaction price: + +1. Write the unit price (aka exchange rate), as `@ UNITPRICE` after the + amount: + + ``` {.journal} + 2009/1/1 + assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each + assets:cash + ``` + +2. Or write the total price, as `@@ TOTALPRICE` after the amount: + + ``` {.journal} + 2009/1/1 + assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot + assets:cash + ``` + +3. Or let hledger infer the price so as to balance the transaction. To + permit this, you must fully specify all posting amounts, and their + sum must have a non-zero amount in exactly two commodities: + + ``` {.journal} + 2009/1/1 + assets:foreign currency €100 ; one hundred euros + assets:cash $-135 ; exchanged for $135 + ``` + +With any of the above examples we get: + +``` {.shell} +$ hledger print -B +2009/01/01 + assets:foreign currency $135.00 + assets:cash $-135.00 +``` + +Example use for transaction prices: recording the effective conversion +rate of purchases made in a foreign currency. + +##### 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](https://en.wikipedia.org/wiki/Stock_exchange) or the [foreign +exchange market](https://en.wikipedia.org/wiki/Foreign_exchange_market). +Some commands ([balance](hledger.html#market-value), currently) can use +this information to show the market value of things at a given date. + +To record market prices, use P directives in the main journal or in an +[included](#including-other-files) file. Their format is: + +``` {.journal} +P DATE COMMODITYBEINGPRICED UNITPRICE +``` + + +DATE is a [simple date](#simple-dates) as usual. COMMODITYBEINGPRICED is +the symbol of the commodity being priced (just the symbol, no quantity). +UNITPRICE is an ordinary [amount](#amounts) (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: + +``` {.journal} +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](#multi-line-comments) 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: + +``` {.journal} +# 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 + +A *tag* is a word followed by a full colon inside a transaction or +posting [comment](#comments). You can write multiple tags, comma +separated. Eg: `; a comment containing sometag:, anothertag:`. You can +search for tags with the [`tag:` query](manual#queries). + +A tag can also have a value, which is any text between the colon and the +next comma or newline, excluding leading/trailing whitespace. (So +hledger tag values can not contain commas or newlines). + +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 (A, TAG2, third-tag, posting-tag): + +``` {.journal} +1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, this time with a value + (a) $1 ; posting-tag: +``` + +Tags are like Ledger's +[metadata](http://ledger-cli.org/3.0/doc/ledger3.html#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: + +- 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 [How to use account aliases](how-to-use-account-aliases.html). + +###### 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](#including-other-files). The spaces around the = are +optional: + +``` {.journal} +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: + +``` {.journal} +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. (This was the default behaviour in +hledger 0.24-0.25): + +``` {.journal} +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. Note, +currently regular expression aliases may cause noticeable slow-downs. +(And if you use Ledger on your hledger file, they will be ignored.) Eg: + +``` {.journal} +alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 +# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" +``` + +###### 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 + +###### end aliases + +You can clear (forget) all currently defined aliases with the +`end aliases` directive: + +``` {.journal} +end aliases +``` + +##### 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. + +``` {.journal} +; 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: + +``` {.journal} +apply account home + +2010/1/1 + food $10 + cash + +end apply account +``` + +which is equivalent to: + +``` {.journal} +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: + +``` {.journal} +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. + +##### Multi-line comments + +A line containing just `comment` starts a multi-line comment, and a line +containing just `end comment` ends it. See [comments](#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: + +``` {.journal} +; 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: + +``` {.journal} +; 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. + +``` {.journal} +# 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: + +``` {.journal} +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: + +``` {.journal} +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 +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 + + Vim <https://github.com/ledger/ledger/wiki/Getting-st + arte + d> + + Sublime Text <https://github.com/ledger/ledger/wiki/Using-Subl + ime- + Text> + + Textmate <https://github.com/ledger/ledger/wiki/Using-Text + Mate + -2> + + Text Wrangler   <https://github.com/ledger/ledger/wiki/Editing-Le + dger + -files-with-TextWrangler> + ----------------- ---------------------------------------------------- + + + + + +## csv format + +
+ +This doc is for version **1.1**. Available versions: +dev | 1.1 | +1.0 | +0.27 + +
+ +### NAME + +CSV - how hledger reads CSV data, and the CSV rules file format + +### DESCRIPTION + +hledger can read +[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) 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 [How to +read CSV files](how-to-read-csv-files.html). + +To learn about *exporting* CSV, see [CSV +output](hledger.html#csv-output). + +### CSV RULES + +The following six kinds of rule can appear in the rules file, in any +order. Blank lines and lines beginning with `#` or `;` are ignored. + +#### skip + +`skip`*`N`* + +Skip this number of CSV records at the beginning. You'll need this +whenever your CSV data contains header lines. Eg: + + + + +``` {.rules} +# ignore the first CSV line +skip 1 +``` + +#### 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](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime), +which must parse the date field values completely. Examples: + +``` {.rules .display-table} +# for dates like "6/11/2013": +date-format %-d/%-m/%Y +``` + +``` {.rules .display-table} +# for dates like "11/06/2013": +date-format %m/%d/%Y +``` + +``` {.rules .display-table} +# for dates like "2013-Nov-06": +date-format %Y-%h-%d +``` + +``` {.rules .display-table} +# for dates like "11/6/2013 11:32 PM": +date-format %-m/%-d/%Y %l:%M %p +``` + +#### 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`. Eg: + +``` {.rules} +# 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: + +``` {.rules .display-table} +# set the amount to the 4th CSV field with "USD " prepended +amount USD %4 +``` + +``` {.rules .display-table} +# 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 +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: + +``` {.rules .display-table} +# if the CSV record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries +``` + +``` {.rules .display-table} +# 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 + +`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} +# rules reused with several CSV files +include common.rules +``` + +### TIPS + +Each generated journal entry will have two postings, to `account1` and +`account2` respectively. Currently it's not possible to generate entries +with more than two postings. + +If the CSV has debit/credit amounts in separate fields, assign to the +`amount-in` and `amount-out` pseudo fields instead of `amount`. + +If the CSV has the currency in a separate field, assign that to the +`currency` pseudo field which will be automatically prepended to the +amount. (Or you can do the same thing with a field assignment.) + +If an amount value is parenthesised, it will be de-parenthesised and +sign-flipped automatically. + +The generated journal entries will be sorted by date. The original order +of same-day entries will be preserved, usually. + + + +## timeclock format + +
+ +This doc is for version **1.1**. Available versions: +dev | +1.1 | +1.0 | +0.27 + +
+ +### NAME + +Timeclock - the time logging format of timeclock.el, as read by hledger + +### DESCRIPTION + +hledger can read timeclock files. [As with +Ledger](http://ledger-cli.org/3.0/doc/ledger3.html#Time-Keeping), these +are (a subset of) +[timeclock.el](http://www.emacswiki.org/emacs/TimeClock)'s format, +containing clock-in and clock-out entries as in the example below. The +date is a [simple date](#simple-dates). 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). + +``` {.timeclock} +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: + +``` {.shell} +$ 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](https://raw.github.com/simonmichael/hledger/master/data/sample.timeclock) +to download and some queries to try: + +``` {.shell} +$ 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](http://www.emacswiki.org/emacs/timeclock-x.el) and + perhaps the extras in + [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/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](https://github.com/ledger/ledger/tree/maint/scripts). + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + + + +## timedot format + +
+ +This doc is for version **1.1**. Available versions: +dev | +1.1 | +1.0 | +0.27 + +
+ +### NAME + +Timedot - hledger's human-friendly time logging format + +### DESCRIPTION + +Timedot is a plain text format for logging dated, categorised quantities +(eg time), 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", the format does not specify the commodity being +logged, so could represent other dated, quantifiable things. Eg you +could record a single-entry journal of financial transactions, perhaps +slightly more conveniently than with hledger\_journal(5) format. + +### 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](#simple-dates) (see +hledger\_journal(5)). Categories are hledger-style account names, +optionally indented. There must be at least two spaces between the +category and the quantity. Quantities can be written in two ways: + +1. a series of dots (period characters). Each dot represents "a + quarter" - eg, a quarter hour. Spaces can be used to group dots into + hours, for easier counting. + +2. a number (integer or decimal), representing "units" - eg, hours. A + good alternative when dots are cumbersome. (A number also can record + negative quantities.) + +Blank lines and lines beginning with \#, ; or \* are ignored. An +example: + +``` {.timedot} +# 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: + +``` {.timedot} +2016/2/3 +inc:client1 4 +fos:hledger 3 +biz:research 1 +``` + +Reporting: + +``` {.shell} +$ hledger -f t.timedot print date:2016/2/2 +2016/02/02 * + (inc:client1) 2.00 + +2016/02/02 * + (biz:research) 0.25 +``` + +``` {.shell} +$ 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](#account-aliases): + +``` {.timedot} +2016/2/4 +fos.hledger.timedot 4 +fos.ledger .. +``` + +``` {.shell} +$ 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](https://raw.github.com/simonmichael/hledger/master/data/sample.timedot). + + + + + + + +